WebGrease configuration file

WebGrease configuration settings are stored in an XML text file. You can use this file to preconfigure the settings for various operations and various solution configuration modes. When you run WG.exe, you can specify a configuration file instead of entering the settings on the command line. The configuration file also includes some settings that are not available from the command line.

Note: Keep in mind that WG.exe can only run one operation per execution. Even though you can preconfigure the settings for multiple operations in the configuration file, you must still run WG.exe for each operation individually.

Some example uses for the WebGrease configuration file include:

  • Create separate minification settings for CSS files and JavaScript files. Because minification is a single operation, you can run it with a single execution of WG.exe.
  • Create separate configurations for Debug and Release mode. Use the WG.exe –type option to specify which mode to use.
  • Preconfigure minification, image sprite, and JavaScript validation settings. Use a build script to run WG.exe three times (one for each operation) using the same configuration file.

The WebGrease configuration file contains XML that has a WebGrease element as the root node. Information inside this element is grouped into three main areas:

Settings element

Specifies global settings and default settings for some file set elements. Any default settings specified in the Settings element are overridden by the settings of a corresponding element in a file set element.

For example, you can use the CssMinification child element to specify default CSS minification settings that apply to all CssFileSet elements. If a specific CssFileSet element includes settings for its Minification child element, those settings will override the default settings (specified in the CssMinification element) for that particular CSS file set.

Attributes 

Attribute Description Value

configSource

Specifies a WebGrease configuration file.

A relative or absolute path and file name.

The configSource attribute enables you to store the configuration for the Settings element in an external file. This allows you to maintain various default settings in separate files. For example, you can maintain all default CSS minification settings in one file and all default JavaScript minification settings in another file.

To include multiple external configuration files, include multiple Settings elements with different values for their configSource attributes.

Child elements

Element Description Value

Bundling element

Specifies the default bundling settings. These settings are used if a CssFileSet element or JsFileSet element does not define bundling settings.

See the Bundling element of the CssFileSet or the Bundling element of the JsFileSet.

CssMinification element

Specifies the default CSS minification settings. These settings are used if a CssFileSet element does not define minification settings.

See the Minification element of the CssFileSet.

DPI element

Specifies the DPI settings.

A semicolon-separated list of DPI values. For more information, see DPI element.

Global element

Specifies global settings.

This element does not have a value, but it does have attributes. For more information, see Global element.

ImageDirectories element

Specifies the folder that contains the static image files to be processed. The folder path can be relative or absolute.

A relative or absolute folder name. To specify multiple folders, separate each path with a semicolon.

ImageDirectoriesToHash element

Specifies the folder that contains the static image files to be hashed. The folder path can be relative or absolute.

A relative or absolute folder name. To specify multiple folders, separate each path with a semicolon.

ImageExtensions element

Specifies the image file extensions of the image types that you want to process.

Any image file extension, without the period. Separate extensions with a semicolon.

For example: jpg;bmp

JsMinification element

Specifies the default JavaScript minification settings. These settings are used if a JsFileSet element does not define minification settings.

See the Minification element of the JsFileSet.

Locales element

Specifies the default locales settings. These settings are used if a CssFileSet element or JsFileSet element does not define locales settings.

See the Locales element of the CssFileSet or the Locales element of the JsFileSet.

OutputPathFormat element

Specifies the directory path for the output files using placeholders for other elements.

A relative or absolute file path that optionally includes placeholders. Placeholders use the element name and must be enclosed in curly braces {}.

For an example, see OutputPathFormat example.

OverrideTokensDirectory element

Specifies the folder that contains the resource tokens (resx files). This overrides the default token location.

A relative or absolute folder name.

Preprocessing element

Specifies a preprocessing engine and any specific settings for that engine.

A semicolon-separated list of preprocessing engines.

ResourcePivot element

Specifies the resource type and specific default resources that are processed for that resource type.

A semicolon-separated list of resources. The key attribute must also be set to the resource type. For more information, see ResourcePivot element.

Spriting element

Specifies the default CSS spriting settings. These settings are used if a CssFileSet element does not define spriting settings.

See the Spriting element of the CssFileSet.

Themes element

Specifies the default CSS theme settings. These settings are used if a CssFileSet element does not define theme settings.

See the Themes element of the CssFileSet.

TokensDirectory element

Specifies the folder that contains the resource tokens.

A relative or absolute folder name.

