API Docs for:
Show:

DocumentModel Class

The DocumentModel class is DocPad's representation of a website or project's content files. This can be individual web pages or blog posts etc. Generally, this is not other website files such as css files, images, or scripts - unless there is a requirement to have DocPad do transformation on these files. Extends the DocPad FileModel class https://github.com/docpad/docpad/blob/master/src/lib/models/file.coffee DocumentModel primarily handles the rendering and parsing of document files. This includes merging the document with layouts and managing the rendering from one file extension to another. The class inherits many of the file specific operations and DocPad specific attributes from the FileModel class. However, it also overrides some parsing and file output operations contained in the FileModel class.

Typically we do not need to create DocumentModels ourselves as DocPad handles all of that. Most of the time when we encounter DocumentModels is when querying DocPad's document collections either in the docpad.coffee file or from within a template.

indexDoc = @getCollection('documents').findOne({relativeOutPath: 'index.html'})

A plugin, however, may need to create a DocumentModel depending on its requirements. In such a case it is wise to use the built in DocPad methods to do so, in particular docpad.createModel

#check to see if the document alread exists ie its an update
docModel = @docpad.getCollection('posts').findOne({slug: 'some-slug'})

#if so, load the existing document ready for regeneration
if docModel
    docModel.load()
else
    #if document doesn't already exist, create it and add to database
    docModel = @docpad.createModel({fullPath:'file/path/to/somewhere'})
    docModel.load()

Constructor

DocumentModel

()

Methods

action

(
  • next
  • opts
)

Inherited from FileModel but overwritten in src/lib/interfaces/console.coffee:694

Do action

Parameters:

  • next Function
  • opts Object

addUrl

(
  • url
)
A file can have multiple urls. This method adds either a single url or an array of urls to the file model.

Parameters:

  • url String or Array

choose

(
  • message
  • choices
  • [opts={}]
  • next
)

Choose something

Parameters:

  • message String
  • choices Object
  • [opts={}] Object optional
  • next Function

clean

(
  • next
)

Clean method

Parameters:

  • next Function

clone

() Object
Clone the model and return the newly cloned model.

Returns:

Object: cloned file model

confirm

(
  • message
  • [opts={}]
  • next
)

Confirm an option

Parameters:

  • message String
  • [opts={}] Object optional
  • next Function

constructor

(
  • opts
  • next
)
private

Constructor method. Setup the CLI

Parameters:

  • opts Object
  • next Function

contextualize

(
  • [opts={}]
  • next
)

Inherited from FileModel but overwritten in src/lib/models/document.coffee:375

Contextualize the data. In other words, put our data into the perspective of the bigger picture of the data. For instance, generate the url for it's rendered equivalant. next(err)

Parameters:

  • [opts={}] Object optional
  • next Object

    callback

delete

(
  • [opts]
  • next
)
Delete the out file, perhaps ahead of regeneration. Optionally pass the opts parameter to set the file path or type. next(err)

Parameters:

  • [opts] Object optional
  • next Object
    callback

deleteSource

(
  • [opts]
  • next
)
Delete the source file. Optionally pass the opts parameter to set the file path or type. next(err)

Parameters:

  • [opts] Object optional
  • next Object
    callback

destroy

(
  • err
)

Destructor.

Parameters:

  • err Object

encode

(
  • opts
)
Object private
File encoding helper opts = {path, to, from, content}

Parameters:

  • opts Object

Returns:

Object: encoded result

extractConfig

(
  • [customConfig={}]
)
Object

Extract Configuration

Parameters:

  • [customConfig={}] Object optional

Returns:

Object:

the DocPad config

extractOptions

(
  • attrs
)
Object private
Extract Options.

Parameters:

  • attrs Object

Returns:

Object: the options object

generate

(
  • next
)

Generate action

Parameters:

  • next Function

getActionRunner

() Object
Get the action runner instance bound to DocPad

Returns:

