Class: Nanoc2::DataSource

Inherits:
Plugin
  • Object
show all
Defined in:
lib/nanoc2/base/data_source.rb

Overview

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

Constant Summary

Constants inherited from Plugin

Plugin::MAP

Instance Method Summary collapse

Methods inherited from Plugin

identifier, identifiers, named, register

Constructor Details

#initialize(site) ⇒ DataSource

Creates a new data source for the given site.



18
19
20
21
 
# File 'lib/nanoc2/base/data_source.rb', line 18

def initialize(site)
  @site       = site
  @references = 0
end

Instance Method Details

#asset_defaults ⇒ Object

Returns the asset defaults (represented by Nanoc2::AssetDefaults) of this site. This is an abstract method implemented by the subclass.

Subclasses must implement this method.



178
179
180
 
# File 'lib/nanoc2/base/data_source.rb', line 178

def asset_defaults
  not_implemented('asset_defaults')
end

#assets ⇒ Object

Returns the list of assets (represented by Nanoc2::Asset) in this site. This is an abstract method implemented by the subclass.

Subclasses must implement this method.



128
129
130
 
# File 'lib/nanoc2/base/data_source.rb', line 128

def assets
  not_implemented('assets')
end

#code ⇒ Object

Returns the custom code (represented by Nanoc2::Code) for this site. This is an abstract method implemented by the subclass. This can be code for custom filters, routers, and more, but pretty much any code can be put in there (global helper functions are very useful).

Subclasses must implement this method.



265
266
267
 
# File 'lib/nanoc2/base/data_source.rb', line 265

def code
  not_implemented('code')
end

#delete_asset(asset) ⇒ Object

Removes the given asset from the data source.

Subclasses must implement this method.



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

def delete_asset(asset)
  not_implemented('delete_asset')
end

#delete_layout(layout) ⇒ Object

Removes the given layout from the data source.

Subclasses must implement this method.



219
220
221
 
# File 'lib/nanoc2/base/data_source.rb', line 219

def delete_layout(layout)
  not_implemented('delete_layout')
end

#delete_page(page) ⇒ Object

Removes the given page from the data source.

Subclasses must implement this method.



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

def delete_page(page)
  not_implemented('delete_page')
end

#delete_template(template) ⇒ Object

Removes the given template from the data source.

Subclasses must implement this method.



253
254
255
 
# File 'lib/nanoc2/base/data_source.rb', line 253

def delete_template(template)
  not_implemented('delete_template')
end

#destroy ⇒ Object

Removes all data stored by this data source. This method undoes the effects of the setup method.

Subclasses must implement this method.



77
78
79
 
# File 'lib/nanoc2/base/data_source.rb', line 77

def destroy
  not_implemented('destroy')
end

#down ⇒ Object

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.



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

def down
end

#layouts ⇒ Object

Returns the list of layouts (represented by Nanoc2::Layout) in this site. This is an abstract method implemented by the subclass.

Subclasses must implement this method.



195
196
197
 
# File 'lib/nanoc2/base/data_source.rb', line 195

def layouts
  not_implemented('layouts')
end

#loading ⇒ Object

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.



29
30
31
32
33
34
35
36
37
38
39
 
# File 'lib/nanoc2/base/data_source.rb', line 29

def loading
  # Load if necessary
  up if @references == 0
  @references += 1

  yield
ensure
  # Unload if necessary
  @references -= 1
  down if @references == 0
end

#move_asset(asset, new_path) ⇒ Object

Changes the path of the given asset to the given new path. When changing a asset’s path, this method must be used (save_asset will not work).

Subclasses must implement this method.



144
145
146
 
# File 'lib/nanoc2/base/data_source.rb', line 144

def move_asset(asset, new_path)
  not_implemented('move_asset')
end

#move_layout(layout, new_path) ⇒ Object

Changes the path of the given layout to the given new path. When changing a layout’s path, this method must be used (save_layout will not work).

Subclasses must implement this method.



212
213
214
 
