Class: KssBuilderBase

kss/builder/base~KssBuilderBase()

A kss-node builder takes input files and builds a style guide.

Constructor

new KssBuilderBase()

Create a KssBuilderBase object.

This is the base object used by all kss-node builders.

const KssBuilderBase = require('kss/builder/base');
class KssBuilderCustom extends KssBuilderBase {
  // Override methods of KssBuilderBase.
}
Source:

Methods

(static) builderResolve(builder) → {string}

Resolve the builder path from the given file path.

Call this static method to resolve the builder path.

Parameters:
Name Type Description
builder string

The path to a builder or a builder to load.
Source:
Returns:

resolved path

Type
string

(static) loadBuilder(builderClass) → {Promise.<KssBuilderBase>}

Loads the builder from the given file path or class.

Call this static method to load the builder and verify the builder implements the correct builder API version.

Parameters:
Name Type Description
builderClass string | function

The path to a builder or a builder class to load.
Source:
Returns:

A Promise object resolving to a KssBuilderBase object, or one of its sub-classes.

Type
Promise.<KssBuilderBase>

addOptionDefinitions(optionDefinitions) → {KssBuilderBase}

Adds option definitions to the builder.

Since kss-node is extensible, builders can define their own options that users can configure.

Each option definition object is key-compatble with yargs, the command-line utility used by kss-node's command line tool.

If an option definition object has a:

  • multiple property: if set to false, the corresponding option will be normalized to a single value. Otherwise, it will be normalized to an array of values.
  • path property: if set to true, the corresponding option will be normalized to a path, relative to the current working directory.
  • default property: the corresponding option will default to this value.
Parameters:
Name Type Description
optionDefinitions object

An object of option definitions.
Source:
Returns:

The KssBuilderBase object is returned to allow chaining of methods.

Type
KssBuilderBase

addOptions(options) → {KssBuilderBase}

Stores the given options.

Parameters:
Name Type Description
options Object

An object of options to store.
Source:
Returns:

The KssBuilderBase object is returned to allow chaining of methods.

Type
KssBuilderBase

build(styleGuide) → {Promise.<KssStyleGuide>}

Build the HTML files of the style guide given a KssStyleGuide object.

Parameters:
Name Type Description
styleGuide KssStyleGuide

The KSS style guide in object format.
Source:
Returns:

A Promise object resolving to a KssStyleGuide object.

Type
Promise.<KssStyleGuide>

buildGuide(styleGuide, options) → {Promise.<KssStyleGuide>}

A helper method that can be used by sub-classes of KssBuilderBase when implementing their build() method.

The following options are required to use this helper method:

  • readBuilderTemplate: A function that returns a promise to read/load a template provided by the builder.
  • readSectionTemplate: A function that returns a promise to read/load a template specified by a section.
  • loadInlineTemplate: A function that returns a promise to load an inline template from markup.
  • loadContext: A function that returns a promise to load the data context given a template file path.
  • getTemplate: A function that returns a promise to get a template by name.
  • templateRender: A function that renders a template and returns the markup.
  • filenameToTemplateRef: A function that converts a filename into a unique name used by the templating system.
  • templateExtension: A string containing the file extension used by the templates.
  • emptyTemplate: A string containing markup for an empty template.
Parameters:
Name Type Description
styleGuide KssStyleGuide

The KSS style guide in object format.
options object

The options necessary to use this helper method.
Source:
Returns:

A Promise object resolving to a KssStyleGuide object.

Type
Promise.<KssStyleGuide>

buildPage(templateName, options, pageReference, sections, contextopt) → {Promise}

Renders the template for a section and saves it to a file.

Parameters:
Name Type Attributes Description
templateName string

The name of the template to use.
options object

The getTemplate and templateRender options necessary to use this helper method; should be the same as the options passed to BuildGuide().
pageReference string | null

The reference of the current page's root section, or null if the current page is the homepage.
sections Array

An array of KssSection objects.
context Object <optional>

Additional context to give to the template when it is rendered.
Source:
Returns:

A Promise object.

Type
Promise

clone(builderPath, destinationPath) → {Promise.<null>}

