Skip to content

Latest commit

 

History

History
308 lines (270 loc) · 6.74 KB

README.md

File metadata and controls

308 lines (270 loc) · 6.74 KB
Raw

gulp-inject-partials

NPM version Build Status Dependency Status Code Climate

A recursive injection of partials based on their path name for gulp.

Gulp-inject-partials parses target file, located defined placeholders and injects file contents based on their relative path. See Basic usage and More examples below. Gulp-inject-partials is based/inspired by gulp-inject.

Note: NodeJs v4 or above is required.

Installation

Install gulp-inject-partials as a development dependancy:

npm install --save-dev gulp-inject-partials

Basic usage

Each pair of comments are the injection placeholders (aka. tags, see options.start and options.end).

index.html

<!DOCTYPE html>
<html>
<head>
  <title>My index</title>
</head>
<body>
  <!-- partial:partial/_mypartial.html -->
  <!-- partial -->
</body>
</html>

partial/_mypartial.html

<div>
  This text is in partial
</div>

gulpfile.js

var gulp = require('gulp');
var injectPartials = require('gulp-inject-partials');

gulp.task('index', function () {
  return gulp.src('./src/index.html')
           .pipe(injectPartials())
           .pipe(gulp.dest('./src'));
});

Results in

<!DOCTYPE html>
<html>
<head>
  <title>My index</title>
</head>
<body>
  <!-- partial:views/_mypartial.html -->
  <div>
  This text is in partial
</div>
  <!-- partial -->
</body>
</html>

More examples

Injecting nested partials

Nesting partials works same way as single level injection. When injecting partials, gulp-inject-partials will parse parent file in search for partials to inject. Once it finds a partial will then recursively parse child partial.

index.html

<!DOCTYPE html>
<html>
<head>
  <title>My index</title>
</head>
<body>
  <!-- partial:views/_mypartial.html -->
  <!-- partial -->
</body>
</html>

views/_mypartial.html

<div>
  This is in partial
  <!-- partial:_mypartial2.html -->
  <!-- partial -->
  <!-- partial:_mypartial3.html -->
  <!-- partial -->
</div>

views/_mypartial2.html

<div>
  This text is in partial 2
</div>

views/_mypartial3.html

<div>
  This text is in partial 3
</div>

gulpfile.js

var gulp = require('gulp');
var injectPartials = require('gulp-inject-partials');

gulp.task('index', function () {
  return gulp.src('./src/index.html')
           .pipe(injectPartials())
           .pipe(gulp.dest('./src'));
});

Results in

<!DOCTYPE html>
<html>
<head>
  <title>My index</title>
</head>
<body>
  <!-- partial:views/_mypartial.html -->
  <div>
  This is in partial
  <!-- partial:_mypartial2.html -->
  <div>
  This text is in partial 2
</div>
  <!-- partial -->
  <!-- partial:_mypartial3.html -->
  <div>
  This text is in partial 3
</div>
  <!-- partial -->
</div>
  <!-- partial -->
</body>
</html>

Setting the custom start and/or end tag

It's possible to change start and end tag by setting option.start and options.end respectivelly.

index.html

<!DOCTYPE html>
<html>
<head>
  <title>My index</title>
</head>
<body>
  <## partial/_mypartial.html>
  </##>
</body>
</html>

partial/_mypartial.html

<div>
  This text is in partial
</div>

gulpfile.js

var gulp = require('gulp');
var injectPartials = require('gulp-inject-partials');

gulp.task('index', function () {
  return gulp.src('./src/index.html')
           .pipe(injectPartials({
              start: '<## {{path}}>',
              end: '</##>'
           }))
           .pipe(gulp.dest('./src'));
});

Results in

<!DOCTYPE html>
<html>
<head>
  <title>My index</title>
</head>
<body>
  <!-- partial:views/_mypartial.html -->
  <div>
  This text is in partial
</div>
  <!-- partial -->
</body>
</html>

Remove tags after insertion

For production purposes we would like inject tags to be removed and have a clean html. This is possible with options.removeTags.

index.html

<!DOCTYPE html>
<html>
<head>
  <title>My index</title>
</head>
<body>
  <!-- partial:partial/_mypartial.html -->
  <!-- partial -->
</body>
</html>

partial/_mypartial.html

<div>
  This text is in partial
</div>

gulpfile.js

var gulp = require('gulp');
var injectPartials = require('gulp-inject-partials');

gulp.task('index', function () {
  return gulp.src('./src/index.html')
           .pipe(injectPartials({
              removeTags: true
           }))
           .pipe(gulp.dest('./src'));
});

Results in

<!DOCTYPE html>
<html>
<head>
  <title>My index</title>
</head>
<body>
  <div>
  This text is in partial
</div>
</body>
</html>

API

inject(options)

options.start

Type: string
Param (optional): path - relative path to source file
Default: <!-- partial:{{path}} -->
Used to dynamically set starting placeholder tag, which might contain relative path to source file. Even thou this parameter is optional, whithout it no file would be injected.

options.end

Type: string
Param (optional): path - relative path to source file
Default: <!-- partial -->
Used to dynamically set ending placeholder tag, which might contain relative path to source file.

options.removeTags

Type: boolean
Default: false
When true the start and end tags will be removed when injecting files.

options.quiet

Type: boolean
Default: false
When true gulp task will not render any information to console.

options.prefix

Type: string
Default: (Empty string)
Prefix path to prepend to every route processed e.g. relative/path/to/partials/. Note that full route is still relative.

options.ignoreError

Type: 'boolean' Default: false When true ignores missing files during the injection and shows just info message

License

MIT © Miroslav Jonas