Class: Nanoc::DataSource Abstract
- Inherits:
-
Object
- Object
- Nanoc::DataSource
- Extended by:
- PluginRegistry::PluginMethods
- Defined in:
- lib/nanoc/base/source_data/data_source.rb
Overview
Subclasses should at least implement #items and #layouts. If
the data source should support creating items and layouts using the
create_item
and create_layout
CLI commands, the #setup,
#create_item and #create_layout methods should be implemented as
well.
Responsible for loading site data. It is the (abstract) superclass for all data sources. Subclasses must at least implement the data reading methods (#items and #layouts); all other methods involving data manipulation are optional.
Apart from the methods for loading and storing data, there are the #up and #down methods for bringing up and tearing down the connection to the data source. These should be overridden in subclasses. The #loading method wraps #up and #down. #loading is a convenience method for the more low-level methods #use and #unuse, which respectively increment and decrement the reference count; when the reference count goes from 0 to 1, the data source will be loaded (#up will be called) and when the reference count goes from 1 to 0, the data source will be unloaded (#down will be called).
The #setup method is used for setting up a site’s data source for the first time.
Direct Known Subclasses
Nanoc::DataSources::Delicious, Nanoc::DataSources::FilesystemUnified, Nanoc::DataSources::FilesystemVerbose, Nanoc::DataSources::LastFM, Nanoc::DataSources::Static, Nanoc::DataSources::Twitter
Instance Attribute Summary (collapse)
-
- (Hash) config
readonly
The configuration for this data source.
-
- (String) items_root
readonly
The root path where items returned by this data source should be mounted.
-
- (String) layouts_root
readonly
The root path where layouts returned by this data source should be mounted.
Instance Method Summary (collapse)
-
- (void) create_item(content, attributes, identifier, params = {})
abstract
Creates a new item with the given content, attributes and identifier.
-
- (void) create_layout(content, attributes, identifier, params = {})
abstract
Creates a new layout with the given content, attributes and identifier.
-
- (void) down
Brings down the connection to the data.
-
- (DataSource) initialize(site, items_root, layouts_root, config)
constructor
Creates a new data source for the given site.
-
- (Array<Nanoc::Item>) items
Returns the list of items (represented by Item) in this site.
-
- (Array<Nanoc::Layout>) layouts
Returns the list of layouts (represented by Layout) in this site.
- - (void) loading
-
- (void) setup
abstract
Creates the bare minimum essentials for this data source to work.
-
- (void) sync
Sync the content for this data source with an external source.
-
- (void) unuse
Marks the data source as unused by the caller.
-
- (void) up
Brings up the connection to the data.
-
- (void) update
Updated the content stored in this site to a newer version.
-
- (void) use
Marks the data source as used by the caller.
Methods included from PluginRegistry::PluginMethods
all, identifier, identifiers, named, register
Constructor Details
- (DataSource) initialize(site, items_root, layouts_root, config)
Creates a new data source for the given site.
57 58 59 60 61 62 63 64 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 57 def initialize(site, items_root, layouts_root, config) @site = site @items_root = items_root @layouts_root = layouts_root @config = config || {} @references = 0 end |
Instance Attribute Details
- (Hash) config (readonly)
Returns The configuration for this data source. For example, online data sources could contain authentication details.
40 41 42 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 40 def config @config end |
- (String) items_root (readonly)
Returns The root path where items returned by this data source should be mounted.
32 33 34 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 32 def items_root @items_root end |
- (String) layouts_root (readonly)
Returns The root path where layouts returned by this data source should be mounted.
36 37 38 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 36 def layouts_root @layouts_root end |
Instance Method Details
- (void) create_item(content, attributes, identifier, params = {})
210 211 212 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 210 def create_item(content, attributes, identifier, params = {}) not_implemented('create_item') end |
- (void) create_layout(content, attributes, identifier, params = {})
This method returns an undefined value.
Creates a new layout with the given content, attributes and identifier. No instance of Layout will be created; this method creates the layout in the data source so that it can be loaded and turned into a Layout instance by the #layouts method.
233 234 235 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 233 def create_layout(content, attributes, identifier, params = {}) not_implemented('create_layout') end |
- (void) down
This method returns an undefined value.
Brings down the connection to the data. This method should undo the effects of the #up method. For example, a database connection established in #up should be closed in this method.
Subclasses may override this method, but are not required to do so; the default implementation simply does nothing.
124 125 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 124 def down end |
- (Array<Nanoc::Item>) items
Returns the list of items (represented by Item) in this site. The default implementation simply returns an empty array.
Subclasses should not prepend items_root
to the item’s identifiers, as
this will be done automatically.
Subclasses may override this method, but are not required to do so; the default implementation simply does nothing.
173 174 175 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 173 def items [] end |
- (Array<Nanoc::Layout>) layouts
Returns the list of layouts (represented by Layout) in this site. The default implementation simply returns an empty array.
Subclasses should prepend layout_root
to the layout’s identifiers,
since this is not done automatically.
Subclasses may override this method, but are not required to do so; the default implementation simply does nothing.
187 188 189 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 187 def layouts [] end |
- (void) loading
This method returns an undefined value.
Loads the data source when necessary (calling #up), yields, and unloads (using #down) the data source when it is not being used elsewhere. All data source queries and data manipulations should be wrapped in a #loading block; it ensures that the data source is loaded when necessary and makes sure the data source does not get unloaded while it is still being used elsewhere.
74 75 76 77 78 79 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 74 def loading use yield ensure unuse end |
- (void) setup
This method returns an undefined value.
Creates the bare minimum essentials for this data source to work. This action will likely be destructive. This method should not create sample data such as a default home page, a default layout, etc. For example, when using a database, this is where you should create the necessary tables for the data source to function properly.
136 137 138 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 136 def setup not_implemented('setup') end |
- (void) sync
This method returns an undefined value.
Sync the content for this data source with an external source.
This method is called by the nanoc sync
command so that data sources may
update local caches of external data, such as items fetched from
third-party APIs.
Subclasses may override this method, but are not required to do so; the default implementation simply does nothing.
160 161 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 160 def sync end |
- (void) unuse
This method returns an undefined value.
Marks the data source as unused by the caller.
Calling this method decreases the internal reference count. When the reference count reaches zero, i.e. when the data source is not used any more, the data source will be unloaded (#down will be called).
100 101 102 103 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 100 def unuse @references -= 1 down if @references == 0 end |
- (void) up
This method returns an undefined value.
Brings up the connection to the data. Depending on the way data is stored, this may not be necessary. This is the ideal place to connect to the database, for example.
Subclasses may override this method, but are not required to do so; the default implementation simply does nothing.
113 114 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 113 def up end |
- (void) update
This method returns an undefined value.
Updated the content stored in this site to a newer version. A newer version of a data source may store content in a different format, and this method will update the stored content to this newer format.
Subclasses may override this method, but are not required to do so; the default implementation simply does nothing.
148 149 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 148 def update end |
- (void) use
88 89 90 91 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 88 def use up if @references == 0 @references += 1 end |