Clone a builder's files.

This method is fairly simple; it copies one directory to the specified location. A sub-class of KssBuilderBase does not need to override this method, but it can if it needs to do something more complicated.

Parameters:
Name Type Description
builderPath string

Path to the builder to clone.
destinationPath string

Path to the destination of the newly cloned builder.
Source:
Returns:

A Promise object resolving to null.

Type
Promise.<null>

createMenu(pageReference) → {Array}

Creates a 2-level hierarchical menu from the style guide.

Parameters:
Name Type Description
pageReference string

The reference of the root section of the page being built.
Source:
Returns:

An array of menu items that can be used as a template variable.

Type
Array

getOptionDefinitions(keyopt) → {*}

Returns the requested option definition or, if no key is specified, an object containing all option definitions.

Parameters:
Name Type Attributes Description
key string <optional>

Optional name of option to return.
Source:
Returns:

The specified option definition or an object of all option definitions.

Type
*

getOptions(keyopt) → {*}

Returns the requested option or, if no key is specified, an object containing all options.

Parameters:
Name Type Attributes Description
key string <optional>

Optional name of the option to return.
Source:
Returns:

The specified option or an object of all options.

Type
*

log(…message) → {KssBuilderBase}

Logs a message to be reported to the user.

Since a builder can be used in places other than the console, using console.log() is inappropriate. The log() method should be used to pass messages to the KSS system so it can report them to the user.

Parameters:
Name Type Attributes Description
message string <repeatable>

The message to log.
Source:
Returns:

The KssBuilderBase object is returned to allow chaining of methods.

Type
KssBuilderBase

logError(error) → {KssBuilderBase}

Logs an error to be reported to the user.

Since a builder can be used in places other than the console, using console.error() is inappropriate. The logError() method should be used to pass error messages to the KSS system so it can report them to the user.

Parameters:
Name Type Description
error Error

The error to log.
Source:
Returns:

The KssBuilderBase object is returned to allow chaining of methods.

Type
KssBuilderBase

prepare(styleGuide) → {Promise.<KssStyleGuide>}

Allow the builder to preform pre-build tasks or modify the KssStyleGuide object.

The method can be set by any KssBuilderBase sub-class to do any custom tasks after the KssStyleGuide object is created and before the HTML style guide is built.

Parameters:
Name Type Description
styleGuide KssStyleGuide

The KSS style guide in object format.
Source:
Returns:

A Promise object resolving to a KssStyleGuide object.

Type
Promise.<KssStyleGuide>

prepareDestination(assetDirectory) → {Promise}

A helper method that initializes the destination directory and optionally copies the given asset directory from the builder.

Parameters:
Name Type Description
assetDirectory string

The name of the asset directory to copy from builder.
Source:
Returns:

A promise to initialize the destination directory.

Type
Promise

prepareExtend(templateEngine) → {Array.<Promise>}

Helper method that loads modules to extend a templating system.

The --extend option allows users to specify directories. This helper method requires all .js files in the specified directories and calls the default function exported with two parameters, the templateEngine object and the options added to the builder.

Parameters:
Name Type Description
templateEngine object

The templating system's main object; used by the loaded module to extend the templating system.
Source:
Returns:

An array of Promise objects; one for each directory given to the extend option.

Type
Array.<Promise>

setLogErrorFunction(logErrorFunction) → {KssBuilderBase}

The error() method logs an error message for the user. This method allows the system to define the underlying function used by the error method to report the error message to the user. The default log error function is a wrapper around console.error().

Parameters:
Name Type Description
logErrorFunction function

Function to log a message to the user.
Source:
Returns:

The KssBuilderBase object is returned to allow chaining of methods.

Type
KssBuilderBase

setLogFunction(logFunction) → {KssBuilderBase}

The log() method logs a message for the user. This method allows the system to define the underlying function used by the log method to report the message to the user. The default log function is a wrapper around console.log().

Parameters:
Name Type Description
logFunction function

Function to log a message to the user.
Source:
Returns:

The KssBuilderBase object is returned to allow chaining of methods.

Type
KssBuilderBase