Class: Nanoc3::DataSource Abstract

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

Overview

This class is abstract.

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.

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from PluginRegistry::PluginMethods

identifier, identifiers, named, register

Constructor Details

#initialize(site, items_root, layouts_root, config) ⇒ DataSource

Creates a new data source for the given site.

Parameters:

  • site (Nanoc3::Site) —

    The site this data source belongs to.

  • items_root (String) —

    The prefix that should be given to all items returned by the #items method (comparable to mount points for filesystems in Unix-ish OSes).

  • layouts_root (String) —

    The prefix that should be given to all layouts returned by the #layouts method (comparable to mount points for filesystems in Unix-ish OSes).

  • config (Hash) —

    The configuration for this data source.



57
58
59
60
61
62
63
64
 
# File 'lib/nanoc3/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

#config ⇒ Hash (readonly)

Returns The configuration for this data source. For example, online data sources could contain authentication details.

Returns:

  • (Hash) —

    The configuration for this data source. For example, online data sources could contain authentication details.



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

def config
  @config
end

#items_root ⇒ String (readonly)

Returns The root path where items returned by this data source should be mounted.

Returns:

  • (String) —

    The root path where items returned by this data source should be mounted.



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

def items_root
  @items_root
end

#layouts_root ⇒ String (readonly)

Returns The root path where layouts returned by this data source should be mounted.

Returns:

  • (String) —

    The root path where layouts returned by this data source should be mounted.



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

def layouts_root
  @layouts_root
end

Instance Method Details

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

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.

Parameters:

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

    Extra parameters to give to the data source. This 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.



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

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

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

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.

Parameters:

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

    Extra parameters to give to the data source. This 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.



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

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

#down ⇒ void

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/nanoc3/base/source_data/data_source.rb', line 124

def down
end

#items ⇒ Array<Nanoc3::Item>

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:



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

def items
  []
end

#layouts ⇒ Array<Nanoc3::Layout>

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:



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

def layouts
  []
end

#loading ⇒ void

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/nanoc3/base/source_data/data_source.rb', line 74

def loading
  use
  yield
ensure
  unuse
end

#setup ⇒ void

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.



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

def setup
  not_implemented('setup')
end

#unuse ⇒ void

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/nanoc3/base/source_data/data_source.rb', line 100

def unuse
  @references -= 1
  down if @references == 0
end

#up ⇒ void

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/nanoc3/base/source_data/data_source.rb', line 113

def up
end

#update ⇒ void

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/nanoc3/base/source_data/data_source.rb', line 148

def update
end

#use ⇒ void

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).



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

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