gulp-handlebars-file-include

Gulp Plugin used to include external files into html.

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
gulp-handlebars-file-include
1.0.05 years ago5 years agoMinified + gzip package size for gulp-handlebars-file-include in KB

Readme

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

```sh $ npm install gulp-handlebars-file-include ``` ---

Basic Usage

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

gulp.js ```javascript 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 ```html
click me
``` Then you can use the button in another file, for example src/index.html ```html
Hello World!!

this is the content of the page

{{ fileInclude 'src/button' }} ``` (Note the use of fileInclude helper) and you get as result dist/index.html ```html
Hello World!!

this is the content of the page

click me
``` 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 ```html
<img src="main.png"/>
click me
``` 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 ```html
{{#if image}}
<img src="{{ image }}"/>
{{else}}
<img src="main.jpg"/>
{{/if}}
{{#if text}}
{{text}}
{{else}}
click me
{{/if}}
``` 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 ```html
Hello World!!

this is the content of the page

{{ fileInclude 'src/button.html' image='bird.jpg' text='buy birds' }} ``` and as you can suppose the result is dist/index.html ```html
Hello World!!

this is the content of the page

<img src="bird.jpg"/>
buy birds
``` 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 ```html
<img src="{{eval "this.image || 'main.jpg'" }}"/>
{{eval "this.text || 'click me'"}}
``` 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**<br/>
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**<br/>
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**<br/>
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**<br/>
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
```javascript
function(filePath){
console.log(filePath)
return filePath.startsWith(path.resolve(__dirname, 'src/partials'));
}
```
- **handlebarsHelpers**<br/>
{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.