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.
55 56 57 58 59 60 61 62 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 55 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.
38 39 40 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 38 def config @config end |
- (String) items_root (readonly)
Returns The root path where items returned by this data source should be mounted.
30 31 32 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 30 def items_root @items_root end |
- (String) layouts_root (readonly)
Returns The root path where layouts returned by this data source should be mounted.
34 35 36 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 34 def layouts_root @layouts_root end |
Instance Method Details
- (void) create_item(content, attributes, identifier, params = {})
208 209 210 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 208 def create_item(content, attributes, identifier, params = {}) # rubocop:disable Lint/UnusedMethodArgument 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.
231 232 233 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 231 def create_layout(content, attributes, identifier, params = {}) # rubocop:disable Lint/UnusedMethodArgument 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.
122 123 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 122 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.
171 172 173 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 171 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.
185 186 187 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 185 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.
72 73 74 75 76 77 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 72 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.
134 135 136 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 134 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.
158 159 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 158 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).
98 99 100 101 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 98 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.
111 112 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 111 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.
146 147 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 146 def update end |
- (void) use
86 87 88 89 |
# File 'lib/nanoc/base/source_data/data_source.rb', line 86 def use up if @references == 0 @references += 1 end |