Infusion 1.5 uses Grunt for creating custom builds. See https://github.com/fluid-project/infusion#how-do-i-create-an-infusion-package for information.
Creating an Infusion 1.4 Custom Build
You can create a custom build of the latest release of Infusion using the Infusion Builder. If you wish to create a custom build using the very latest version, you can do so manually, if you know a bit about ant and svn.
What you will need
- Apache
Ant - The optional Ant task 'Script'
- Fluid Infusion source and build scripts, available from github.
For instructions on setting up the tools listed above, see the section #Setting up the environment at the bottom of this page.
Using the custom build scripts
The Infusion build scripts are typically run from a command line. You must be in the build-scripts directory to run the scripts.
The most typical use of the build scripts will be using the customBuild target with one or more of three optional parameters: 'include', 'exclude', and 'jsfilename'. (See the #Options section below for more information about these and other parameters.) The following example shows what this would look like.
ant -lib lib/rhino customBuild -Dinclude="<list of modules to include>" -Dexclude="<list of modules to exclude>" -Djsfilename="<desired file name>"
The values passed to 'include' and 'exclude' are comma separated lists of module names (see the list of #Modules below for supported module names). If you specify a module to include, all of the module's dependencies will also be included. By contrast, if you specify a module to exclude, only that module will be excluded - not its dependencies.
Use excludes with caution
If you exclude a module that is a required dependency, then it must be included in your website in another way for Infusion components to work.
Some examples:
ant -lib lib/rhino customBuild -Dinclude="pager" -Djsfilename="infusionPager.js"
This example will create a custom JavaScript file called infusionPager.js that includes only one Infusion Component: the Pager. The build will automatically include any and all Infusion framework files needed by the Pager, as well as any jQuery files.
ant -lib lib/rhino customBuild -Dinclude="uiOptions, tableOfContents" \
-Dexclude="jQuery, jQueryUICore, jQueryUIWidgets" \
-Djsfilename="MyCustomInfusion.js"
This example will create a custom JavaScript file called MyCustomInfusion.js that includes two Infusion Component (UI Options and the Table of Contents) and excludes jQuery files. The build will automatically include any and all Infusion framework files required by the two components.
A user might choose to exclude the jQuery files if they already have a copy of jQuery in use on their site.
ant -lib lib/rhino customBuild -Dinclude="framework, fss"
This example will create a custom JavaScript file with the default file name (MyInfusion.js) that includes the Infusion Framework files and the Fluid Skinning System (FSS) files as well as any other files required by these two modules. It will not include any of the Infusion components.
URL rewriting
Infusion builds include a single js file, InfusionAll.js, that includes the necessary dependency files. However, the HTML files are bundled with the <script> and <link> blocks all pointing at the individual files.
To create a build that comes with the references in the <head> rewritten to point at the single .js file:
In v1.1: Run the custom build scripts with the rewriteHead option set to "true":
ant -lib lib/rhino -DrewriteHead="true"
In v1.2: Run the infusionAllBuilds ant target:
ant -lib lib/rhino infusionAllBuilds
Warning
The infusionAllBuilds target (or the rewriteHead option in v1.1) is intended to be used alone. It will run without error if the same options as the customBuild target (e.g. include, exclude, etc.) are provided, however the HTML files will link to both the single concatenated file and the individual required files.
Rhino
Portions of the Infusion build system are written in JavaScript, and are connected with the Ant-based system using the Rhino engine.
If you'd rather not specify the -lib parameter every time you run a build, you can upgrade the copy of Rhino installed by Ant in your $ANT_HOME/lib directory with the newer version distributed in Infusion's build-scripts/lib/rhino directory. On Mac OS X:
sudo rm -rf /usr/share/ant/lib/js-1.6R7.jar sudo cp lib/rhino/js.jar /usr/share/ant/lib/js-1.7R3.jar
Modules
Name | Notes |
|---|---|
Component Modules: |
|
inlineEdit |
|
pager |
|
progress | Included with the Uploader component by default |
reorderer |
|
tabs | Included with the UI Options component by default |
tableOfContents | Included with the UI Options component by default |
tooltip | Included with the Inline Edit component by default |
uiOptions |
|
undo | Included with the Inline Edit component by default |
uploader |
|
Framework Modules: |
|
framework | Will automatically be included with any component module |
renderer | Will automatically be included with any component module that requires it |
fastXmlPull | Will automatically be included with the Renderer and any component that requires the Renderer |
json |
|
fss | Including the |
fssReset |
|
fssLayout | If you wish to exclude all of FSS, you will need to exclude all fss modules |
fssText |
|
fssThemes |
|
External libraries: |
|
jQuery | Will automatically be included with any component module |
jQuerybgiframePlugin | Required by |
jQueryDelegatePlugin | Required by |
jQueryUICore |
|
jQueryUIWidgets | Required by |
jQueryTooltipPlugin | Required by |
swfupload | Included with the Uploader component by default |
swfobject | Included with the Uploader component by default |
Options
Option | Description | Default |
|---|---|---|
| A comma-separated list of module names to be included in the output. | If unspecified, everything will be included. |
| A comma-separated list of module names to be excluded from the output. | If unspecified, no required dependencies will be excluded. |
| The desired name of the resulting JavaScript file containing all of the requested modules. |
|
New in v1.2: | A boolean used to request that the output not be minified (Minification removes all comments and whitespace. The resulting file is smaller, but very difficult to read. If you wish to be able to ready the file, use | false (i.e. output will be minified by default) |
Removed as of v1.2: | A boolean used to request that the | false (i.e. HTML files will include references to individual files by default) |
Custom build with no parameters
If you use custom build with no parameters, everything, except for the tests and samples, is included. In addition, the resulting build files in the products/dist and products/src-dist directories are named InfusionAll.js files, rather than MyInfusion.js.
Output
The Infusion build scripts produce two folders at the root level of the distribution (i.e. as siblings of the build-scripts folder):
build/: This is a working folder used by the scripts to assemble and process files.products/: This is the destination for the final output of the scripts.
You will rarely need to look at the contents of the build folder, but the products folder will contain the files you're looking for.
Products in v1.2
The products folder will contain either one or two archive files, depending on what target what run.
Custom Build
If the customBuild target was used to create a custom Infusion package, a single archive will be created: infusion-1.2.zip. This file will contain:
- The concatenated JavaScript file containing all the requested resources, minified (unless the
noMinifyflag was set); - a
.warfile suitable for deploying to a web server; - folders containing the individual files requested, minified (unless the
noMinifyflag was set)
Release Build
If the default target was used to create the release packages, two archives will be created: infusion-1.2.zip and infusion-1.2-src.zip. These files have the same content, save that the -src archive contains un-minified files.
- The concatenated JavaScript file containing the entire Infusion library and all dependencies;
- a
.warfile suitable for deploying to a web server; - folders containing the Infusion files
Products in v1.1
The products folder will contain two folders and two archives:
src-dist/: A folder containing unminified versions of all of the requested files, organized according to the Infusion source tree;dist/: A folder containing minified versions of all of the requested files, organized according to the Infusion source treeinfusion-1.1.2-src.zip: An archive file containing- The concatenated JavaScript file containing the entire Infusion library and all dependencies;
- a
.warfile suitable for deploying to a web server; - folders containing the Infusion files
infusion-1.1.2.zip: An archive file containing the items listed above, but minified.
Other targets
The Infusion build scripts include other ant targets that are generally intended for use by the Infusion development team, but may be of interest to others:
Target | Description |
|---|---|
| In v1.1: The default target. |
In v1.2: | The default target. |
In v1.2: | Creates a release-ready distrubution with the HTML headers re-written to link to the single concatenated InfusionAll.js instead of individual required files. |
| Runs JSLint on all source code in the source directory. To specify a single directory, use |
Setting up the environment
What you will need
- Apache
Ant - The optional Ant task 'Script'
- Fluid Infusion source and build scripts
Getting and configuring Ant
- Download the latest full version of Ant from ant.apache.org
- Put it wherever you like. If you're on OS X and want to replace the default version, you'll put it in
/usr/sharewith admin privileges. - You may wish to check your installation according to the Ant installation instructions
Getting the optional Ant task 'Script'
- Inside your new ant directory, also with admin privileges (think "sudo" on Unix), run
ant -f fetch.xml -Ddest=system
Getting the Fluid Infusion source and build scripts
- Clone Fluid Infusion from Github:
git clone git://github.com/fluid-project/infusion.git