lorem v0.4.0

lorem

Filler text generator compatible with Node.js, Require.js and plain-old <script/>.

Even though JQuery (>= 1.6) is optional, including it before lorem will allow lorem JQuery plugin to be automatically registered, making ipsum() available for $(selector) objects (which is exactly what is needed most of the time).

In a nutshell, lorem does the following:

• locates all tags (within $(selector)) with class attribute containing lorem_<options>
• replaces html (src in case of <img/>) within such tags according to the <options>

Usage

On the client-side, lorem can be either included using a direct link or can be installed with bower ('bower install lorem') or jam ('jam install lorem') package managers.

Plain-Old <script/>

<div id="container">
    <p>Generated using JQuery plugin:</p>
    <span class="lorem_s">
        <!-- expecting one sentence here -->
    </span>
    <div style="background-color: black; color: white" data-lorem="p2">
        <!-- expecting two paragraphs here -->
    </div>
    <!-- expecting image below -->
    <img class="lorem_i256x46"/>
</div>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
<script src="https://raw.github.com/shyiko/lorem/master/src/library/lorem.js"></script>
<script>
    (function($) {
        $('#container').ipsum();
        $(document.body).append('Generated not using JQuery plugin: "' + lorem.ipsum('w') + '"');
    }(jQuery));
</script>

Live demo: http://jsfiddle.net/shyiko/x8KAv

Require.js

require(['lorem'], function(lorem) {
    var paragraphAsAString = lorem.ipsum('p');
    ...
});

Node.js

Install the module with: npm install lorem

var lorem = require('lorem');
...
var paragraphAsAString = lorem.ipsum('p');

Classes

<lorem class prefix>_p[<number>[_<minimum number of sentences>[x<maximum number of sentences>]]]
<lorem class prefix>_s[<number>[_<minimum number of words>[x<maximum number of words>]]][$<maximum number of characters>]
<lorem class prefix>_w[<number>][$<maximum number of characters>]
<lorem class prefix>_i<width>[x<height>]

Examples (assuming default options):

lorem_p # single paragraph, same as lorem_p1
lorem_p2 # two paragraphs
lorem_s # single sentence, same as lorem_s1
lorem_s3$120 # three sentences, with maximum overall length <= 120 characters
lorem_w$5 # single word, maximum 5 characters long. same as lorem_w1$3.
lorem_w4 # four words
lorem_i300x100 # 300x100 image

Options

Defaults:

{
    text: 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod <TRUNCATED>' +
          'See lorem.js for complete value',
    /* used to tokenize text */          
    wordDelimiter: /\s|[,.]/, 
    numberOfSentencesPerParagraph: {min: 4, max: 7},
    numberOfWordsPerSentence: {min: 4, max: 9},
    imageURL: 'http://placehold.it/${w}x${h}',
    /* unsupported under IE<8 */
    offlineImage: 'data:image/gif;base64,R0lGODdhAQABAIABAMzMzP///ywAAAAAAQABAAACAkQBADs=', 
    /* indicates whether to use offlineImage instead of imageURL */
    useOfflineImage: false, 
    prefix: 'lorem_',
    /* optional. automatically added by lorem to all affected DOM elements */
    markerClass: 'lorem-marker',
    /* data-* attribute to apply lorem to */
    dataAttribute: 'lorem'
}

Defaults can be overridden either globally:

lorem.overrideDefaults(options) // e.g. lorem.overrideDefaults({ prefix: 'custom_prefix_' })

or per-request:

$('container').ipsum({ prefix: 'custom_prefix_' }); // lorem.ipsum(className, options) works as well

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Ideally add unit tests for any new or changed functionality. Executing 'grunt' within project directory should not produce any lint or test errors.

License

Copyright (c) 2012 Stanley Shyiko Licensed under the MIT license.