Object:

getAttributes

(
  • [dereference=true]
)
Object
Get the file model attributes. By default the attributes will be dereferenced from the file model. To maintain a reference, pass false as the parameter. The returned object will NOT contain the file model's ID attribute.

Parameters:

  • [dereference=true] Object optional

Returns:

Object:

getBuffer

() Object
Get the file model's buffer object. Returns a node.js buffer object.

Returns:

Object: node.js buffer object

getCommander

()

Get the commander

Returns:

the commander instance

getContent

() String or Object
Get the file content. This will be the text content if loaded or the file buffer object.

Returns:

String or Object:

getEve

(
  • next
)

Get the most ancestoral (root) layout we have - ie, the very top one. Often this will be the base or default layout for a project. The layout where the head and other html on all pages is defined. In some projects, however, there may be more than one root layout so we can't assume there will always only be one. This is used by the contextualize method to determine the output extension of the document. In other words the document's final output extension is determined by the root layout. next(err,layout)

Parameters:

  • next Function

getExtensions

(
  • opts
)
Array
Get file extensions. Depending on the parameters passed this will either be the file model's extensions property or the extensions extracted from the file model's filename property. The opts parameter is passed in the format: {extensions,filename}.

Parameters:

  • opts Object

Returns:

Array: array of extension names

getFilename

(
  • [opts={}]
)
String
Get the file name. Depending on the parameters passed this will either be the file model's filename property or, the filename determined from the fullPath or relativePath property. Valid values for the opts parameter are: fullPath, relativePath or filename. Format: {filename}

Parameters:

  • [opts={}] Object optional

Returns:

String:

getFilePath

(
  • [opts={}]
)
String
Get the file path. Depending on the parameters passed this will either be the file model's fullPath property, the relativePath property or the filename property. Valid values for the opts parameter are: fullPath, relativePath or filename. Format: {fullPath}

Parameters:

  • [opts={}] Object optional

Returns:

String:

getLayout

(
  • next
)

Get the layout object that this file references (if any). We update the layoutRelativePath as it is used for finding what documents are used by a layout for when a layout changes. next(err, layout)

Parameters:

  • next Function

    callback

getLocale

() Object
Get the file's locale information

Returns:

Object: the locale

getMeta

(
  • [args...]
)
Object
Get the file model metadata object. Optionally pass a list of metadata property names corresponding to those properties that you want returned.

Parameters:

  • [args...] Object optional

Returns:

Object:

getOptions

() Object private
Get Options. Returns an object containing the properties detectEncoding, rootOutDirPath locale, stat, buffer, meta and TaskGroup.

Returns:

Object:

getOutContent

() String or Object

Inherited from FileModel but overwritten in src/lib/models/document.coffee:149

Get the file content for output. This will be the text content AFTER it has been through the rendering process. If this has been called before the rendering process, then the raw text content will be returned, or, if early enough in the process, the file buffer object.

Returns:

String or Object:

getPath

(
  • relativePath
  • parentPath
)
String
Get a file path. If the relativePath parameter starts with . then we get the path in relation to the document that is calling it. Otherwise we just return it as normal

Parameters:

  • relativePath String
  • parentPath String

Returns:

String:

getStat

() Object
Get the node.js file stat.

Returns:

Object: the file stat

hasLayout

() Boolean

Checks if the file has a layout.

Returns:

Boolean:

help

(
  • next
)

Help method

Parameters:

  • next Function

info

(
  • next
)

Info method

Parameters:

  • next Function

init

(
  • next
)

Action initialise

Parameters:

  • next Function

initialize

(
  • attrs
  • [opts={}]
)
Initialize the file model with the passed attributes and options. Emits the init event.

Parameters:

  • attrs Object
    the file model attributes
  • [opts={}] Object optional
    the file model options

install

(
  • next
  • opts
)

Install method

Parameters:

  • next Function
  • opts Object

isBinary

