grunt-jsdom-jquery

"Grunt Task that uses jsdom to postprocess compiled HTML files with jQuery",

A simple Grunt multitask that uses jsdom to compile HTML on server side and allows manipulation with jQuery.

It is possible to use own functions to manipulate the HTML, but there are also four predefined functions:

• toc - will create a table of content
• bib - will create a table of all cites and link them up
• tof - will create a table of all figures and link them up
• tot - will create a table of all tables and link them up

Used in paged-media-boilerplate.

The Bibliography can be used with a custom .json or a Bibtex file. All four functions behave very similar to Latex.

Table of Contents

• Getting Started
  • Use it with grunt
  • Example with hyphenation
• Documentation
  • Options
  • Predefined post processing
    • Table of contents (toc)
    • Table of figures / tables (tof/tot)
    • Bibliography (bib)
• Release History
• License

Getting Started

Use it with grunt

Install this grunt plugin next to your project's grunt.js gruntfile with: npm install grunt-jsdom-jquery

Then add this line to your project's grunt.js gruntfile:

grunt.loadNpmTasks('grunt-jsdom-jquery');

Example with hyphenation

Get jquery-hyphen.js and a pattern file for your language.

This is how a task could look like:

jsdom:
  options:
    src: [
      grunt.file.read("jquery-hyphen.js")
      grunt.file.read("en-us.js")
    ]
    functions: [
      () -> this.$('p').hyphenate('en-us');
    ]

Documentation

Simply add task definition in your gruntfile. See the folllowing example:

jsdom:
  options:
    # options 
  compile: 
    src: "path/to/some/html/file/index.html"
    dest: "pdf/output/"

Run grunt jsdom to execute all the targets or grunt jsdom:targetname to execute a specific target. Every html file defined by the src parameter will be post processed and saved to dest folder.

Options

Here the available options with the corresponding defaults:

toc: # see below 
tof: # see below 
tot: # see below 
bib: # see below 
 
 
# Will be passed to each jade template generation 
jadeOptions: 
  pretty: true
 
# Will take an array of functions, which will be executed in order. 
# The names of the 4 predefined functions are also valid. 
# For details see below. 
functions: ["toc","tot","tof","bib"]
 
# See documentation of js dom. 
# jQuery will be unshifted to the `src` array.  
scripts: undefined
src: undefined
 

options.functions

In each function this will be bound to an object possessing the following properties:

• window
• document
• jQuery's $.

Parameters for the functions are:

• options object
• source (the HTML file) filename.

Example

jsdom: 
  options: 
    functions: [
      "toc",
      (options,src) ->
        $ = @$
        document = @document
        window = @window
        # do something 
      ]
    toc:
      selector: "#table-of-contents"
  compile: 
    src: "path/to/some/html/file/index.html"
    dest: "pdf/output/"

Predefined post processing

Options regarding the predefined functions can be accessed by options.{{nameOfFunction}}, so for the table of contents function options.toc will be responsible.

Table of contents (toc)

