grunt-replace-attribute

Replace the attribute of any html tag

Getting Started

This plugin requires Grunt ~0.4.5

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-replace-attribute --save-dev

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

grunt.loadNpmTasks('grunt-replace-attribute');

The "replace_attribute" task

Overview

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

grunt.initConfig({
  replace_attribute: {
    options: {
      upsert: true
    },
    your_target: {
      options: {
        replace: {
          'div.batman': { class: '%value% > superman' }
        }
      }
      files: {
          'destination.html': 'source.html'
      }
    },
  },
});

Options

options.upsert

Type: Object|Boolean Default value: false

Determines whether to add a new attribute to an element if it is not already present.

Either set the option globally, for all selectors:

upsert: true|false // always|never insert a new attribute

or for individual tags:

upsert: { div: false, input: true }

options.placeholder

Type String Default value: '%value%'

This is the placeholder for the current attribute value. See the examples below for more detail.

options.replace

Type: Object

An Object containing the configuration for your target selectors.

grunt-replace-attribute uses node-trumpet, so any of the following selectors should work:

• E
• E F
• E > F
• E + F
• E.class
• E#id
• E[attr=value]
• E[attr~=search]
• E[attr|=prefix]
• E[attr^=prefix]
• E[attr$=suffix]
• E[attr*=search]

options.replace.{tag name}

Type: Object

An Object which maps attribute names to their replacements. Each attribute name can be one of the following types:

---

Type: String

The new attribute value. The current attribute value can be referenced using the syntax %value%. (See options.placeholder to change this).

Type Array

An array containing a regular expression and a string to be passed as arguments to String's replace method.

Type Function

A function which returns the new attribute value. The current attribute is available as the first argument.

---

Usage Examples

Basic example using Strings

In this example, we replace all the class attributes on each span element with the value text-center. options.upsert is omitted, so only elements which already have a class attribute will be modified.

grunt.initConfig({
  replace_attribute: {
    target: {
      options: {
        replace: {
          span: { class: 'text-center' }
        }
      },
      files: {
        'path/to/destination.html': 'path/to/source.html'
      }
    }
  }
});

<!-- source.html -->
<div class="container">
    <span class="text-left">My class will be modified</span>
    <span>My class will not be modified</span>
</div>

<!-- destination.html -->
<div class="container">
    <span class="text-center">My class will be modified</span>
    <span>My class will not be modified</span>
</div>

Using Strings with %value%

In this example, we append pull-right on to the value of all the class attributes of each div element. options.upsert is set to true, so all div elements will be modified.

grunt.initConfig({
  replace_attribute: {
    target: {
      options: {
        upsert: true,
          replace: {
          div: { class: '%value% pull-right' }
        }
      },
      files: {
        'path/to/destination.html': 'path/to/source.html'
      }
    }
  }
});

<!-- source.html -->
<div class="label">
    <div>My class will be modified</div>
</div>

<!-- destination.html -->
<div class="label pull-right">
    <div class="pull-right">My class will be modified</div>
</div>

Using Regular Expressions

In this example, we use a regex to modify each li's class attribute, appending -banana onto the match. The two arguments are given to String.replace so we can use the $1, $2, $3 ... syntax to reference each match.

grunt.initConfig({
  replace_attribute: {
    target: {
      options: {
        replace: {
          li: { class: [/(one|two|three)/g, '$1-banana'] }
        }
      },
      files: {
        'path/to/destination.html': 'path/to/source.html'
      }
    }
  }
});

<!-- source.html -->
<li class="one"></li>
<li class="two"></li>
<li class="three"></li>
<li class="four"></li>

<!-- destination.html -->
<li class="one-banana"></li>
<li class="two-banana"></li>
<li class="three-banana"></li>
<li class="four"></li>

Using Functions

In this example we reverse the path of the src value on all img elements using a function.

grunt.initConfig({
  replace_attribute: {
    target: {
      options: {
        replace: {
          img: {
            src: function (original) {
              return original.split('/').reverse().join('/');
            }
          }
        }
      },
      files: {
        'path/to/destination.html': 'path/to/source.html'
      }
    }
  }
});

<!-- source.html -->
<img src="path/to/an/img" >

<!-- destination.html -->
<img src="img/an/to/path" >

Using more complex selectors

In this example, we use a more complex selector to add a style="opacicty:0.5;" attribute to spans within li elements which have the class disabled and all other elements which have the attribute data-fade="true".

grunt.initConfig({
  replace_attribute: {
    target: {
      options: {
        upsert: { h1: true, span: true },
        replace: {
          '*[data-fade=true], li.disabled > span': { style: 'opacicty:0.5;' }
        }
      },
      files: {
        'path/to/destination.html': 'path/to/source.html'
      }
    }
  }
});

<!-- source.html -->
<div class="heading">
    <h1 data-fade="true" >Heading</h1>
    <span>Description</span>
</div>
<ul class="list-group">
    <li class="list-group-item disabled">
        <span>Item 1</span>
    </li>
    <li class="list-group-item">
        <span>Item 2</span>
    </li>
    <li class="list-group-item disabled">
        <span>Item 3</span>
    </li>
</ul>

<!-- destination.html -->
<div class="heading">
    <h1 data-fade="true" style="opacicty:0.5;">Heading</h1>
    <span>Description</span>
</div>
<ul class="list-group">
    <li class="list-group-item disabled" style="opacicty:0.5;">
        <span>Item 1</span>
    </li>
    <li class="list-group-item">
        <span>Item 2</span>
    </li>
    <li class="list-group-item disabled" style="opacicty:0.5;">
        <span>Item 3</span>
    </li>
</ul>

Known Issues

• self-closing tags

if an input tag which closes itself is modified, the output tag is stripped of the forward slash. This may pose a problem if it conflicts with your htmlhint options.

<input class="foo" />
<!-- becomes -->
<input class="bar">

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.

Release History

• v 1.0.0 - Initial Release