Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Configuration

berarma edited this page · 27 revisions

Configuration

Asset Compress, like my other plugins, is configured with an ini file. The config file should be put in app/config/asset_compress.ini. The primary way of configuring AssetCompress is through the ini file. The ini file is used to configure where AssetCompress looks for files to compress.

The ini file is broken into a number of sections, that allow you to define general behavior for file extensions as well as define build files, and provide filter configuration.

A sample ini file would look like:

; Provide general configuration information
[General]
cacheConfig = true

; Define an extension type.
; build targets are prefixed with this value
; are connected when the ini file is parsed.
[js]
baseUrl = http://cdn.example.com
timestamp = true
paths[] = WEBROOT/js/*
cachePath = WEBROOT/cache_js/
filters[] = sprockets
filters[] = YuiJs

; filters can have configuration as well.
[filter_YuiJsFilter]
path = /path/to/yuicompressor

[filter_Uglifyjs]
uglify = /path/to/uglify-js

; Each target should have a section defining the files
; everything after js_ is considered the build file.
; all files included in the build are relative to the parent 
; paths key.
;
; targets can include their own filters.
[libs.js]
files[] = jquery.js
files[] = mootools.js
files[] = class.js
filters[] = Uglifyjs

; Create the CSS extension
[css]
baseUrl = http://cdn.example.com
paths[] = WEBROOT/css/
cachePath = WEBROOT/cache_css/

[all.css]
files[] = layout.css
filters[] = cssmin

There are a number of sections to a configuration file, so we'll go through them one at a time.

General

The first section in the above file, is the [General] section. It allows you to define plugin wide behavior, such as the debug mode, and baseUrl that assets should be linked to. Possible keys:

  • cacheConfig Setting this to true, will cause the parsed & populated configuration object to be cached into CakePHP's Cache class. It will be stored in the 'asset_compress' Cache configuration. This lets you store the serialized configuration object in fast storage like Memcache or APC.

Extension sections, js and css

Extension settings allow you to define the basic behavior for file extensions AssetCompress will be handling. Normally there are sections for [js] and [css]. The section name should match the extension of the files being built. Each section can define the following keys:

  • baseUrl Defines a base url that all assets should be included from, useful when you want to include assets from a CDN or static file domain. Should include the full domain name of the alternative server. e.g. http://cdn.example.com. No trailing slash is needed, it is also assumed that the complete static build files will be available on this alternate domain.
  • timestamp Should generated assets of the given extension have timestamps included in their filenames. This is useful when you want to bust browser caches when files change. See the section on timestamps for more information.
  • paths[] The paths that AssetCompress will find the component files for a build file. You can have as many paths as necessary and they will be searched in the order defined. The APP and WEBROOT constants will be replaced with the correct values. (The 3.0 branch also replaces ROOT, needed to access files in the vendor directory.)
  • cachePath The path assets should be 'cached' or saved to once built. This value needs to be set if you want to generate static build files with the plugin. A trailing slash is required
  • filters[] Define any number of filters to be applied to the all the built assets with this extension. The filters will be applied in the order they are defined.

Timestamping

If you set timestamp = true for an extension, AssetCompress will generate files with timestamps. In addition, it will create the file TMP/asset_compress_build_time. This file contains an array of build files and their timestamps. It should be deployed with your application, as it contains information used by the plugin to locate and correctly link to build files. If General.cacheConfig is true, the build times will be stored in the asset_compress cache config. This can be used to reduce file IO by putting timestamps in a faster cache engine.

Build file sections

Build file sections contain the build file name. For example, in the sample file above [libs.js] defines a JavaScript build file named libs.js. Build files need to be unique across your entire application. Defining duplicate build files will result in the last defined one being used. Build file sections can have the following keys:

  • baseUrl Defines a base url that all assets should be included from, useful when you want to include assets from a CDN or static file domain. Should include the full domain name of the alternative server. e.g. http://cdn.example.com. No trailing slash is needed, it is also assumed that the complete static build files will be available on this alternate domain.
  • files[] The files that compose this build file. Files will be concatenated in the order they are defined in this setting. Files are located on the extensions paths[]. If a file is not found, an exception is raised. There are a few prefixes that can be used to use files outside the configured paths. See below for special file types.
  • filters[] Additional filters that are applied to this build. Additional filters will be merged in with the extension wide filters, and be applied afterwards.
  • theme Set to true if the given build contains any theme files. This will tell AssetCompress to generate build files for each theme when running the console app. And to use the current theme in development mode.

Special file types

Theme assets

As of 0.5, CakePHP themes work with AssetCompress. You can define build files that use assets in themes. When the shell is run, a build file will be generated for each theme installed. This assumes that each theme has the same set of assets that need to be compressed. The theme name will be prepended to the generated asset name. A build definition would look like:

[app.css]
theme = true
files[] = reset.css
files[] = theme:css/design.css

Files prefixed with theme: or t: will be found inside the active theme. In the development controller, the current request's theme will be used. In the shell, a build file for each installed theme will be generated if possible. Build files for themes will be prefixed with the theme name to ensure unique files after generation. If you had a red theme, the above build would create red-app.css when generated.

Note Theme asset paths are relative to the webroot directory of the theme.

Plugin Assets

As of 0.6, you can include assets from plugins. Plugin assets can be included using the p or plugin prefix.

[app.css]
files[] = p:DebugKit:css/debug_toolbar.css
files[] = plugin:Blog:css/blog.css

The plugin and p prefixes are equivalent, and should be followed by the plugin name, and then the relative path from the plugin's webroot directory. Using plugin assets requires that the plugin is loaded via CakePlugin in your bootstrap.php file.

In addition to using plugin assets, each plugin in your application can provide an asset_compress.ini file in its Config/ directory. When AssetCompress loads configuration all asset_compress.ini files in plugins will also be loaded and merged into the configuration data.

Filter configuration sections

Filters can have settings defined for them. These settings are passed into the filters, settings() method. There is no list of generally supported keys, as each filter has different requirements. Filter sections are prefixed by filter_ and then the name of the filter. So [filter_Uglifyjs] defines the settings for the Uglifyjs filter.

Installation specific configuration files

As of 0.13 you applications, and plugins support .local files. Whenever an ini file is processed, AssetCompress will also load a .local.ini version of that file. The .local files are useful when you are dealing with multiple platforms that may have system tools like nodejs installed in different locations. Local configuration files can re-define any configuration section or property. Sections and properties defined in a local file will overwrite those defined in the base configuration file.

Something went wrong with that request. Please try again.