() Boolean
Is this a binary file?

Returns:

Boolean:

isBufferOutdated

() Boolean
Is Buffer Outdated True if there is no buffer OR the buffer time is outdated

Returns:

Boolean:

isOption

(
  • key
)
Boolean private
Checks whether the passed key is one of the options.

Parameters:

  • key String

Returns:

Boolean:

isText

() Boolean
Is this a text file? ie - not a binary file.

Returns:

Boolean:

load

(
  • [opts={}]
  • next
)
Load the file from the file system. If the fullPath exists, load the file. If it doesn't, then parse and normalize the file. Optionally pass file options as a parameter.

Parameters:

  • [opts={}] Object optional
  • next Function
    callback

normalize

(
  • [opts={}]
  • next
)

Inherited from FileModel but overwritten in src/lib/models/document.coffee:345

Normalize any parsing we have done, because if a value has updates it may have consequences on another value. This will ensure everything is okay. next(err)

Parameters:

  • [opts={}] Object optional
  • next Object

    callback

parse

(
  • [opts={}]
  • next
)

Inherited from FileModel but overwritten in src/lib/models/document.coffee:181

Parse our buffer and extract meaningful data from it. next(err).

Parameters:

  • [opts={}] Object optional
  • next Object

    callback

performAction

(
  • action
  • args
  • [config={}]
)

Perform Action

Parameters:

  • action Object
  • args Object
  • [config={}] Object optional

prompt

(
  • message
  • [opts={}]
  • next
)

Prompt for input

Parameters:

  • message String
  • [opts={}] Object optional
  • next Function

referencesOthers

(
  • [flag=true]
)

Set flag to indicate if the document contains references to other documents. Used in the rendering process to decide on whether to render this document when another document is updated.

Parameters:

  • [flag=true] Boolean optional

removeUrl

(
  • userUrl
)
Removes a url from the file model (files can have more than one url).

Parameters:

  • userUrl Object
    the url to be removed

render

(
  • [opts={}]
  • next
)

Triggers the render process for this document. Calls the renderExtensions, renderDocument and renderLayouts methods in sequence. This is the method you want to call if you want to trigger the rendering of a document manually.

The rendered content is returned as the result parameter to the passed callback and the DocumentModel instance is returned in the document parameter. next(err,result,document)

Parameters:

  • [opts={}] Object optional
  • next Function

    callback

render

(
  • next
  • opts
)

Inherited from FileModel but overwritten in src/lib/interfaces/console.coffee:804

Render method

Parameters:

  • next Function
  • opts Object

renderDocument

(
  • opts
  • next
)
private

Triggers the renderDocument event after all extensions have been rendered. Listeners can use this event to perform transformations on the already rendered content.

Parameters:

  • opts Object
  • next Function

    callback

renderExtensions

(
  • opts
  • next
)
private

Renders one extension to another depending on the document model's extensions property. Triggers the render event for each extension conversion. This is the point where the various templating systems listen for their extension and perform their conversions. Common extension conversion is from md to html. So the document source file maybe index.md.html. This will be a markdown file to be converted to HTML. However, documents can be rendered through more than one conversion. Index.html.md.eco will be rendered from eco to md and then from md to html. Two conversions. next(err,result)

Parameters:

  • opts Object
  • next Function

    callback

renderLayouts

(
  • opts
  • next
)
private

Render and merge layout content. Merge layout metadata with document metadata. Return the resulting merged content to the callback result parameter. next(err,result)

Parameters:

  • opts Object
  • next Function

    callback

run

(
  • next
)

Run method

Parameters:

  • next Function

selectSkeletonCallback

(
  • skeletonsCollection
  • next
)

Select a skeleton

Parameters:

  • skeletonsCollection Object
  • next Function

server

(
  • next
)

Server method

Parameters:

  • next Function

set

(
  • attrs
  • opts
)
Assign attributes and options to the file model.

