Tutorial05 Customizing coz

Custom Setup with Template Engine.

You can pass parameters to template engine via setup property in bud file. For example, handlebars engine accepts helper functions which can be called in template context.

.render-with-custom-setup.txt.bud (bud file)

/**
 * render-with-custom-setup.txt.bud
 * This is a bud file for "examples/06-customize-coz"
 */

// Bud with custom setup
module.exports = {
    force: true,
    mode: '444',
    // Template with using custom helper function.
    tmpl: 'Hey, {{emphasize msg}}',
    engine: 'handlebars',
    // Setup options for handlebars engine.
    setup: {
        // Register custom handlebars helpers.
        helpers: {
            'emphasize': function (txt) {
                return txt.toUpperCase() + '!!!!';
            }
        }
    },
    data: {
        'msg': 'watch out'
    }
};
if (!module.parent) {
    require('coz').render(__filename);
}

Running this will generate:

render-with-custom-setup.txt (generated file)

Hey, WATCH OUT!!!!

Register Custom Template Function.

You can register custom template to coz context and call it from .bud file by name.

render-with-custom-tmpl.js (executable file)

#!/usr/bin/env node

/**
 * render-with-custom-tmpl.js
 * This is an executable file for "examples/06-customize-coz"
 */


var Coz = require('coz').Coz;

// Create a custom coz context.
var coz = new Coz({
    // Define custom templates.
    tmpls: {
        // Custom template to generate single line json string.
        singleLineJson: function (data) {
            return JSON.stringify(data, null, 0);
        }
    }
});

coz.render({
    force: true,
    mode: '444',
    path: 'render-by-my-custom-tmpl-01.json',
    // Use custom tmpl
    tmpl: 'singleLineJson',
    // Data to pass custom tmpl.
    data: {
        'generator': __filename,
        'coz is': 'wonderful'
    }
}, function (err) {
    console.log('Compile done with custom tmpl.');
});

Running this will generate:

render-by-my-custom-tmpl-01.json (generated file)

{"generator":"/Users/okuni/projects/coz/docs/examples/06-customize-coz/render-with-custom-tmpl.js","coz is":"wonderful","$$bud":{"cwd":"/Users/okuni/projects/coz/docs/examples/06-customize-coz","path":"/Users/okuni/projects/coz/docs/examples/06-customize-coz/render-by-my-custom-tmpl-01.json"}}

Register Custom Template Engine.

By default, coz use Handlebars as template engine.

You can register your own engine and use it from .bud files.

render-with-custom-engine.js (executable file)

#!/usr/bin/env node

/**
 * render-with-custom-engine.js
 * This is an executable file for "examples/06-customize-coz"
 */


var Coz = require('coz').Coz;

// Create a custom coz context.
var coz = new Coz({
    // Define custom engines.
    engines: {
        'myCustomEngine01': {
            // Aliases for this engine.
            // These names also can be used in "engine" property of bud.
            $aliases: [
                'myCustom01'
            ],
            /**
             * Compile template string and create template function.
             * @implements {module:coz/lib/template~Engine.prototype.compile}
             * @param {string} source - Source string to compile.
             * @param {function} callback - Callback when done.
             */
            'compile': function (source, callback) {

                // Define a template function with source.
                // Template function takes a single agument `data` object and returns rendered string.

                /**
                 * Compiled template function
                 * @param {object} data - Data to render with.
                 * @returns {string} - Rendered string.
                 */
                function compiledTemplate(data) {
                    var rendered = String(source);
                    Object.keys(data).forEach(function (key) {
                        rendered = rendered.replace('__' + key + '___', data[key]);
                    });
                    return rendered;
                }

                // Pass the template function to callback.
                var err = null;
                callback(err, compiledTemplate);
            }
        }
    }
});

// Use custom coz context to render.
coz.render({
    force: true,
    mode: '444',
    // Use engine defined above.
    engine: 'myCustomEngine01',
    path: __dirname + '/render-by-my-custom-engine-01.txt',
    // Template source string to compile with the custom engine.
    tmpl: 'This is good day to __goodToDo___.',
    // Data to passed to compiled template function.
    data: {
        goodToDo: 'die'
    }
}, function (err) {
    console.log('Compile done with custom engine');
});

Running this will generate:

render-by-my-custom-engine-01.txt (generated file)

This is good day to die.

Use Custom Configurations From CLI Interface.

To customize CLI Interface, create a configuration file and pass it's pathname to --configuration (or -c) options.

use-custom-config-from-cli.config.js (configuration file)

/**
 * use-custom-config-from-cli.config.js
 * This is a CLI configuration file for "examples/06-customize-coz"
 */

// Custom configuration for CLI
module.exports = {
    tmpls: {
        // Custom template function.
        myCustomTmpl01: function (data) {
            return JSON.stringify(data, null, 2);
        }
    }
};

use-custom-config-from-cli.sh (CLI shell)

#!/bin/bash

###
# use-custom-config-from-cli.sh
# This is a CLI shell file for "examples/06-customize-coz"
##

HERE=$(dirname $0)

cd ${HERE}

# Render bud with custom configuration.
coz render ".render-by-custom-cli.txt.bud" -c "use-custom-config-from-cli.config.js"

---

See Also

Tutorials

• 01 - Installing coz
• 02 - Rendering bud files
• 03 - Mastering coz bud
• 04 - Using programmatic API
• 05 - Customizing coz

Links

• Node.js
• NPM
• nvm
• coz @ npm