Assets Management
=================
:code:`Phalcon\Assets` is a component that allows you to manage static resources
such as CSS stylesheets or JavaScript libraries in a web application.
:doc:`Phalcon\\Assets\\Manager <../api/Phalcon_Assets_Manager>` is available in the services
container, so you can add resources from any part of the application where the container
is available.
Adding Resources
----------------
Assets supports two built-in resources: CSS and JavaScripts. You can create other
resources if you need. The assets manager internally stores two default collections
of resources - one for JavaScript and another for CSS.
You can easily add resources to these collections like follows:
.. code-block:: php
assets->addCss("css/style.css");
$this->assets->addCss("css/index.css");
// And some local JavaScript resources
$this->assets->addJs("js/jquery.js");
$this->assets->addJs("js/bootstrap.min.js");
}
}
Then in a view, these resources can be printed:
.. code-block:: html+php
Some amazing website
assets->outputCss(); ?>
assets->outputJs(); ?>
Volt syntax:
.. code-block:: html+jinja
Some amazing website
{{ assets.outputCss() }}
{{ assets.outputJs() }}
For better pageload performance, it is recommended to place JavaScript at the end of the HTML instead of in the :code:``.
Local/Remote resources
----------------------
Local resources are those who are provided by the same application and they're located in the document root
of the application. URLs in local resources are generated by the 'url' service, usually
:doc:`Phalcon\\Mvc\\Url <../api/Phalcon_Mvc_Url>`.
Remote resources are those such as common libraries like jQuery, Bootstrap, etc. that are provided by a CDN.
The second parameter of :code:`addCss()` and :code:`addJs()` says whether the resource is local or not (:code:`true` is local, :code:`false` is remote). By default, the assets manager will assume the resource is local:
.. code-block:: php
assets->addCss("//netdna.bootstrapcdn.com/twitter-bootstrap/2.3.1/css/bootstrap-combined.min.css", false);
$this->assets->addCss("css/style.css", true);
$this->assets->addCss("css/extra.css");
}
Collections
-----------
Collections group resources of the same type. The assets manager implicitly creates two collections: :code:`css` and :code:`js`.
You can create additional collections to group specific resources to make it easier to place those resources in the views:
.. code-block:: php
assets->collection("header");
$headerCollection->addJs("js/jquery.js");
$headerCollection->addJs("js/bootstrap.min.js");
// Javascripts in the footer
$footerCollection = $this->assets->collection("footer");
$footerCollection->addJs("js/jquery.js");
$footerCollection->addJs("js/bootstrap.min.js");
Then in the views:
.. code-block:: html+php
Some amazing website
assets->outputJs("header"); ?>
assets->outputJs("footer"); ?>
Volt syntax:
.. code-block:: html+jinja
Some amazing website
{{ assets.outputCss("header") }}
{{ assets.outputJs("footer") }}
URL Prefixes
------------
Collections can be URL-prefixed, this enables you to easily change from one server to another at any moment:
.. code-block:: php
assets->collection("footer");
if ($config->environment === "development") {
$footerCollection->setPrefix("/");
} else {
$footerCollection->setPrefix("http:://cdn.example.com/");
}
$footerCollection->addJs("js/jquery.js");
$footerCollection->addJs("js/bootstrap.min.js");
A chainable syntax is available too:
.. code-block:: php
collection("header")
->setPrefix("http://cdn.example.com/")
->setLocal(false)
->addJs("js/jquery.js")
->addJs("js/bootstrap.min.js");
Minification/Filtering
----------------------
:code:`Phalcon\Assets` provides built-in minification of JavaScript and CSS resources. You can create a collection of
resources instructing the Assets Manager which ones must be filtered and which ones must be left as they are.
In addition to the above, Jsmin by Douglas Crockford is part of the core extension offering minification of JavaScript files
for maximum performance. In the CSS land, CSSMin by Ryan Day is also available to minify CSS files:
The following example shows how to minify a collection of resources:
.. code-block:: php
collection("jsFooter")
// The name of the final output
->setTargetPath("final.js")
// The script tag is generated with this URI
->setTargetUri("production/final.js")
// This is a remote resource that does not need filtering
->addJs("code.jquery.com/jquery-1.10.0.min.js", false, false)
// These are local resources that must be filtered
->addJs("common-functions.js")
->addJs("page-functions.js")
// Join all the resources in a single file
->join(true)
// Use the built-in Jsmin filter
->addFilter(
new Phalcon\Assets\Filters\Jsmin()
)
// Use a custom filter
->addFilter(
new MyApp\Assets\Filters\LicenseStamper()
);
A collection can contain JavaScript or CSS
resources but not both. Some resources may be remote, that is, they're obtained by HTTP from a remote source
for further filtering. It is recommended to convert the external resources to local for better performance.
As seen above, the :code:`addJs()` method is used to add resources to the collection, the second parameter indicates
whether the resource is external or not and the third parameter indicates whether the resource should
be filtered or left as is:
.. code-block:: php
collection("jsFooter");
// This a remote resource that does not need filtering
$jsFooterCollection->addJs("code.jquery.com/jquery-1.10.0.min.js", false, false);
// These are local resources that must be filtered
$jsFooterCollection->addJs("common-functions.js");
$jsFooterCollection->addJs("page-functions.js");
Filters are registered in the collection, multiple filters are allowed, content in resources are filtered
in the same order as filters were registered:
.. code-block:: php
addFilter(
new Phalcon\Assets\Filters\Jsmin()
);
// Use a custom filter
$jsFooterCollection->addFilter(
new MyApp\Assets\Filters\LicenseStamper()
);
Note that both built-in and custom filters can be transparently applied to collections.
The last step is to decide if all the resources in the collection must be joined into a single file or serve each of them
individually. To tell the collection that all resources must be joined you can use the :code:`join()` method.
If resources are going to be joined, we need also to define which file will be used to store the resources
and which URI will be used to show it. These settings are set up with :code:`setTargetPath()` and :code:`setTargetUri()`:
.. code-block:: php
join(true);
// The name of the final file path
$jsFooterCollection->setTargetPath("public/production/final.js");
// The script HTML tag is generated with this URI
$jsFooterCollection->setTargetUri("production/final.js");
If resources are going to be joined, we need also to define which file will be used to store the resources
and which URI will be used to show it. These settings are set up with :code:`setTargetPath()` and :code:`setTargetUri()`.
Built-In Filters
^^^^^^^^^^^^^^^^
Phalcon provides 2 built-in filters to minify both JavaScript and CSS, their C-backend provide
the minimum overhead to perform this task:
+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+
| Filter | Description |
+=================================================================================+==============================================================================================================+
| :doc:`Phalcon\\Assets\\Filters\\Jsmin <../api/Phalcon_Assets_Filters_Jsmin>` | Minifies JavaScript by removing unnecessary characters that are ignored by Javascript interpreters/compilers |
+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+
| :doc:`Phalcon\\Assets\\Filters\\Cssmin <../api/Phalcon_Assets_Filters_Cssmin>` | Minifies CSS by removing unnecessary characters that are already ignored by browsers |
+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+
Custom Filters
^^^^^^^^^^^^^^
In addition to the built-in filters, you can create your own filters. These can take advantage of existing
and more advanced tools like YUI_, Sass_, Closure_, etc.:
.. code-block:: php
_options = $options;
}
/**
* Do the filtering
*
* @param string $contents
*
* @return string
*/
public function filter($contents)
{
// Write the string contents into a temporal file
file_put_contents("temp/my-temp-1.css", $contents);
system(
$this->_options["java-bin"] .
" -jar " .
$this->_options["yui"] .
" --type css " .
"temp/my-temp-file-1.css " .
$this->_options["extra-options"] .
" -o temp/my-temp-file-2.css"
);
// Return the contents of file
return file_get_contents("temp/my-temp-file-2.css");
}
}
Usage:
.. code-block:: php
assets->get("head");
// Add/Enable the YUI compressor filter in the collection
$css->addFilter(
new CssYUICompressor(
[
"java-bin" => "/usr/local/bin/java",
"yui" => "/some/path/yuicompressor-x.y.z.jar",
"extra-options" => "--charset utf8",
]
)
);
In a previous example, we used a custom filter called :code:`LicenseStamper`:
.. code-block:: php
assets->collection("js");
foreach ($jsCollection as $resource) {
echo Tag::javascriptInclude(
$resource->getPath()
);
}
.. _YUI: http://yui.github.io/yuicompressor/
.. _Closure: https://developers.google.com/closure/compiler/?hl=fr
.. _Sass: http://sass-lang.com/