Extensions
The extend
directory is purposed for extending Fepper's functionality.
Extensions can be contributed or custom. The extend
directory will not be
modified when updating Fepper.
Contributed extensions:
- Install and update contributed extensions with npm in the
extend
directory. - Add the tasks to
extend/contrib.js
(andextend/auxiliary/auxiliary_contrib.js
if necessary) in order for Fepper to run them. - Contributed Fepper extensions can be found at https://www.npmjs.com/search?q=fepper%20extension
Custom extensions:
- Write custom extensions in the
extend/custom
directory. - Extensions require a file ending in "~extend.js" in order for Fepper to recognize their tasks.
- The "*~extend.js" file can be directly under
extend/custom
, or nested one directory deep, but no deeper. - Add the tasks to
extend/custom.js
(andextend/auxiliary/auxiliary_custom.js
if necessary) in order for Fepper to run them. - Fepper runs a self-contained instance of gulp to manage tasks. This gulp instance will be independent of any other gulp instance on your system.
- For best results, set
const gulp = global.gulp
, notconst gulp = require('gulp')
. - The
fp
command is an alias forgulp
(among other things). Anyfp
task can be included in a custom task. - Fepper only supports gulp 3 syntax.
It may be helpful to write help text for a custom extension, especially when a
person other than the author uses it. To do this, create a custom task appended
by ":help". Declare and log the help text as follows, and it will be output by
running fp extend:help
.
'use strict';
const gulp = global.gulp;
gulp.task('custom-task:help', function (cb) {
let helpText = `
Fepper Custom Task Extension
Usage:
<task> [<additional args>...]
Task and description:
fp custom-task:help Print usage and description of custom task.
`;
console.log(helpText);
cb();
});
Confs and prefs:
You might need to access the values in the conf.yml
and pref.yml
files in
order to write custom tasks. They are exposed through global.conf
and
global.pref
(on the global
Node object).
The values in patternlab-config.json
are exposed through global.conf.ui
.
Please note that all paths in patternlab-config.json
will be converted to
absolute paths in global.conf.ui
. Relative paths can be accessed through
global.conf.ui.pathsRelative
.
Utilities:
Common utilty functions for custom extensions are available from the Fepper Utils npm.
Object-oriented Fepper:
Beneath the gulp tasking system lies object-oriented Fepper. Running any fp
task instantiates the Fepper
class. This instance is exposed through the
global.fepper
object. By directly accessing the Fepper
instance, you can run
any Fepper operation without gulp. Deeper within Fepper
lies the Patternlab
class. By directly accessing Patternlab
, you can run any Pattern Lab
operation without Fepper. The Patternlab
instance is attached to Fepper as
global.fepper.ui.patternlab
. The global.fepper
object can, of course, be
easily inspected in a console.
If there is something you wish were different about the Fepper
class, or any
of its member classes, you can inherit from the class, and make whatever changes
you wish, without worry that your changes will be overwritten by the next
update.
Here is an example of overriding the fp help
command:
- Create an
instance_file
. For this example, let's write it atextend/custom/hack-help.js
.
'use strict';
const FepperSuper = require('fepper');
const HelperSuper = require('fepper/core/tasks/helper');
const TasksSuper = require('fepper/core/tasks/tasks');
class Helper extends HelperSuper {
constructor(options) {
super(options);
}
main() {
console.log('ASYNC ALL THE THINGS!');
}
}
class Tasks extends TasksSuper {
constructor(options) {
super(options);
this.helper = new Helper(this.options);
}
}
module.exports = class Fepper extends FepperSuper {
constructor(cwd) {
super(cwd);
this.tasks = new Tasks(this.options);
}
}
- Declare
instance_file
inpref.yml
.
instance_file: extend/custom/hack-help.js
- Run
fp help
on the command line. It should log "ASYNC ALL THE THINGS!"
Hackers wishing to view the code for any of these classes will find that the ES6
syntax and object-orientation makes the code mostly self-documenting. The entry
point to the Fepper
class is in
Fepper NPM at core/fepper.js
.
There is currently no public API for object-oriented Fepper. To express demand for one, please open an issue.