CombineFiles Plugin

The CombineFiles plugin allows you to merge Pixelsilk System Files together, giving the appearance and functionality of a single large file. It is generally used with Javascript files to reduce the number of HTTP requests that a website visitor has to make to load all of the javascript for a page.

2011-02-14_170946.png

Enabling CombineFiles

The CombineFiles plugin must be enabled before it can be used. See Enabling Plugins for more information.

Types of Files That Can be Combined

Note that any system files can be combined using CombineFiles. This includes javascript, css, csv, and plain text. 

Only Javascript and CSS support minification (see below). 

Using CombineFiles

There are two ways to use the CombineFiles plugin: a direct script reference, or the FileCombinerControl. Each has its advantages.

Direct Script Reference

The easiest and simplest way to use the CombineFiles plugin is with a script reference. A CombineFiles reference will always start with the URL CombineFiles.aspx. Then, either a direct path or a query string can be used to specify the files. Files are comma separated, so two possible combined files URLs are:

/CombineFiles.aspx?files=myScript1.js,myScript2.js
or
/CombineFiles.aspx/myScript1.js,myScript2.js

Both above URLs, when included in a <script> tag, will render the combination of myScript1.js and myScript2.js. Using it in a script tab is straightforward:

<script type="text/javascript" src="/CombineFiles.aspx/myScript1.js,myScript2.js"></script>

In both cases, a parameter of m may be used to produce minified output. For example:

/CombineFiles.aspx?files=myScript1.js,myScript2.js&m=1
or
/CombineFiles.aspx/m/myScript1.js,myScript2.js

Note that in the case without a query string, the files to be combined must be the last items in the path.

Both javascript and CSS are capable of being minified. Text (or javascript and CSS mixed together) will be left as-is.

Option 2: The FileCombinerControl

For maximum performance, use a FileCombinerControl to combine files. First, create the control (see Creating New Controls). Then to use the control, call it when you want to render a URL for the script, and include the files you want to combine in the format parameter. For example, for a control named CombineMyFiles:

<script type="text/javascript" src="[[CombineMyFiles:myScript1.js,myScript2.js]]"></script>

The control will then render an appropriate URL to combine the files, such as this:

<script type="text/javascript" src="/CombineFiles.aspx/0Sewt2ECdd4duLndd9eZUcYVESc1/myScript1.js,myScript2.js"></script>

Note the hash in the URL. When this hash is present, an Expires header will be sent in the response. When an expires header is sent, user agents (browsers) will cache the file, and the next time it is requested, it will be loaded directly from the user's cache, instead of making an HTTP request to the server to get the combined files. This can make a very large performance increase.

FileCombinerControl Settings

The FileCombinerControl also easily allows modifying how the combined files will be rendered.
2011-02-14_170522.png

  • Minify Files
    If checked, the combination of files will be minified, in the same way as supplying the m parameter above.
  • Cache Response
    If checked, the Expires header described above will not be sent. This can be useful for debugging.
  • No Query String
    If checked, the format of the CombineFiles reference will be in "/CombineFiles.aspx/m/my,files" instead of "/CombineFiles.aspx?files=my,files".

CombineFiles Settings

Finally, the CombineFiles plugin itself defines a single setting:

2011-02-14_171352.png

If checked, every set of combined files will be minified (if possible), regardless of the control settings or the m flag.

 

Back to Plug-ins »