Class: Nanoc3::DataSource Abstract

Inherits:
Object
  • Object
show all
Extended by:
PluginRegistry::PluginMethods
Defined in:
lib/nanoc3/base/data_source.rb

Overview

This class is abstract.

Subclasses should at least implement #items and #layouts. If

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.

the data source should support creating items and layouts using the create_item and create_layout CLI commands, the #setup, #create<em>item and #create</em>layout methods should be implemented as well.

Direct Known Subclasses

Nanoc3::DataSources::Delicious, Nanoc3::DataSources::FilesystemUnified, Nanoc3::DataSources::FilesystemVerbose, Nanoc3::DataSources::LastFM, Nanoc3::DataSources::Twitter

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Methods included from PluginRegistry::PluginMethods

identifier, identifiers, named, register

Constructor Details

- (DataSource) initialize(site, items_root, layouts_root, config)

Creates a new data source for the given site.

returned by the #items method (comparable to mount points for filesystems in Unix-ish OSes).

layouts returned by the #layouts method (comparable to mount points for filesystems in Unix-ish OSes).

Parameters:

  • site (Nanoc3::Site) —

    The site this data source belongs to.

  • items_root (String) —

    The prefix that should be given to all items

  • layouts_root (String) —

    The prefix that should be given to all

  • config (Hash) —

    The configuration for this data source.



56
57
58
59
60
61
62
63
 
# File 'lib/nanoc3/base/data_source.rb', line 56

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)

online data sources could contain authentication details.

Returns:

  • (Hash) —

    The configuration for this data source. For example,



39
40
41
 
# File 'lib/nanoc3/base/data_source.rb', line 39

def config
  @config
end

- (String) items_root (readonly)

should be mounted.

Returns:

  • (String) —

    The root path where items returned by this data source



31
32
33
 
# File 'lib/nanoc3/base/data_source.rb', line 31

def items_root
  @items_root
end

- (String) layouts_root (readonly)

source should be mounted.

Returns:

  • (String) —

    The root path where layouts returned by this data



35
36
37
 
# File 'lib/nanoc3/base/data_source.rb', line 35

def layouts_root
  @layouts_root
end

Instance Method Details

- (void) create_item(content, attributes, identifier, params = {})

This method is abstract.

This method returns an undefined value.

Creates a new item with the given content, attributes and identifier. No instance of Item will be created; this method creates the item in the data source so that it can be loaded and turned into a Item instance by the #items method.

can be used to influence the way items are stored. For example, filesystem data sources could use this to pass the extension of the files that should be generated.

Parameters:

  • content (String)
  • attributes (Hash)
  • identifier (String)
  • params (Hash) (defaults to: {}) —

    Extra parameters to give to the data source. This



197
198
199
 
# File 'lib/nanoc3/base/data_source.rb', line 197

def create_item(content, attributes, identifier, params={})
  not_implemented('create_item')
end

- (void) create_layout(content, attributes, identifier, params = {})

This method is abstract.

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.

can be used to influence the way items are stored. For example, filesystem data sources could use this to pass the extension of the files that should be generated.

Parameters:

  • content (String)
  • attributes (Hash)
  • identifier (String)
  • params (Hash) (defaults to: {}) —

    Extra parameters to give to the data source. This



220
221
222
 
# File 'lib/nanoc3/base/data_source.rb', line 220

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.



123
124
 
# File 'lib/nanoc3/base/data_source.rb', line 123

def down
end

- (Array<Nanoc3::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.

Returns:



160
161
162
 
# File 'lib/nanoc3/base/data_source.rb', line 160

def items
  []
end

- (Array<Nanoc3::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.

Returns:



174
175
176
 
# File 'lib/nanoc3/base/data_source.rb', line 174

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.



73
74
75
76
77
78
 
# File 'lib/nanoc3/base/data_source.rb', line 73

def loading
  use
  yield
ensure
  unuse
end

- (void) setup

This method is abstract.

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.



135
136
137
 
# File 'lib/nanoc3/base/data_source.rb', line 135

def setup
  not_implemented('setup')
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).



99
100
101
102
 
# File 'lib/nanoc3/base/data_source.rb', line 99

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.



112
113
 
# File 'lib/nanoc3/base/data_source.rb', line 112

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.



147
148
 
# File 'lib/nanoc3/base/data_source.rb', line 147

def update
end

- (void) use

This method returns an undefined value.

Marks the data source as used by the caller.

Calling this method increases the internal reference count. When the data source is used for the first time (first #use call), the data source will be loaded (#up will be called).



87
88
89
90
 
# File 'lib/nanoc3/base/data_source.rb', line 87

def use
  up if @references == 0
  @references += 1
end