Overview

There are two types of XML files that can be used as input to the command-line version of the Microsoft Ajax Minifier. The first specifies input and output files and is called a manifest file; the second specified rules for renaming variable, properties, and functions.

Technically, both sets of information can be specified in the same file. The root element is ignored and can use any element name at all (although there has to be a single root element for the file to be valid XML). The “input” functionality simply looks for all descendent elements of type <output> and operates on them. The “naming” functionality simply looks for descendent elements of type <rename> and <norename>. All three of these elements can exist under the root elements, and the same XML file can be specified in both the –rename and –xml switches.

The manifest file can also be used as the input to the AjaxMin Manifest Build Task.

XML Manifest File

The simplest version of a manifest file has a root element that contains one or more <output> elements. Each <output> element may contain one or more <input> elements. The <output> element specifies an output file (the OFILE in the mandatory “path” attribute), and the containing <input> elements specify the source file(s) (the IFILE in the mandatory “path” attribute) to use to create the output.

<root>
  <output path="..\..\Output\XmlInput\FirstOutputFile.js">
    <input path="input1.js"/>
    <input path="input2.js"/>
    <input path="input3.js"/>
  </output>
  <output path="..\..\Output\XmlInput\SecondOutputFile.js">
    <input path="input2.js"/>
    <input path="input1.js"/>
    <input path="input3.js"/>
  </output>
</root>

But the manifest file can do even more. For example, the root element may contain an <arguments> element, which has a string value of switches that is parsed to create the default settings to use when generating each <output> file. Each <output> element can also contain an <arguments> element to specify settings that are laid on top of the default settings specified at the root.

<arguments> Elements

There are no required attributes for the <arguments> element, and it only contains a single text string that is parsed as command-line switches for either the entire set (if a child of the root element) or the specific output file (if a child of an <output> element).

<arguments>-kill:0x400 -eval:safeall</arguments>

There is one optional attribute for the <arguments> element: config. This is only useful when using the manifest with the Manifest Build Task.

The .targets file supplied with Microsoft Ajax Minifier passes the build configuration to the build task. If the <arguments> element includes a “config” attribute, only the arguments that match the current build configuration will be used. In this way, separate Debug and Release options can be specified in your manifest file:

<arguments config="Debug">-kill:-1 -minify:false -line:M</arguments>
<arguments config="Release">-rename:all</arguments>

<output> Elements

The <output> elements have a required “path” attribute (as previously mentioned), but can also specify the output encoding via an optional “encoding” attribute with a value consistent with the –enc switch. The type of the output file (JavaScript or StyleSheet") can either be determined by the extensions of the input files, or if they are inconclusive or non-standard, the <output> element can have a “type” attribute with a value of “JS” or “CSS.”

Inside the <output> element are one or more required <input> elements, as previously mentioned. But it can also contain an <arguments> element, any number of <rename> elements, any number of <norename> elements, an optional <symbolMap> element, and any number of <resource> elements.

<output path="outputfile.js" type="js" encoding="utf-16" >
    </output>

<input> Elements

The <input> elements must have a required “path” attribute that points to the input file. It can also have an optional “encoding” attribute that can specify one of the supported .NET text encoding names to use to read that input file. It can also have an “optional” attribute. If no “optional” attribute is specified, the file is considered required and an error will be thrown if it doesn’t exist. But if the value of the “optional” attribute is “true,” no error will be thrown if the input files doesn’t exist.

<input path="inputfile.js" encoding="big5" optional="true" />

There is also an optional “origin” attribute, which can be used to specify source files which are not part of the project per se, and which are taken from outside sources. Typically these files are third-party frameworks and other files that you don’t want to modify (or cannot due to licensing reasons), but also for which you don’t want to see a bunch of warnings. Marking a source file as “external” turns off all warnings and all errors except for the most serious of syntax errors.

<input path="jquery-2.0.0.min.js" origin="external" />

External files will be minified independently, by themselves, and internal or project files will be minified after concatenating adjacent non-external files. The results will all be concatenated together into the resulting output file in the given <input> element order. External files therefore must be valid syntax on their own; individual project files may be partial syntax, as long as result of concatenating the adjacent non-project files is valid syntax.

<rename> Elements

The <rename> element contains two required attributes: “from” and “to.” What this element does is create a renaming pair – any variables with a name equal to the “from” attribute value will be renamed to the value of the “to” variable (assuming they are both valid JavaScript identifier names).

<rename from="fromName" to="toName" />

<norename> Elements

The <norename> element contains a single required attribute, “name”. This element specifies that any variables with a name equal to the “name” attribute value will not be automatically renamed. The attribute “id” may be substituted for “name.”

<norename name="$" />

<symbolMap> Elements

The <symbolMap> element will cause a symbol map to be created for the containing output file. The element contains a single required attribute, “path,” which specifies the output of the symbol map file. By default, the XML source map file format is generated. If the V3 JSON source map format is desired, the “name” attribute should also be specified, with the value “V3”. The only two allowed values for the name are “v3” or “xml” (case-insensitive).

<symbolMap name="v3" path="outputfile.js.map" />

<resource> Elements

An <output> element may also contain zero or more <resource> elements that specify .RESX or .RESOURCES files (the RFILE in the mandatory “path” attribute) from which localized strings can be pulled. The object to look for in the sources is specified by the optional “name” attribute, and must be a valid JavaScript identifier (IDENT); if the “name” attribute is not specified, the identifier “Strings” is assumed. For example, given the element:

<resource path="MYLOC.RESX" name="MyLoc" />

Then whenever the member lookup MyLoc.Foo is encountered in the sources, the string in the file MYLOC.RESX with the name “Foo” is looked up, and MyLoc.IDENT is replaced with that string literal. If there is no string in MYLOC.RESX with the name “Foo”, then the member lookup is replaced with an empty string literal.

 

XML Naming File

<root>
    <rename from="IDENT" to="IDENT" />
    <norename id="IDENT" />
</root>

This file can be used with the –rename switch of the EXE program. The root element can contain zero or more <rename> elements, and zero or more <norename> elements.  The <rename> element specifies identifier names in the source (the IDENT in the mandatory “from” attribute) that should be renamed (to the IDENT in the mandatory “to” attribute). The <norename> element specifies certain identifiers (the IDENT in the mandatory “id” attribute) which should not be automatically renamed. IDENT is always a valid case-sensitive JavaScript identifier.

Last edited Dec 16, 2013 at 3:14 PM by ronlo, version 28

Comments

No comments yet.