Installation
Quick Take
Purpose
This program is a non-parsing1, mixed-HTML2 email-template3 minifier.
1 Non-parsing means that program’s algorithm is a scanerless parser, it will traverse the input string as-is and will try to identify delete-able whitespace. That’s opposed to parsing algorithms where code as string is parsed into AST, processed, then rendered back into string.
2 mixed-HTML means this program supports all templating languages (from Nunjucks to JSP), all ESP templating languages (from Mailchimp or Oracle Responsys) and any programming languages present within HTML (for example, CDATA XML). This program will minify CSS too.
3 Web page HTML minifiers like html-minifier
won’t work on email templates. For example, email template HTML has extra requirements,
for example line-length limits (which are imposed by SMTP standards
).
API — crush()
The main function crush() is imported like this:
It’s a function which takes two input arguments:
| Input argument | Type | Obligatory | Description |
|---|---|---|---|
strType: String Obligatory: yes | |||
str | String | yes | The input string, HTML source code. |
optsType: Plain object Obligatory: no | |||
opts | Plain object | no | Optional Options Object. |
The Optional Options Object has the following shape:
| Key | Type | Default | Description |
|---|---|---|---|
lineLengthLimitType: number Default: 500 | |||
lineLengthLimit | number | 500 | When removing line breaks, what is the maximum line length to keep. Relevant only when opts.removeLineBreaks is on |
removeIndentationsType: Boolean Default: true | |||
removeIndentations | Boolean | true | Should we remove indentations? The default is, yes. |
removeLineBreaksType: Boolean Default: false | |||
removeLineBreaks | Boolean | false | Should we remove the line breaks? The default answer is, no. Enabling it automatically enables opts.removeIndentations. |
removeHTMLCommentsType: Boolean or Numbers: 0, 1 or 2Default: false | |||
removeHTMLComments | Boolean or Numbers: 0, 1 or 2 | false | Should we remove the HTML comments? Default answer, false is no, but there are settings to remove comments: 0 is off, 1 instructs to remove non-Outlook comments, 2 removes all comments including Outlook conditionals |
removeCSSCommentsType: Boolean Default: true | |||
removeCSSComments | Boolean | true | Should we remove CSS comments? This concerns both head CSS comments and inline CSS style comments within HTML style attributes. |
reportProgressFuncType: null or Boolean false or functionDefault: null | |||
reportProgressFunc | null or Boolean false or function | null | If you supply a function here, it will be called, and an argument will be given to it, a natural number, which means percentage complete at that moment. Values will range from 1 to 99, and finally, the main function will return the result’s plain object. |
reportProgressFuncFromType: Natural number Default: 0 | |||
reportProgressFuncFrom | Natural number | 0 | Default is zero percent but you can squeeze reporting percentages to start from a different number |
reportProgressFuncToType: Natural number Default: 100 | |||
reportProgressFuncTo | Natural number | 100 | Default is 100 percent but you can squeeze reporting percentages to go up to a different number |
breakToTheLeftOfType: array of zero or more stringsDefault: see the list below | |||
breakToTheLeftOf | array of zero or more strings | see the list below | When any of given strings are encountered AND removeLineBreaks option is on, current line will be terminated. This setting is not active if removeLineBreaks is turned off. If you want to disable a default set, either set this key to false or null or to an empty array. |
mindTheInlineTagsType: array of zero or more stringsDefault: see the list below | |||
mindTheInlineTags | array of zero or more strings | see the list below | Inline HTML tags such as <span> can accidentally introduce extra text. We take extra precautions when minifying around inline tags. |
Here are all defaults in one place for copying:
The function returns a plain object (type Res above):
| Key’s name | Type | Description |
|---|---|---|
logType: Plain object | ||
log | Plain object | Various statistics about the performed calculations. |
rangesType: Array of zero or more string range arrays | ||
ranges | Array of zero or more string range arrays | The result in ranges notation. |
applicableOptsType: Plain object | ||
applicableOpts | Plain object | Reports which options would have made a difference if enabled or disabled, considering the given input. |
resultType: String | ||
result | String | The result as string. |
opts.reportProgressFunc
This option is used in a web worker setup, in GUI web apps driven by html-crush. The idea is, since this program is CPU-bound, you put it on a web worker. Since the calculation can take some time, we need means to get the progress measurement from the main function.
html-crush will ping your callback function that you pass in opts.reportProgressFunc with a percentage done so far, calling it hundred times.