Class: Nanoc3::DataSource

Included Modules

Nanoc3::Plugin

Nanoc3::DataSource is responsible for loading data. It is the (abstract) superclass for all data sources. Subclasses must at least implement the data reading methods (items, layouts, and code_snippets); 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.

The setup method is used for setting up a site’s data source for the first time. This method should be overridden in subclasses.

Attributes

Instance Attributes

config [R] public

A hash containing the configuration for this data source.

items_root [R] public

A string containing the root where items returned by this data source should be mounted.

layouts_root [R] public

A string containing the root where layouts returned by this data source should be mounted.

Constants Inherited from Nanoc3::Plugin

MAP

Constants Included from Nanoc3::Plugin

MAP

Constructor Summary

public initialize(site, items_root, layouts_root, config)

Creates a new data source for the given site.

site:The site this data source belongs to.
items_root: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: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:The configuration for this data source.
[View source] 


41
42
43
44
45
46
47
48
 
# File 'lib/nanoc3/base/data_source.rb', line 41

def initialize(site, items_root, layouts_root, config)
  @site         = site
  @items_root   = items_root
  @layouts_root = layouts_root
  @config       = config

  @references = 0
end

Public Visibility

Public Class Method Summary

identifier(identifier)

Sets the identifier for this data source.

identifiers(*identifiers)

Sets the identifiers for this data source.

register(class_or_name, *identifiers)

Registers the given class as a data source with the given identifier.

Public Class Methods Inherited from Nanoc3::Plugin

all, named

Public Instance Method Summary

#code_snippets

Returns the custom code snippets (represented by Nanoc3::CodeSnippet) for this site.

#create_item(content, attributes, identifier)

Creating data Creates a new item with the given content, attributes and identifier.

#create_layout(content, attributes, identifier)

Creates a new layout with the given content, attributes and identifier.

#down

Brings down the connection to the data.

#items

Loading data Returns the list of items (represented by Nanoc3::Item) in this site.

#layouts

Returns the list of layouts (represented by Nanoc3::Layout) in this site.

#loading

Loads the data source when necessary (calling up), yields, and unloads the data source when it is not being used elsewhere.

#setup

Creating/updating Creates the bare minimum essentials for this data source to work.

#unuse

Marks the data source as unused by the caller.

#up

Loading and unloading Brings up the connection to the data.

#update

Updated the content stored in this site to a newer version.

#use

Marks the data source as used by the caller.

Public Class Method Details

identifier

public identifier(identifier)

Sets the identifier for this data source.

[View source] 


56
57
58
 
# File 'lib/nanoc3/base/data_source.rb', line 56

def self.identifier(identifier)
  Nanoc3::DataSource.register(self, identifier)
end

identifiers

public identifiers(*identifiers)

Sets the identifiers for this data source.

[View source] 


51
52
53
 
# File 'lib/nanoc3/base/data_source.rb', line 51

def self.identifiers(*identifiers)
  Nanoc3::DataSource.register(self, *identifiers)
end

register

public register(class_or_name, *identifiers)

Registers the given class as a data source with the given identifier.

[View source] 


61
62
63
 
# File 'lib/nanoc3/base/data_source.rb', line 61

def self.register(class_or_name, *identifiers)
  Nanoc3::Plugin.register(Nanoc3::DataSource, class_or_name, *identifiers)
end

Public Instance Method Details

code_snippets

public code_snippets

Returns the custom code snippets (represented by Nanoc3::CodeSnippet) for this site. The default implementation simply returns an empty array. This can be code for custom filters and more, but pretty much any code can be put in there (global helper functions are very useful).

Subclasses may implement this method.

[View source] 


172
173
174
 
# File 'lib/nanoc3/base/data_source.rb', line 172

def code_snippets
  []
end

create_item

public create_item(content, attributes, identifier)

Creating data Creates a new item with the given content, attributes and identifier.

[View source] 


179
180
181
 
# File 'lib/nanoc3/base/data_source.rb', line 179

def create_item(content, attributes, identifier)
  not_implemented('create_item')
end

create_layout

public create_layout(content, attributes, identifier)

Creates a new layout with the given content, attributes and identifier.

[View source] 


184
185
186
 
# File 'lib/nanoc3/base/data_source.rb', line 184

def create_layout(content, attributes, identifier)
  not_implemented('create_layout')
end

down

public down

Brings down the connection to the data. This is an abstract method implemented by the subclass. This method should undo the effects of up.

Subclasses may implement this method.

[View source] 


118
119
 
# File 'lib/nanoc3/base/data_source.rb', line 118

def down
end

items

public items

Loading data Returns the list of items (represented by Nanoc3::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 implement this method.

[View source] 


151
152
153
 
# File 'lib/nanoc3/base/data_source.rb', line 151

def items
  []
end

layouts

public layouts

Returns the list of layouts (represented by Nanoc3::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 implement this method.

[View source] 


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

def layouts
  []
end

loading

public loading

Loads the data source when necessary (calling up), yields, and unloads 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.

Meta Tags

Yields:

[View source] 


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

def loading
  use
  yield
ensure
  unuse
end

setup

public setup

Creating/updating 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, if you’re using a database, this is where you should create the necessary tables for the data source to function properly.

Subclasses must implement this method.

[View source] 


130
131
132
 
# File 'lib/nanoc3/base/data_source.rb', line 130

def setup
  not_implemented('setup')
end

unuse

public unuse

Marks the data source as unused 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). Similarly, when the reference count reaches zero, the data source will be unloaded (#down will be called).

[View source] 


97
98
99
100
 
# File 'lib/nanoc3/base/data_source.rb', line 97

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

up

public up

Loading and unloading Brings up the connection to the data. This is an abstract method implemented by the subclass. 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 implement this method.

[View source] 


110
111
 
# File 'lib/nanoc3/base/data_source.rb', line 110

def up
end

update

public update

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 implement this method.

[View source] 


139
140
 
# File 'lib/nanoc3/base/data_source.rb', line 139

def update
end

use

public use

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). Similarly, when the reference count reaches zero, the data source will be unloaded (#down will be called).

[View source] 


85
86
87
88
 
# File 'lib/nanoc3/base/data_source.rb', line 85

def use
  up if @references == 0
  @references += 1
end
Generated on Sunday, August 09 2009 at 01:43:11 PM by YARD 0.2.3.2 (ruby-1.8.7).