‚̧Notwithstanding Precautions, Misadventure
    Have ideas to improve npm?Join in the discussion! ¬Ľ

    grunt-usebanner

    0.3.1¬†‚Äʬ†Public¬†‚Äʬ†Published

    grunt-banner

    NPM version Build Status peerDependency Status devDependency Status

    Adds a simple banner to files

    Getting Started

    This plugin requires Grunt ~0.4.1

    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-banner --save-dev

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

    grunt.loadNpmTasks('grunt-banner');

    Or if you are using matchdep it will be included along with other grunt-* tasks by using this line of JS:

    require('matchdep').filterDev('grunt-*').forEach(grunt.loadNpmTasks);

    The "usebanner" task

    grunt-banner renamed it’s task from banner to usebanner as a banner is often used to hold a banner template for a number of grunt plugins

    Overview

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

    The wildcard selector * is perfectly valid for selecting targets to add a banner to.

    grunt.initConfig({
      usebanner: {
        taskName: {
          options: {
            position: 'top' || 'bottom',
            banner: '// banner text <%= templates encouraged %>',
            linebreak: true || false
          },
          files: {
            src: [ 'path/to/file.ext', 'path/to/another/*.ext' ]
          }
        }
      }
    })

    Options

    options.position

    Type: String Default value: 'top Value range: 'top' or 'bottom' only

    The position to place the banner - either the top or bottom (other values will default to top)

    options.banner

    Type: String Default value: ``

    The text to use as a banner. Templated strings are perfectly acceptable and encouraged.

    options.pattern

    Type: String

    Allows the banner to be added only if the supplied pattern matches.

    options.linebreak

    Type: Boolean Default value: true

    Set linebreak to true to add a line break between banner and file content.

    options.process

    Type: Function

    Allows the banner to be generated for each file using the output of the process function.

    Usage Examples

    Basic Usage

    In this example an appConfig is read from a JSON file and used to populate a banner template which is then used by grunt-banner to place at the top of some files. Each file in the array will have the banner placed on to it and all .js files in the /more-scripts/ folder will have a banner thanks to the * wildcard.

    var appConfig = grunt.file.readJSON( 'app-config.json' ) || {};
    grunt.initConfig({
      banner: '/* <%= appConfig.info.name %> - version <%= appConfig.info.version %> - ' +
              '<%= grunt.template.today("dd-mm-yyyy") %>\n' +
              '<%= appConfig.info.description %>\n ' +
              '&#169 <%= grunt.template.today("yyyy") %> <%= appConfig.info.author.name %> ' +
              '- <%= appConfig.info.author.email %> */\n',
      usebanner: {
        dist: {
          options: {
            position: 'top',
            banner: '<%= banner %>'
          },
          files: {
            src: [ 'scripts/main-min.js', 'stylesheets/main-min.css', 'more-scripts/*.js' ]
          }
        }
      }
    })

    Process Usage

    By supplying a process function you effectively take control of how the banner is generated, the task is still responsible for placing it. In essence, it replaces the need for a banner object being specified in your grunt config as you are creating it from code for each file. This gives you the flexibility to add file-specific data to your banners.

    This example uses grunt templating to generate a banner that references the file name it is being appended to. Run the test cases to see this in action.

    usebanner: {
      dist: {
        options: {
          position: 'top',
          process: function( filepath )
            return grunt.template.process(
              '// banner for file: <%= filename %>',
              { data: {
                filename: filepath.match(/\/([^/]*)$/)[1]
              } } );
            }
          },
          files: {
            src: [ 'test/tmp/someProcess.js' ]
          }
      }
    }

    Notes

    grunt-banner simply adds the banner to the head or foot of the files that are specified by the array passed to files.src, it makes no attempt to see if a banner already exists and it is up to the user to ensure that the file should not already contain a banner. To this end it is recommended to use the grunt-contrib-clean task and only add banners to production-ready code.

    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.


    Task submitted by Matt Styles @personalurban

    Keywords

    Install

    npm i grunt-usebanner

    DownloadsWeekly Downloads

    57

    Version

    0.3.1

    License

    none

    Last publish

    Collaborators

    • avatar