FileModel Class
The FileModel class is DocPad's representation of a file in the file system. Extends the DocPad Model class https://github.com/docpad/docpad/blob/master/src/lib/base.coffee#L49. FileModel manages the loading of a file and parsing both the content and the metadata (if any). Once loaded, the content, metadata and file stat (file info) properties of the FileModel are populated, as well as a number of DocPad specific attributes and properties. Typically we do not need to create FileModels ourselves as DocPad handles all of that. But it is possible that a plugin may need to manually create FileModels for some reason.
attrs =
fullPath: 'file/path/to/somewhere'
opts = {}
#we only really need the path to the source file to create
#a new file model
model = new FileModel(attrs, opts)
The FileModel forms the base class for the DocPad DocumentModel class.
Constructor
FileModel
()
Item Index
Methods
- action
- addUrl
- clone
- contextualize
- delete
- deleteSource
- encode
- extractOptions
- getActionRunner
- getAttributes
- getBuffer
- getContent
- getExtensions
- getFilename
- getFilePath
- getLocale
- getMeta
- getOptions
- getOutContent
- getPath
- getStat
- initialize
- isBinary
- isBufferOutdated
- isOption
- isText
- load
- normalize
- parse
- removeUrl
- render
- set
- setBuffer
- setDefaults
- setMeta
- setMetaDefaults
- setOptions
- setStat
- setUrl
- toJSON
- write
- writeSource
Methods
action
-
args...
Apply an action with the supplied arguments.
Parameters:
-
args...
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
clone
()
Object
Clone the model and return the newly cloned model.
Returns:
cloned file model
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
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
Objectcallback
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
Objectcallback
encode
-
opts
File encoding helper opts = {path, to, from, content}
Parameters:
-
opts
Object
Returns:
encoded result
extractOptions
-
attrs
Extract Options.
Parameters:
-
attrs
Object
Returns:
the options object
getActionRunner
()
Object
Get the action runner instance bound to DocPad
Returns:
getAttributes
-
[dereference=true]
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:
getBuffer
()
Object
Get the file model's buffer object. Returns a node.js buffer object.
Returns:
node.js buffer object
getContent
()
String or Object
Get the file content. This will be the text content if loaded or the file buffer object.
Returns:
getExtensions
-
opts
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 of extension names
getFilename
-
[opts={}]
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:
getFilePath
-
[opts={}]
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:
getLocale
()
Object
Get the file's locale information
Returns:
the locale
getMeta
-
[args...]
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:
getOptions
()
Object
private
Get Options. Returns an object containing the properties detectEncoding, rootOutDirPath locale, stat, buffer, meta and TaskGroup.
Returns:
getOutContent
()
String or Object
Get the file content for output.
Returns:
getPath
-
relativePath
-
parentPath
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:
getStat
()
Object
Get the node.js file stat.
Returns:
the file stat
initialize
-
attrs
-
[opts={}]
Initialize the file model with the passed attributes and options. Emits the init event.
Parameters:
-
attrs
Objectthe file model attributes
-
[opts={}]
Object optionalthe file model options
isBinary
()
Boolean
Is this a binary file?
Returns:
isBufferOutdated
()
Boolean
Is Buffer Outdated True if there is no buffer OR the buffer time is outdated
Returns:
isOption
-
key
Checks whether the passed key is one of the options.
Parameters:
-
key
String
Returns:
isText
()
Boolean
Is this a text file? ie - not a binary file.
Returns:
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
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
removeUrl
-
userUrl
Removes a url from the file model (files can have more than one url).
Parameters:
-
userUrl
Objectthe url to be removed
render
-
[opts={}]
-
next
Render this file. The file model output content is returned to the passed callback in the result (2nd) parameter. The file model itself is returned in the callback's document (3rd) parameter. next(err,result,document)
Parameters:
-
[opts={}]
Object optional -
next
Objectcallback
set
-
attrs
-
opts
Assign attributes and options to the file model.
Parameters:
-
attrs
Arraythe attributes to be applied
-
opts
Objectthe 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
Objectthe attributes to be applied
-
opts
Objectthe options to be applied
setMeta
-
attrs
-
opts
Set the file model meta data, attributes and options in one go.
Parameters:
-
attrs
Objectthe attributes to be applied
-
opts
Objectthe options to be applied
setMetaDefaults
-
attrs
-
opts
Set the file model meta data defaults
Parameters:
-
attrs
Objectthe attributes to be applied
-
opts
Objectthe 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
toJSON
-
[dereference=false]
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:
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
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
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.
The default attributes for any file model.
bufferTime
Object
Buffer time.
detectEncoding
Boolean
Whether or not we should detect encoding
klass
Object
private
The file model class. This should be overridden in any descending classes.
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
String name of the model type. In this case, 'file'. This should be overridden in any descending classes.