jmikola / js-assets-helper-bundle
Exposes the AssetsHelper service from Symfony2's templating component to JavaScript, allowing relative or absolute asset URI's to be generated client-side.
Installs: 12 581
Dependents: 0
Suggesters: 0
Security: 0
Stars: 19
Watchers: 7
Forks: 4
Open Issues: 0
Language:JavaScript
Type:symfony-bundle
Requires
- php: >=5.3.2
- symfony/dependency-injection: >=2.0.5,<3.0-dev
- symfony/framework-bundle: ~2.0
- symfony/twig-bundle: ~2.0
This package is auto-updated.
Last update: 2024-11-06 09:13:04 UTC
README
This bundle exposes the AssetsHelper service from Symfony2's templating component to JavaScript, which allows relative or absolute asset URI's to be generated client-side.
Compatibility
This bundle depends PR #2502, which is included in Symfony 2.0.5 and higher.
Configuration
If you do not configure the bundle explicitly, it will only expose the default
package defined in the templating
block of the FrameworkBundle configuration.
Named packages you wish to expose must be explicitly listed:
jmikola_js_assets_helper: packages_to_expose: [ cloudfront, s3 ]
While an array of package names is the normal format, the configuration will also accept a scalar to expose a single package:
jmikola_js_assets_helper: packages_to_expose: cloudfront
In these examples, "cloudfront" and "s3" correspond to named packages in the FrameworkBundle configuration. For example:
framework: templating: # The default package will be a PathPackage assets_version: 123 assets_version_format: "%%s?version=%%s" packages: # The cloudfront package will be a UrlPackage cloudfront: version: 123 version_format: "%%s?version=%%s" base_urls: https://example.cloudfront.net
Additional information on configuring templating asset packages may be found in the FrameworkBundle docs.
Routing
The bundle defines one route to a dynamically generated JavaScript file. Ensure this route is including in your application's routing configuration:
jmikola_js_assets_helper: resource: "@JmikolaJsAssetsHelperBundle/Resources/config/routing/routing.xml"
Assets
The bundle includes a compiled JavaScript asset, which must be published to your
web/
directory:
$ php app/console assets:install --symlink web
Include the compiled and dynamic JavaScript in your applications template:
<script src="{{ asset('bundles/jmikolajsassetshelper/js/assets_helper.js') }}"></script> <script src="{{ path('jmikola_js_assets_helper_js') }}"></script>
Usage
Once configured, the bundle creates a single AssetsHelper
global in JavaScript.
This is modeled after the PHP class from Symfony2's Templating component and
has the following methods:
/** * Returns the public path. * * Absolute paths (i.e. http://...) are returned unmodified. * * @param string path A public path * @param string packageName A package name (optional) * * @return string A public path which takes into account the base path and URL path */ function getUrl(path, packageName); /** * Gets the version to add to public URL. * * @param string packageName A package name (optional) * @return string The current version */ function getVersion(packageName);
Typically, you will want to use the getUrl()
method to generate asset paths.
Keep in mind that if you refer to a named package that has not been exposed, an
InvalidPackageError
will be thrown.
The following equivalent snippets demonstrate how AssetsHelper.getUrl()
compares to Symfony2's asset helper for Twig:
// JavaScript '<img src="' + AssetsHelper.getUrl('/images/logo.png') + '">';
{# Twig #} <img src="{{ asset('/images/logo.png') }}">
Development
Note: This bundle includes a static JavaScript asset, which is pre-compiled with Google's Closure Compiler. Any changes to the static JavaScript will require that you recompile the asset. For your convenience, you may want to install JMSGoogleClosureBundle and use the following command:
$ php app/console plovr:build @JmikolaJsAssetsHelperBundle/compile.js