Grunt-html-amend NPM

grunt-html-amend

Amends HTML source files with dynamic data.

Introduction

It is often desirable to have a grunt task inject dynamic data into an HTML file. This grunt task allows you to add in comments, element, attributes or arbirtary character data.

Getting Started

This plugin requires Grunt ^1.0.3

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-html-amend --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-html-amend');

The "htmlAmend" task

Overview

In your project's Gruntfile, add a section named htmlAmend to the data object passed into grunt.initConfig().

NOTE: Nearly all options may be specified as functions which return a valid option. For example, the content option may be either a string or a function which returns a string. If the result of the function is another function, that new function will be executed. There is no limit to the number of functions which may be run, however system limitations and Grunt will certainly impose limits.

grunt.initConfig({
  htmlAmend: {
    options: {
        // Common options go here
    },
    // Standard grunt file specifications
    src: 'src/index.html',
    dest: 'dist/index.html'
    }]
  },
});

Options

options.position

Type	Values	Default Value
`string`	'element', 'attribute', 'comment', 'regex'	`undefined`

attribute

Name	Values	Required
element	String or Function	yes
attributeName	String or Function	yes
attributeValue	String or Function	no

The attribute option will operate on the first element in the DOM which matches the element.

An attribute with the name attributeName and value attributeValue will be appended to the opening tag of the matching element.

Example:

Grunt configuration:

htmlAmend: {
  options: {
    position: 'attribute',
    element: 'div',
    attributeName: 'class',
    attributeValue: 'best-class'
  },
  src: 'src/index.html',
  dest: 'dist/index.html'
}

Input HTML ('src/index.html'):

<html>
  <body>
    <div></div>
  </body>
</html>

Output HTML ('dest/index.html'): Input HTML:

<html>
  <body>
    <div class="best-class"></div>
  </body>
</html>

comment

Name	Values	Required
element	String or Function	yes
content	String or Function	no

The comment option will operate on the first element in the DOM which matches the element.

A star comment (/* */) will be added directly after the matching element, with the content between the comment stars.

Example:

Grunt configuration:

htmlAmend: {
  options: {
    position: 'comment',
    element: 'div',
    content: 'This space for rent'
  },
  src: 'src/index.html',
  dest: 'dist/index.html'
}

Input HTML ('src/index.html'):

<html>
  <body>
    <div></div>
  </body>
</html>

Output HTML ('dest/index.html'): Input HTML:

<html>
  <body>
    <div>/* This space for rent */</div>
  </body>
</html>

element

Name	Values	Required
element	String or Function	yes
mode	'afterOpen', 'beforeClose' or Function	yes
content	String or Function	no

The element option will operate on the first element in the DOM which matches the element.

If the mode is afterOpen, then the content will be added after the open tag. Conversely, if the mode is beforeClose, then the content will be inserted directly before the closing tag.

Example:

Grunt configuration:

htmlAmend: {
  options: {
    position: 'element',
    element: 'section',
    mode: 'afterOpen',
    content: '<div class="message">Hello world!</div>'
  },
  src: 'src/index.html',
  dest: 'dist/index.html'
}

Input HTML ('src/index.html'):

<html>
  <body>
    <section></section>
  </body>
</html>

Output HTML ('dest/index.html'):

<html>
  <body>
    <section><div class="message">Hello world!</div></section>
  </body>
</html>

regex

Name	Values	Required
regex	String, RegExp or Function	yes
content	String or Function	no

The regex option will operate on the first instance in the DOM which is matched by the regex value. It is possible to replace all matches if the value for regex is a RegExp with the global flag set.

Example:

Grunt configuration:

htmlAmend: {
  options: {
    position: 'regex',
    regex: 'PUT_CONTENT_HERE',
    content: '<div>This space for rent</div>'
  },
  src: 'src/index.html',
  dest: 'dist/index.html'
}

Input HTML ('src/index.html'):

<html>
  <body>
    PUT_CONTENT_HERE
  </body>
</html>

Output HTML ('dest/index.html'): Input HTML:

<html>
  <body>
    <div>This space for rent</div>
  </body>
</html>

Building

npm install -g grunt jest
npm install
npm run build

Running Tests

Integration tests run, which invoke the task to run against specific HTML files. In general, the input HTML files reside in test\integration\files\source and the expected HTML files reside in test\integration\files\expected. Using PathUtil to specify files for the runTest harness can keep tests clean and easy to follow.

Run tests once:

npm run test

Run tests continuously:

npm run test:watch

Deploying

This is a basic script which can be used to build and deploy (to NPM) the project.

export VERSION=<NEXT VERSION>
git checkout -b release/$VERSION
npm version --no-git-tag-version patch
npm run build
npm run test
git add package*
git commit -m 'Version bump'
npx auto-changelog -p
git add CHANGELOG.md
git commit -m 'Updated changelog'
git checkout master
git merge --no-ff release/$VERSION
git tag -a -m 'Tagged for release' $VERSION
git branch -d release/$VERSION
git checkout develop
git merge --no-ff master
git push --all && git push --tags

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

html insert replace gruntplugin

@hal313/html-amend

@infinitebrahmanuniverse/nolb-grunt-h @everything-registry/sub-chunk-1795

1.0.0

8 years ago