API Docs for:
Show:

FileModel Class

Extends Model

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

()

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:

Object:

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 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

encode

(
  • opts
)
Object private

File encoding helper opts = {path, to, from, content}

Parameters:

  • opts Object

Returns:

Object:

encoded result

extractOptions

(
  • attrs
)
Object private

Extract Options.

Parameters:

  • attrs Object

Returns:

Object:

the options object

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

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:

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:

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

Get the file content for output.

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

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

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
)

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
)

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

Parameters:

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

    callback

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
)

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 Object

    callback

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

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:

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
)

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.

Object private

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.