# File 'lib/nanoc2/base/data_source.rb', line 212

def move_layout(layout, new_path)
  not_implemented('move_layout')
end

#move_page(page, new_path) ⇒ Object

Changes the path of the given page to the given new path. When changing a page’s path, this method must be used (save_page will not work).

Subclasses must implement this method.



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

def move_page(page, new_path)
  not_implemented('move_page')
end

#move_template(template, new_name) ⇒ Object

Changes the name of the given template to the given new name. When changing a template’s name, this method must be used (save_template will not work).

Subclasses must implement this method.



246
247
248
 
# File 'lib/nanoc2/base/data_source.rb', line 246

def move_template(template, new_name)
  not_implemented('move_template')
end

#page_defaults ⇒ Object

Returns the page defaults (represented by Nanoc2::PageDefaults) of this site. This is an abstract method implemented by the subclass.

Subclasses must implement this method.



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

def page_defaults
  not_implemented('page_defaults')
end

#pages ⇒ Object

Returns the list of pages (represented by Nanoc2::Page) in this site. This is an abstract method implemented by the subclass.

Subclasses must implement this method.



95
96
97
 
# File 'lib/nanoc2/base/data_source.rb', line 95

def pages
  not_implemented('pages')
end

#save_asset(asset) ⇒ Object

Saves the given asset in the data source, creating it if it doesn’t exist yet and updating the existing copy otherwise.

Subclasses must implement this method.



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

def save_asset(asset)
  not_implemented('save_asset')
end

#save_asset_defaults(asset_defaults) ⇒ Object

Saves the given asset defaults in the data source.

Subclasses must implement this method.



185
186
187
 
# File 'lib/nanoc2/base/data_source.rb', line 185

def save_asset_defaults(asset_defaults)
  not_implemented('save_asset_defaults')
end

#save_code(code) ⇒ Object

Saves the given code in the data source.

Subclasses must implement this method.



272
273
274
 
# File 'lib/nanoc2/base/data_source.rb', line 272

def save_code(code)
  not_implemented('save_code')
end

#save_layout(layout) ⇒ Object

Saves the given layout in the data source, creating it if it doesn’t exist yet and updating the existing copy otherwise.

Subclasses must implement this method.



203
204
205
 
# File 'lib/nanoc2/base/data_source.rb', line 203

def save_layout(layout)
  not_implemented('save_layout')
end

#save_page(page) ⇒ Object

Saves the given page in the data source, creating it if it doesn’t exist yet and updating the existing copy otherwise.

Subclasses must implement this method.



103
104
105
 
# File 'lib/nanoc2/base/data_source.rb', line 103

def save_page(page)
  not_implemented('save_page')
end

#save_page_defaults(page_defaults) ⇒ Object

Saves the given page defaults in the data source.

Subclasses must implement this method.



168
169
170
 
# File 'lib/nanoc2/base/data_source.rb', line 168

def save_page_defaults(page_defaults)
  not_implemented('save_page_defaults')
end

#save_template(template) ⇒ Object

Saves the given template in the data source, creating it if it doesn’t exist yet and updating the existing copy otherwise.

Subclasses must implement this method.



237
238
239
 
# File 'lib/nanoc2/base/data_source.rb', line 237

def save_template(template)
  not_implemented('save_template')
end

#setup ⇒ Object

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.



69
70
71
 
# File 'lib/nanoc2/base/data_source.rb', line 69

def setup
  not_implemented('setup')
end

#templates ⇒ Object

Returns the list of templates (represented by Nanoc2::Template) in this site. This is an abstract method implemented by the subclass.

Subclasses must implement this method.



229
230
231
 
# File 'lib/nanoc2/base/data_source.rb', line 229

def templates
  not_implemented('templates')
end

#up ⇒ Object

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.



49
50
 
# File 'lib/nanoc2/base/data_source.rb', line 49

def up
end

#update ⇒ Object

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.



86
87
 
# File 'lib/nanoc2/base/data_source.rb', line 86

def update
end