README.md

gulp-handlebars-file-include

Gulp plugin for create html templates in a simpler way.
A very common problem when developers create html templates for a site, is the amount of repeated html code.
This module resolve that problem allowing you define a sections of code in separated files, for later invoke it. Much better still, this allow you build semantic templates with handlebars.

---

Installation

$ npm install gulp-handlebars-file-include

---

Basic Usage

Configure gulp-handlebars-file-include in your gulp file

gulp.js

var gulpHandlebarsFileInclude = require('gulp-handlebars-file-include');

gulp.src('src/**/*')
    .pipe(gulpHandlebarsFileInclude())
    .pipe(gulp.dest('dist'))

Example

Let say we create a file to represent a button

src/button.html

<button class="btn simple-btn">
    click me
</button>

Then you can use the button in another file, for example

src/index.html

<h1>Hello World!!</h1>
<p>this is the content of the page</p>
{{ fileInclude 'src/button' }}

(Note the use of fileInclude helper) and you get as result

dist/index.html

<h1>Hello World!!</h1>
<p>this is the content of the page</p>
<button class="btn simple-btn">
    click me
</button>

Let say you want to add an icon image to the buttons, the only thing you need to do is change your button.html file, for example.

src/button.html

<button class="btn simple-btn">
    <img src="main.png"/>
    click me
</button>

But you can even improve the behavior of your button and allow set its image and text when it is used, for example

src/button.html

<button class="btn simple-btn">
    {{#if image}}
    <img src="{{ image }}"/>
    {{else}}
    <img src="main.jpg"/>
    {{/if}}
    
    {{#if text}}
    {{text}}
    {{else}}
    click me
    {{/if}}
</button>

here we say to button set the image and text context property if those values are supplied, if not, set the 'main.png' and 'click me' values respectively. Then in your index.html you can say

src/index.html

<h1>Hello World!!</h1>
<p>this is the content of the page</p>
{{ fileInclude 'src/button.html' image='bird.jpg' text='buy birds' }}

and as you can suppose the result is

dist/index.html

<h1>Hello World!!</h1>
<p>this is the content of the page</p>
<button class="btn simple-btn">
    <img src="bird.jpg"/>
    buy birds
<button>

even better, you can use the eval helper (provided with this module) to evaluate an expression on fly, that will reduce your button.html file to this:

src/button.html

<button class="btn simple-btn">
    <img src="{{eval "this.image || 'main.jpg'" }}"/>
    {{eval "this.text || 'click me'"}}
</button>

Note that this helper receive a string expression to evaluate, and you access to context parameters with this keyword.

---

Handlebars Helpers

• fileInclude This helper receive the path as string, of an external file used to compile with handlebars and included the compiled result.
  You can pass parameters used to compile the external file in the way arg1=value1 arg2=value2 ...

• eval This helper receive an expression as string, this expression is evaluated and return its result.
  You can access to context properties in the expression, using the this keyword

---

API

gulpHandlebarsFileInclude(globalContext, options)

• globalContext object used as a default context for all templates.
  This can be useful if you want to set, for example, the same footer message for all indexes page.

• options object with the following properties

  • rootPath
    string, or string[] used to set where the compiler search for files to include.
    This is useful to take you away to define the whole path of the file to include.
    If the compiler can't find a file in the rootPath, then is search as normal absolute file path.

  • extensions
    string[] to set the valid file extensions in which the compiler search the files.
    This allow to declare a file to include without extensions.
    Default is ['.html', '.hbs', '.hb', '.handlebars'].

  • maxRecursion
    int used to restrict the maximum amount of times in which a file can include it-self.
    This is used to stop infinite recursion of the included file.
    Default value is 10.

  • ignoreFiles
    function(string) => boolean that receive a filePath of the current file to compile and return boolean to indicate if you want generate the file in dist.
    That is useful to avoid generate files of partial templates.
    For example, maybe all your partial files are in src/partials, then you can check the path of file to generete and ignore from src/partials with

      function(filePath){
          console.log(filePath)
          return filePath.startsWith(path.resolve(__dirname, 'src/partials'));
      }

  • handlebarsHelpers
    {name: <string>, fn: function}[]
    Array of Objects with the properties name of string and fn of function.
    This is used to include custom helpers to the handlebars compiler.