DPI element

Specifies the DPI settings as a list of semicolon-separated values. The output attribute can be used to include multiple instances of this element and to specify different folders for different DPI outputs.

Attributes

Attribute Description Value

Output

Specifies the output location as a file or folder. The path can be relative or absolute.

A relative or absolute folder or file name.

Child elements

None.

Global element

Specifies global settings.

Attributes

Attribute Description Value

config

Specifies a solution configuration name.

Any configuration name defined in your solution file, such as Debug or Release. This value is case-sensitive.

treatWarningsAsErrors

Specifies whether the program treats warnings as errors.

True or False.

Child Elements

None.

Preprocessing element

Specifies a preprocessing engine and any engine-specific settings. The static files are run through the preporocessing engine before being processed by WebGrease. WebGrease includes the Sass preprocessing engine.

Either the engines attribute or the Engines element is required. You can specify the preprocessing engines in either place.

Attributes

Attribute Description Value

config

Specifies a solution configuration name.

Any configuration name defined in your solution file, such as Debug or Release. This value is case-sensitive.

engines

Specifies the preprocessing engine.

A semicolon-separated list of preprocessing engines.

Child Elements

Element Description Value

Engines

Specifies the preprocessing engines.

A semicolon-separated list of preprocessing engines.

ResourcePivot element

Specifies a resource type and the specific default resources that are processed by all CssFileSet and JsFileSet elements. An individual CssFileSet element or JsFileSet element can specify additional resources by including the appropriate child element.

For example, if the ResourcePivot element is configured as <ResourcePivot key="themes" applyMode="CssApplyAfterParse">msnblue</ResourcePivot>, then all CssFileSet elements will process the msnblue theme. You can specify an additional theme to be processed by a specific CssFileSet by including a Themes element in that CssFileSet.

If you include a ResourcePivot element with key=”themes”, you do not also need to include a Themes element as a child element of the Settings element. Both of these approaches are used to specify default themes, so only one approach is needed. Likewise, if you include a ResourcePivot element with key=”locales”, you do not also need to include a Locales element as a child element of the Settings element.

Attributes

Attribute Description Value

key

Specifies the subfolder for the resource type.

Common values are:

  • themes
  • locales

applyMode

Specifies how changes are applied.

One of the following values:

  • ApplyAsStringReplace
  • CssApplyAfterParse

Default = ApplyAsStringReplace

The key attribute specifies the name of a subfolder within the tokens directory that contains the resource files. For example, if key=locales is specified, WebGrease looks in the following folders for the resource files:

  • <tokens directory>/css/locales
  • <tokens directory>/js/locales

The ApplyAsStringReplace value of the applyMode attribute specifies that resources are applied before the CSS is parsed. This allows tokens to be inserted into the CSS rule (for example: margin-%global.left%). However, this can cause significantly slower processing because the CSS will be parsed for each resource. For example, if you have ten themes, the CSS will be parsed ten times.

The CssApplyAfterParse value of the applyMode attribute specifies that resources are applied after the CSS is parsed. This is usually faster because the CSS is only parsed once; however, tokens cannot be inserted into CSS rules using this method.

Child Elements

None.

Examples

Example Settings element

<Settings>
<!-- Specifies two folders that contain image files as relative paths -->
<ImageDirectories>css\images;f2\i</ImageDirectories>
      <!- - Specifies several image file extensions -->
<ImageExtensions>png;jpg;jpeg;gif;ico</ImageExtensions>

<!-- If unspecified, this defaults to the current directory -->
<TokensDirectory>App</TokensDirectory>
<!-- subdirectory of above  -->
<OverrideTokensDirectory>Site1</OverrideTokensDirectory>
</Settings>

OutputPathFormat example

Given the following resources:

  • A resource named green in the themes folder
  • A resource named en-us in the locales folder

And the following configuration:

<Settings>
   <ResourcePivot key=”themes” />
   <ResourcePivot key=”locales” />
   <Dpi output="tmx.mobile.webkit">1;2</Dpi>
   <OutputPathFormat>{themes}/{locales}/{dpi}/{output}</OutputPathFormat>
</Settings>

The following outputs are produced:

  • green/en-us/1/tmx.mobile.webkit
  • green/en-us/2/tmx.mobile.webkit

See Also

Last edited Sep 4, 2013 at 7:56 PM by JeffRob, version 6

Comments

No comments yet.