8000 Added the documentation for the new Asset component by javiereguiluz · Pull Request #4987 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

Added the documentation for the new Asset component #4987

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 9 commits into from
Closed

Added the documentation for the new Asset component #4987

Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
9e1ac65
Added the documentation for the new Asset component
javiereguiluz Feb 11, 2015
bc3403a
Minor rewording
javiereguiluz Feb 11, 2015
e6e2ba4
Added a missing link reference
javiereguiluz Feb 12, 2015
7312638
Tweaked documentation and added links to API methods/classes
javiereguiluz Feb 15, 2015
ac58089
Fixed a lot of errors and added an introduction
javiereguiluz Feb 16, 2015
9c456e3
Moved the component documentation to its own folder
javiereguiluz Feb 16, 2015
3c83243
Fixed some RST syntax issues
javiereguiluz Feb 16, 2015
6f7a63e
Fixed RST syntax issues
javiereguiluz Feb 19, 2015
6c2b2ee
Lots of fixes and rewordings
javiereguiluz Feb 20, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Fixed a lot of errors and added an introduction
  • Loading branch information
@javiereguiluz
javiereguiluz committed Feb 16, 2015
commit ac58089ccd4e3a15b7657b9fc5ad7188add27cc4
68 changes: 51 additions & 17 deletions components/asset.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,37 @@ The Asset Component
===================

The Asset component manages URL generation and versioning of web assets such
as CSS stylsheets, JavaScript files and image files.
as CSS stylesheets, JavaScript files and image files.

In the past, it was common for web applications to hardcode the URLs of the web
assets. For example:

.. code-block:: html

<link rel="stylesheet" type="text/css" href="/css/main.css">

<!-- ... -->

<a href="/"><img src="/images/logo.png"></a>

This practice is no longer recommended unless the web application is extremely
simple. The main problems of hardcoding asset URLs are the following:

* **Templates get verbose** because you have to write the full path for each
asset. When using the Asset component, you can group assets in packages to
avoid repeating the common part of their path.
* **Versioning is difficult** because it has to be custom managed for each
application. Adding a version to the asset URLs is essential for some applications
because it allows to control how the assets are cached. The Asset component
allows to define different versioning strategies for each package.
* **Moving assets location** is cumbersome and error-prone, because it requires
you to carefully update the URLs of all assets included in all templates.
The Asset component allows to move assets effortlessly just by changing the
base path value associated with the package of assets.
* **Impossible to use multiple CDNs** because it requires to change the URL of
the asset randomly for each request. The Asset component provides out-of-the-box
support for any number of multiple CDNs, both regular (``http://``) and
secure (``https://``).

Installation
------------
Expand All @@ -22,9 +52,10 @@ Usage
Asset Packages
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, I believe we're starting to quick with this more complex terminology. On IRC, we have lots of people that are often very confused with the term "asset" itself. Maybe we should first talk about that and show a very basic Asset component usage.

Btw, I would also propose to make the Package component default to the EmptyVersionStrategy. I don't think many people need versioning at their first encounter. Then the example can be very simple:

$package = new Package();

echo $package->getUrl('/image.png'); // /image.php

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In my opinion, the real problem was the lack of an introduction for the asset. In ac58089 I briefly explain the benefits that the Asset component provides comparing it with no using any asset management.

~~~~~~~~~~~~~~

The Asset component manages its assets through packages. A package groups all
the assets which use the same versioning strategy. In the following basic
example, a package is created to manage assets without any versioning::
The Asset component manages assets through packages. A package groups all the
assets which share the same properties: versioning strategy, base path, CDN hosts,
etc. In the following basic example, a package is created to manage assets without
any versioning::

use Symfony\Component\Asset\Package;
use Symfony\Component\Asset\VersionStrategy\EmptyVersionStrategy;
Expand Down Expand Up @@ -139,16 +170,19 @@ can take into account the context of the current request::
use Symfony\Component\Asset\Context\RequestStackContext;
// ...

$package = new PathPackage('/static/images', new StaticVersionStrategy('v1'));
$package->setContext(new RequestStackContext($requestStack));
$package = new PathPackage(
'/static/images',
new StaticVersionStrategy('v1'),
new RequestStackContext($requestStack)
);

echo $package->getUrl('/logo.png');
// result: /somewhere/static/images/logo.png?v1

When the request context is set, in addition to the configured base path,
:class:`Symfony\Component\Asset\PathPackage` also prepends the current request
base URL (``/somewhere/`` in this example) to assets. This allows your website
to be hosted anywhere under the web server root directory.
When the request context is set (via the third optional argument), in addition
to the configured base path, :class:`Symfony\Component\Asset\PathPackage` also
prepends the current request base URL (``/somewhere/`` in this example) to assets.
This allows your website to be hosted anywhere under the web server root directory.

Absolute Assets and CDNs
~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -202,9 +236,9 @@ protocol-relative URLs for HTTPs requests, any base URL for HTTP requests)::

$package = new UrlPackage(
array('http://example.com/', 'https://example.com/'),
new StaticVersionStrategy('v1')
new StaticVersionStrategy('v1'),
new RequestStackContext($requestStack)
);
$package->setContext(new RequestStackContext($requestStack));

echo $package->getUrl('/logo.png');
// result: https://example.com/logo.png?v1
Expand Down Expand Up @@ -237,11 +271,11 @@ they all have different base paths::

$packages = new Packages($defaultPackage, $namedPackages)

The :class:`Symfony\Component\Asset\Packages` class requires to define a default
package which will be applied to all assets except those which indicate the name
of the package to use. In addition, this application defines a package named
``img`` to serve images from an external domain and a ``doc`` package to avoid
repeating long paths when linking to a document inside a template::
The :class:`Symfony\Component\Asset\Packages` class allows to define a default
package, which will be applied to assets that don't define the name of package
to use. In addition, this application defines a package named ``img`` to serve
images from an external domain and a ``doc`` package to avoid repeating long
paths when linking to a document inside a template::

echo $packages->getUrl('/main.css');
// result: /main.css?v1
Expand Down
0