This function will search for the given selector (#toc) and fill its element with a linked list of chapters, sections and subsections.

The selectors for these three can be individually defined, also the id for the found elements will be set to, e.g., section1.1.

Defaults for options:

# Selector for the table of contents, content will be deleted. 
selector: "#toc"
 
# Selector for the chapter headings 
chapter: ":not(.front-matter,.back-matter) > h2"
 
# Template for the chapternumber 
chapterTemplate: "span.chapternumber=chapter"
 
# Class which will be added to the text 
chapterTextClass: "chaptertext"
 
# Same for section and subsection 
section: "h3"
sectionTemplate: "span.sectionnumber=chapter+'.'+section"
sectionTextClass: "sectiontext"
subsection: "h4"
subsectionTemplate: "span.subsectionnumber=chapter+'.'+section+'.'+subsection"
subsectionTextClass: "subsectiontext"

Example:

<div id="toc"></div>
<h2>Chapter Heading</h2>

will be replaced by:

<div id="toc">
  <ul>
    <li class="toc chapter">
      <a href="#chapter1">
        <span class="chapternumber">1</span> 
        <span class="chaptertext">Chapter Heading</span>
      </a>
      <ul>
    </li>
  </ul>
</div>
<h2 id="chapter1">
  <span class="chapternumber">1</span> 
  <span class="chaptertext">Chapter Heading</span>
</h2>

Table of figures / tables (tof/tot)

These functions will search for the given selector (#tof/#tot) and fill its element with a linked list of figures / tables.

Defaults for options:

# Content of this element will be replaced by the list of figures / tables 
selector: "#tof" / "#tot"
 
# Selector for choosing all elements which should be listed and / or linked 
element: "figure:has(figcaption)" / "table:has(caption)"
 
# Selector for the caption 
caption: "figcaption" / "caption"
 
# Class which will be added to all text found in the caption 
textClass: "figuretext" / "tabletext"
 
# Class which will be added to all text found in a link to an element 
linkTextClass: "figurereftext" / "tablereftext"
 
# Class for the text which belongs in front of the number 
preClass:"pre"
 
# Default for the text in front of the number  
preDefault: "Fig." / "Tab."
 
# Jade template for the number, pre will be  
# substituted by given text or default. 
# Available numbers: 
# element (absolute number of the element) 
# chapter (number of the containing chapter) 
# chapterelement (absolute number of the element relative to the chapter) 
# section (number of the containing section) 
# sectionelement (absolute number of the element relative to the section) 
# subsection (number of the containing subsection) 
# subsectionelement (absolute number of the element relative to the subsection) 
numberTemplate:"span.figurenumber=pre+chapter+'.'+chapterelement" /
  "span.tablenumber=pre+chapter+'.'+chapterelement"
 
# Class for the short description for the list 
shortClass:"short"

Example:

<h2>Chapter 1</h2>
<figure id="image">
  <img></img>
  <figcaption>
    <span.short>Short description</span>
    <span.pre>Figure </span>
  Long description
  </figcaption>
</figure>
<a href="#image">(a)</a>
<div class="back-matter">
  <h2>Table of figures</h2>
  <div id="tof"></div>
</div>

will be replaced by:

<h2 id="chapter1">
  <span class="chapternumber">1</span> 
  <span class="chaptertext">Chapter Heading</span>
</h2>
<figure id="image">
  <img></img>
  <figcaption>
    <span class="figurenumber">Figure 1.1</span> 
    <span class="figuretext">Long description</span>
  </figcaption>
</figure>
<a href="#image">
  <span class="figurenumber">Figure 1.1</span>
  <span class="figurereftext">(a)</span>
</a>
<div class="back-matter">
  <h2>Table of figures</h2>
  <div id="tof">
    <ul>
      <li class="tof">
        <a href="#image">
          <span class="figurenumber">Figure 1.1</span> 
          <span class="figuretext">Short description</span>
        </a>
      </li>
    </ul>
  </div>
</div>

Bibliography (bib)

Searches for cite elements in the html file, modifies them according to a template and creates a linked table with all used cites.

Can be used with a .json or a .bib file. If the provided file has no .json in its name, bibtex-parser will be used for reading it. A .json file should contain a dictionary, where the keys are used to fetch the entries.

Note: bibtex-parser will convert all keys to uppercase. So for lookup the provided keys will be also uppercased. Keep that in mind if using a .json.

Example:

<cite>PhysRevB.89.035403</cite>

will be replaced by:

<cite>
  <a href="#PHYSREVB.89.035403">
    <span class="citenumber">[1]</span>
  </a>
</cite>

Defaults for options:

# Selector for the bibliography, content will be deleted. 
selector: "#bib" 
 
# Selector for a single cite, note, that the innerHTML will be upper cased and  
# then be used to search the provided dictionary for an corresponding entry. 
cite: ":not(blockquote) > cite"
 
# Will replace KEY in a <cite template="TEMPLATENAME">KEY</cite> with the  
# compiled jade template. If no TEMPLATENAME is provided, the default will  
# be used. 
citeStyle:  
  default: "span.citenumber=`[`+NUMBER+`]`"
 
 
# Name of the key, which will be used for sorting all used entries prior  
# creating the table.  
# Uses [_.sortBy](http://lodash.com/docs#sortBy) that means ["YEAR", "MONTH"] is valid. 
sort: "NUMBER"
 
# Function which will be called with each entry prior creating the table, 
# should return the (modified) entry 
modifyEntry: undefined
 
# Filename or string of a jade template which will be used for each entry 
entryStyle: # default is the template in src/bibEntry.jade 
 
# Filename of the bibliography, if not defined will use patterns to find a file 
file: undefined
 
# Is only used if no file is specified. Replaces substrings in the source  
# filename (the HTML file) with other strings to find the bibliography # dynamically. 
patterns: 
  ".bib": /.html/i # .html will be replaced with .bib, not cases sensitive 

Release History

• v0.0.7: Bugfix for bib
• v0.0.7: Bugfix for toc
• v0.0.6: gitignore
• v0.0.5: Bugfix for cites
• v0.0.4: Bugfix for cites
• v0.0.3: Added dependency
• v0.0.2: Restructuring and tof/tot implementation
• v0.0.1: First Release

License

Copyright (c) 2014 Paul Pflugradt Licensed under the MIT license.