Parameters:

  • attrs Array
    the attributes to be applied
  • opts Object
    the options to be applied

setBuffer

(
  • [buffer]
)
Set the file model's buffer. Creates a new node.js buffer object if a buffer object is is not passed as the parameter

Parameters:

  • [buffer] Object optional

setDefaults

(
  • attrs
  • opts
)
Set defaults. Apply default attributes and options to the file model

Parameters:

  • attrs Object
    the attributes to be applied
  • opts Object
    the options to be applied

setMeta

(
  • attrs
  • opts
)
Set the file model meta data, attributes and options in one go.

Parameters:

  • attrs Object
    the attributes to be applied
  • opts Object
    the options to be applied

setMetaDefaults

(
  • attrs
  • opts
)
Set the file model meta data defaults

Parameters:

  • attrs Object
    the attributes to be applied
  • opts Object
    the options to be applied

setOptions

(
  • [attrs={}]
)
Set the options for the file model. Valid properties for the attrs parameter: TaskGroup, detectEncoding, rootOutDirPath, locale, stat, data, buffer, meta.

Parameters:

  • [attrs={}] Object optional

setStat

(
  • stat
)
Set the node.js file stat.

Parameters:

  • stat Object

setUrl

(
  • url
)
Set the url for the file

Parameters:

  • url String

start

(
  • argv
)

Start the CLI

Parameters:

  • argv Array

toJSON

(
  • [dereference=false]
)
Object
Get the file model attributes. By default the attributes will maintain a reference to the file model. To return a dereferenced object, pass true as the parameter. The returned object will contain the file model's ID attribute.

Parameters:

  • [dereference=false] Object optional

Returns:

Object:

uninstall

(
  • next
  • opts
)

Uninstall method

Parameters:

  • next Function
  • opts Object

update

(
  • next
  • opts
)

Update method

Parameters:

  • next Function
  • opts Object

upgrade

(
  • next
  • opts
)

Upgrade method

Parameters:

  • next Function
  • opts Object

watch

(
  • next
)

Watch method

Parameters:

  • next Function

welcomeCallback

(
  • opts
  • next
)

Welcome Callback

Parameters:

  • opts Object
  • next Function

wrapAction

(
  • action
  • config
)

Wrap Action

Parameters:

  • action Object
  • config Object

write

(
  • opts
  • next
)
Write the out file. The out file may be different from the input file. Often the input file is transformed in some way and saved as another file format. A common example is transforming a markdown input file to a HTML output file. next(err)

Parameters:

  • opts Object
  • next Function
    callback

writeSource

(
  • [opts]
  • next
)

Inherited from FileModel but overwritten in src/lib/models/document.coffee:802

Write the source file. Optionally pass the opts parameter to modify or set the file's path, content or type. next(err)

Parameters:

  • [opts] Object optional
  • next Object

    callback

Properties

actionRunnerInstance

Object private
The action runner instance bound to DocPad

buffer

Object
File buffer. Node.js Buffer object. https://nodejs.org/api/buffer.html#buffer_class_buffer. Provides methods for dealing with binary data directly.

bufferTime

Object
Buffer time.

detectEncoding

Boolean
Whether or not we should detect encoding

Object private

Inherited from FileModel but overwritten in src/lib/models/document.coffee:93

The default attributes for any document model.

klass

Object private

Inherited from FileModel but overwritten in src/lib/models/document.coffee:74

The document model class.

locale

Object private
Locale information for the file

meta

Object private
The parsed file meta data (header). Is a Model instance.

rootOutDirPath

String
The out directory path to put the relative path.

stat

Object
Node.js file stat object. https://nodejs.org/api/fs.html#fs_class_fs_stats. Basically, information about a file, including file dates and size.

TaskGroup

Object private
Task Group Class

type

String private

Inherited from FileModel but overwritten in src/lib/models/document.coffee:81

String name of the model type. In this case, 'document'.