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
()
Item Index
Methods
- action
- addUrl
- choose
- clean
- clone
- confirm
- constructor
- contextualize
- delete
- deleteSource
- destroy
- encode
- extractConfig
- extractOptions
- generate
- getActionRunner
- getAttributes
- getBuffer
- getCommander
- getContent
- getEve
- getExtensions
- getFilename
- getFilePath
- getLayout
- getLocale
- getMeta
- getOptions
- getOutContent
- getPath
- getStat
- hasLayout
- help
- info
- init
- initialize
- install
- isBinary
- isBufferOutdated
- isOption
- isText
- load
- normalize
- parse
- performAction
- prompt
- referencesOthers
- removeUrl
- render
- render
- renderDocument
- renderExtensions
- renderLayouts
- run
- selectSkeletonCallback
- server
- set
- setBuffer
- setDefaults
- setMeta
- setMetaDefaults
- setOptions
- setStat
- setUrl
- start
- toJSON
- uninstall
- update
- upgrade
- watch
- welcomeCallback
- wrapAction
- write
- writeSource
Methods
action
-
next
-
opts
Do action
Parameters:
-
next
Function -
opts
Object
addUrl
-
url
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
Returns:
confirm
-
message
-
[opts={}]
-
next
Confirm an option
Parameters:
-
message
String -
[opts={}]
Object optional -
next
Function
constructor
-
opts
-
next
Constructor method. Setup the CLI
Parameters:
-
opts
Object -
next
Function
contextualize
-
[opts={}]
-
next
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
Objectcallback
delete
-
[opts]
-
next
Parameters:
-
[opts]
Object optional -
next
Objectcallback
deleteSource
-
[opts]
-
next
Parameters:
-
[opts]
Object optional -
next
Objectcallback
destroy
-
err
Destructor.
Parameters:
-
err
Object
encode
-
opts
Parameters:
-
opts
Object
Returns:
extractConfig
-
[customConfig={}]
Extract Configuration
Parameters:
-
[customConfig={}]
Object optional
Returns:
the DocPad config
extractOptions
-
attrs
Parameters:
-
attrs
Object
Returns:
generate
-
next
Generate action
Parameters:
-
next
Function
getActionRunner
()
Object
Returns:
getAttributes
-
[dereference=true]
Parameters:
-
[dereference=true]
Object optional
Returns:
getBuffer
()
Object
Returns:
getCommander
()
Get the commander
Returns:
the commander instance
getContent
()
String or Object
Returns:
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
Parameters:
-
opts
Object
Returns:
getFilename
-
[opts={}]
Parameters:
-
[opts={}]
Object optional
Returns:
getFilePath
-
[opts={}]
Parameters:
-
[opts={}]
Object optional
Returns:
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
Functioncallback
getLocale
()
Object
Returns:
getMeta
-
[args...]
Parameters:
-
[args...]
Object optional
Returns:
getOptions
()
Object
private
Returns:
getOutContent
()
String or Object
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:
getPath
-
relativePath
-
parentPath
.
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:
getStat
()
Object
Returns:
hasLayout
()
Boolean
Checks if the file has a layout.
Returns:
help
-
next
Help method
Parameters:
-
next
Function
info
-
next
Info method
Parameters:
-
next
Function
init
-
next
Action initialise
Parameters:
-
next
Function
initialize
-
attrs
-
[opts={}]
Parameters:
-
attrs
Objectthe file model attributes -
[opts={}]
Object optionalthe file model options
install
-
next
-
opts
Install method
Parameters:
-
next
Function -
opts
Object
isBinary
()
Boolean
Returns:
isBufferOutdated
()
Boolean
Returns:
isOption
-
key
Parameters:
-
key
String
Returns:
isText
()
Boolean
Returns:
load
-
[opts={}]
-
next
Parameters:
-
[opts={}]
Object optional -
next
Functioncallback
normalize
-
[opts={}]
-
next
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
Objectcallback
parse
-
[opts={}]
-
next
Parse our buffer and extract meaningful data from it. next(err).
Parameters:
-
[opts={}]
Object optional -
next
Objectcallback
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
Parameters:
-
userUrl
Objectthe 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
Functioncallback
render
-
next
-
opts
Render method
Parameters:
-
next
Function -
opts
Object
renderDocument
-
opts
-
next
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
Functioncallback
renderExtensions
-
opts
-
next
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
Functioncallback
renderLayouts
-
opts
-
next
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
Functioncallback
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
Parameters:
-
attrs
Arraythe attributes to be applied -
opts
Objectthe options to be applied
setBuffer
-
[buffer]
Parameters:
-
[buffer]
Object optional
setDefaults
-
attrs
-
opts
Parameters:
-
attrs
Objectthe attributes to be applied -
opts
Objectthe options to be applied
setMeta
-
attrs
-
opts
Parameters:
-
attrs
Objectthe attributes to be applied -
opts
Objectthe options to be applied
setMetaDefaults
-
attrs
-
opts
Parameters:
-
attrs
Objectthe attributes to be applied -
opts
Objectthe options to be applied
setOptions
-
[attrs={}]
Parameters:
-
[attrs={}]
Object optional
setStat
-
stat
Parameters:
-
stat
Object
setUrl
-
url
Parameters:
-
url
String
start
-
argv
Start the CLI
Parameters:
-
argv
Array
toJSON
-
[dereference=false]
Parameters:
-
[dereference=false]
Object optional
Returns:
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
Parameters:
-
opts
Object -
next
Functioncallback
writeSource
-
[opts]
-
next
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
Objectcallback
Properties
actionRunnerInstance
Object
private
buffer
Object
bufferTime
Object
detectEncoding
Boolean
The default attributes for any document model.
klass
Object
private
The document model class.
locale
Object
private
meta
Object
private
rootOutDirPath
String
stat
Object
TaskGroup
Object
private
type
String
private
String name of the model type. In this case, 'document'.