Yii clientScript

I am having an issue with the clientScript and assetManager. I'm publishing a directory of files and then adding a package which I later register. The package gets added just fine but when it gets rendered the url is wrong.

Publishing the files and adding the package:

The package is added just fine and published to a asset directory in the application, this is the output from Yii::app()->clientScript->packages.

Although, when I register the package width Yii::app()->clientScript->registerPackage('jquery.dropdown') this is what gets rendered:

Notice the URL in the src attribute, wrong directory. Have anyone encountered this before and/or know what's wrong?

• answered 2013-04-19 09:40 Lifesnoozer

Your problem lies with the following

The package manager actually publishes the package for you, so what you're doing here is publishing the same file twice. Set $scriptFiles to Yii::getPathOfAlias('library').'/assets/jquery.plugins/jquery.dropdown/ instead and it should work fine.

Yii2 по-русски, документация Yii Framework 2

An asset in Yii is a file that may be referenced in a Web page. It can be a CSS file, a JavaScript file, an image or video file, etc. Assets are located in Web-accessible directories and are directly served by Web servers.

It is often preferable to manage assets programmatically. For example, when you use the yii\jui\DatePicker widget in a page, it will automatically include the required CSS and JavaScript files, instead of asking you to manually find these files and include them. And when you upgrade the widget to a new version, it will automatically use the new version of the asset files. In this tutorial, we will describe the powerful asset management capability provided in Yii.

Yii manages assets in the unit of asset bundle. An asset bundle is simply a collection of assets located in a directory. When you register an asset bundle in a view. it will include the CSS and JavaScript files in the bundle in the rendered Web page.

Asset bundles are specified as PHP classes extending from yii\web\AssetBundle. The name of a bundle is simply its corresponding fully qualified PHP class name (without the leading backslash). An asset bundle class should be autoloadable. It usually specifies where the assets are located, what CSS and JavaScript files the bundle contains, and how the bundle depends on other bundles.

The following code defines the main asset bundle used by the basic application template :

The above AppAsset class specifies that the asset files are located under the @webroot directory which corresponds to the URL @web ; the bundle contains a single CSS file css/site.css and no JavaScript file; the bundle depends on two other bundles: yii\web\YiiAsset and yii\bootstrap\BootstrapAsset. More detailed explanation about the properties of yii\web\AssetBundle can be found in the following:

• sourcePath. specifies the root directory that contains the asset files in this bundle. This property should be set if the root directory is not Web accessible. Otherwise, you should set the basePath property and baseUrl. instead. Path aliases can be used here.
• basePath. specifies a Web-accessible directory that contains the asset files in this bundle. When you specify the sourcePath property, the asset manager will publish the assets in this bundle to a Web-accessible directory and overwrite this property accordingly. You should set this property if your asset files are already in a Web-accessible directory and do not need asset publishing. Path aliases can be used here.
• baseUrl. specifies the URL corresponding to the directory basePath. Like basePath. if you specify the sourcePath property, the asset manager will publish the assets and overwrite this property accordingly. Path aliases can be used here.
• js. an array listing the JavaScript files contained in this bundle. Note that only forward slash "/" should be used as directory separators. Each JavaScript file can be specified in one of the following two formats:
  • a relative path representing a local JavaScript file (e.g. js/main.js ). The actual path of the file can be determined by prepending yii\web\AssetManager::$basePath to the relative path, and the actual URL of the file can be determined by prepending yii\web\AssetManager::$baseUrl to the relative path.
  • an absolute URL representing an external JavaScript file. For example, http://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js or //ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js .
• css. an array listing the CSS files contained in this bundle. The format of this array is the same as that of js .
• depends. an array listing the names of the asset bundles that this bundle depends on (to be explained shortly).
• jsOptions. specifies the options that will be passed to the yii\web\View::registerJsFile() method when it is called to register every JavaScript file in this bundle.
• cssOptions. specifies the options that will be passed to the yii\web\View::registerCssFile() method when it is called to register every CSS file in this bundle.
• publishOptions. specifies the options that will be passed to the yii\web\AssetManager::publish() method when it is called to publish source asset files to a Web directory. This is only used if you specify the sourcePath property.

Assets, based on their location, can be classified as:

• source assets: the asset files are located together with PHP source code which cannot be directly accessed via Web. In order to use source assets in a page, they should be copied to a Web directory and turned into the so-called published assets. This process is called asset publishing which will be described in detail shortly.
• published assets: the asset files are located in a Web directory and can thus be directly accessed via Web.
• external assets: the asset files are located on a Web server that is different from the one hosting your Web application.

When defining an asset bundle class, if you specify the sourcePath property, it means any assets listed using relative paths will be considered as source assets. If you do not specify this property, it means those assets are published assets (you should therefore specify basePath and baseUrl to let Yii know where they are located).

It is recommended that you place assets belonging to an application in a Web directory to avoid the unnecessary asset publishing process. This is why AppAsset in the prior example specifies basePath instead of sourcePath .

For extensions. because their assets are located together with their source code in directories that are not Web accessible, you have to specify the sourcePath property when defining asset bundle classes for them.

Note: Do not use @webroot/assets as the source path. This directory is used by default by the asset manager to save the asset files published from their source location. Any content in this directory is considered temporarily and may be subject to removal.

When you include multiple CSS or JavaScript files in a Web page, they have to follow a certain order to avoid overriding issues. For example, if you are using a jQuery UI widget in a Web page, you have to make sure the jQuery JavaScript file is included before the jQuery UI JavaScript file. We call such ordering the dependencies among assets.

Asset dependencies are mainly specified through the yii\web\AssetBundle::$depends property. In the AppAsset example, the asset bundle depends on two other asset bundles: yii\web\YiiAsset and yii\bootstrap\BootstrapAsset. which means the CSS and JavaScript files in AppAsset will be included after those files in the two dependent bundles.

Asset dependencies are transitive. This means if bundle A depends on B which depends on C, A will depend on C, too.

You can specify the cssOptions and jsOptions properties to customize the way that CSS and JavaScript files are included in a page. The values of these properties will be passed to the yii\web\View::registerCssFile() and yii\web\View::registerJsFile() methods, respectively, when they are called by the view to include CSS and JavaScript files.

Note: The options you set in a bundle class apply to every CSS/JavaScript file in the bundle. If you want to use different options for different files, you should create separate asset bundles, and use one set of options in each bundle.

For example, to conditionally include a CSS file for browsers that are IE9 or below, you can use the following option:

This will cause a CSS file in the bundle to be included using the following HTML tags:

To wrap the generated CSS link tags within <noscript>. you can configure cssOptions as follows,

To include a JavaScript file in the head section of a page (by default, JavaScript files are included at the end of the body section), use the following option:

By default, when an asset bundle is being published, all contents in the directory specified by yii\web\AssetBundle::$sourcePath will be published. You can customize this behavior by configuring the publishOptions property. For example, to publish only one or a few subdirectories of yii\web\AssetBundle::$sourcePath. you can do the following in the asset bundle class:

The above example defines an asset bundle for the "fontawesome" package. By specifying the beforeCopy publishing option, only the fonts and css subdirectories will be published.

Most JavaScript/CSS packages are managed by Bower and/or NPM. If your application or extension is using such a package, it is recommended that you follow these steps to manage the assets in the library:

1. Modify the composer.json file of your application or extension and list the package in the require entry. You should use bower-asset/PackageName (for Bower packages) or npm-asset/PackageName (for NPM packages) to refer to the library.
2. Create an asset bundle class and list the JavaScript/CSS files that you plan to use in your application or extension. You should specify the sourcePath property as @bower/PackageName or @npm/PackageName. This is because Composer will install the Bower or NPM package in the directory corresponding to this alias.

Note: Some packages may put all their distributed files in a subdirectory. If this is the case, you should specify the subdirectory as the value of sourcePath. For example, yii\web\JqueryAsset uses @bower/jquery/dist instead of @bower/jquery .

To use an asset bundle, register it with a view by calling the yii\web\AssetBundle::register() method. For example, in a view template you can register an asset bundle like the following:

Info: The yii\web\AssetBundle::register() method returns an asset bundle object containing the information about the published assets, such as basePath or baseUrl .

If you are registering an asset bundle in other places, you should provide the needed view object. For example, to register an asset bundle in a widget class, you can get the view object by $this->view .

When an asset bundle is registered with a view, behind the scenes Yii will register all its dependent asset bundles. And if an asset bundle is located in a directory inaccessible through the Web, it will be published to a Web directory. Later, when the view renders a page, it will generate <link> and <script> tags for the CSS and JavaScript files listed in the registered bundles. The order of these tags is determined by the dependencies among the registered bundles and the order of the assets listed in the yii\web\AssetBundle::$css and yii\web\AssetBundle::$js properties.

Yii manages asset bundles through an application component named assetManager which is implemented by yii\web\AssetManager. By configuring the yii\web\AssetManager::$bundles property, it is possible to customize the behavior of an asset bundle. For example, the default yii\web\JqueryAsset asset bundle uses the jquery.js file from the installed jquery Bower package. To improve the availability and performance, you may want to use a version hosted by Google. This can be achieved by configuring assetManager in the application configuration like the following:

You can configure multiple asset bundles similarly through yii\web\AssetManager::$bundles. The array keys should be the class names (without the leading backslash) of the asset bundles, and the array values should be the corresponding configuration arrays .

Tip: You can conditionally choose which assets to use in an asset bundle. The following example shows how to use jquery.js in the development environment and jquery.min.js otherwise:

You can disable one or multiple asset bundles by associating false with the names of the asset bundles that you want to disable. When you register a disabled asset bundle with a view, none of its dependent bundles will be registered, and the view also will not include any of the assets in the bundle in the page it renders. For example, to disable yii\web\JqueryAsset. you can use the following configuration:

You can also disable all asset bundles by setting yii\web\AssetManager::$bundles as false .

Sometimes you may want to "fix" incorrect/incompatible asset file paths used in multiple asset bundles. For example, bundle A uses jquery.min.js version 1.11.1, and bundle B uses jquery.js version 2.1.1. While you can fix the problem by customizing each bundle, an easier way is to use the asset map feature to map incorrect assets to the desired ones. To do so, configure the yii\web\AssetManager::$assetMap property like the following:

The keys of assetMap are the asset names that you want to fix, and the values are the desired asset paths. When you register an asset bundle with a view, each relative asset file in its css and js arrays will be examined against this map. If any of the keys are found to be the last part of an asset file (which is prefixed with yii\web\AssetBundle::$sourcePath if available), the corresponding value will replace the asset and be registered with the view. For example, the asset file my/path/to/jquery.js matches the key jquery.js .

Note: Only assets specified using relative paths are subject to asset mapping. The target asset paths should be either absolute URLs or paths relative to yii\web\AssetManager::$basePath .

As aforementioned, if an asset bundle is located in a directory that is not Web accessible, its assets will be copied to a Web directory when the bundle is being registered with a view. This process is called asset publishing. and is done automatically by the asset manager .

By default, assets are published to the directory @webroot/assets which corresponds to the URL @web/assets. You may customize this location by configuring the basePath and baseUrl properties.

Instead of publishing assets by file copying, you may consider using symbolic links, if your OS and Web server allow. This feature can be enabled by setting linkAssets to be true.

With the above configuration, the asset manager will create a symbolic link to the source path of an asset bundle when it is being published. This is faster than file copying and can also ensure that the published assets are always up-to-date.

The core Yii code has defined many asset bundles. Among them, the following bundles are commonly used and may be referenced in your application or extension code.

• yii\web\YiiAsset. It mainly includes the yii.js file which implements a mechanism of organizing JavaScript code in modules. It also provides special support for data-method and data-confirm attributes and other useful features.
• yii\web\JqueryAsset. It includes the jquery.js file from the jQuery Bower package.
• yii\bootstrap\BootstrapAsset. It includes the CSS file from the Twitter Bootstrap framework.
• yii\bootstrap\BootstrapPluginAsset. It includes the JavaScript file from the Twitter Bootstrap framework for supporting Bootstrap JavaScript plugins.
• yii\jui\JuiAsset. It includes the CSS and JavaScript files from the jQuery UI library.

If your code depends on jQuery, jQuery UI or Bootstrap, you should use these predefined asset bundles rather than creating your own versions. If the default setting of these bundles do not satisfy your needs, you may customize them as described in the Customizing Asset Bundle subsection.

Instead of directly writing CSS and/or JavaScript code, developers often write them in some extended syntax and use special tools to convert it into CSS/JavaScript. For example, for CSS code you may use LESS or SCSS ; and for JavaScript you may use TypeScript .

You can list the asset files in extended syntax in the css and js properties of an asset bundle. For example,

When you register such an asset bundle with a view, the asset manager will automatically run the pre-processor tools to convert assets in recognized extended syntax into CSS/JavaScript. When the view finally renders a page, it will include the CSS/JavaScript files in the page, instead of the original assets in extended syntax.

Yii uses the file name extensions to identify which extended syntax an asset is in. By default it recognizes the following syntax and file name extensions:

Yii relies on the installed pre-processor tools to convert assets. For example, to use LESS you should install the lessc pre-processor command.

You can customize the pre-processor commands and the supported extended syntax by configuring yii\web\AssetManager::$converter like the following:

In the above, we specify the supported extended syntax via the yii\web\AssetConverter::$commands property. The array keys are the file extension names (without leading dot), and the array values are the resulting asset file extension names and the commands for performing the asset conversion. The tokens and in the commands will be replaced with the source asset file paths and the target asset file paths.

Info: There are other ways of working with assets in extended syntax, besides the one described above. For example, you can use build tools such as grunt to monitor and automatically convert assets in extended syntax. In this case, you should list the resulting CSS/JavaScript files in asset bundles rather than the original files.

A Web page can include many CSS and/or JavaScript files. To reduce the number of HTTP requests and the overall download size of these files, a common practice is to combine and compress multiple CSS/JavaScript files into one or very few files, and then include these compressed files instead of the original ones in the Web pages.

Info: Combining and compressing assets is usually needed when an application is in production mode. In development mode, using the original CSS/JavaScript files is often more convenient for debugging purposes.

In the following, we introduce an approach to combine and compress asset files without the need to modify your existing application code.

1. Find all the asset bundles in your application that you plan to combine and compress.
2. Divide these bundles into one or a few groups. Note that each bundle can only belong to a single group.
3. Combine/compress the CSS files in each group into a single file. Do this similarly for the JavaScript files.
4. Define a new asset bundle for each group:
   • Set the css and js properties to be the combined CSS and JavaScript files, respectively.
   • Customize the asset bundles in each group by setting their css and js properties to be empty, and setting their depends property to be the new asset bundle created for the group.

Using this approach, when you register an asset bundle in a view, it causes the automatic registration of the new asset bundle for the group that the original bundle belongs to. And as a result, the combined/compressed asset files are included in the page, instead of the original ones.

Let's use an example to further explain the above approach.

Assume your application has two pages, X and Y. Page X uses asset bundles A, B and C, while Page Y uses asset bundles B, C and D.

You have two ways to divide these asset bundles. One is to use a single group to include all asset bundles, the other is to put A in Group X, D in Group Y, and (B, C) in Group S. Which one is better? It depends. The first way has the advantage that both pages share the same combined CSS and JavaScript files, which makes HTTP caching more effective. On the other hand, because the single group contains all bundles, the size of the combined CSS and JavaScript files will be bigger and thus increase the initial file transmission time. For simplicity in this example, we will use the first way, i.e. use a single group to contain all bundles.

Info: Dividing asset bundles into groups is not trivial task. It usually requires analysis about the real world traffic data of various assets on different pages. At the beginning, you may start with a single group for simplicity.

Use existing tools (e.g. Closure Compiler. YUI Compressor ) to combine and compress CSS and JavaScript files in all the bundles. Note that the files should be combined in the order that satisfies the dependencies among the bundles. For example, if Bundle A depends on B which depends on both C and D, then you should list the asset files starting from C and D, followed by B and finally A.

After combining and compressing, we get one CSS file and one JavaScript file. Assume they are named as all-xyz.css and all-xyz.js. where xyz stands for a timestamp or a hash that is used to make the file name unique to avoid HTTP caching problems.

We are at the last step now. Configure the asset manager as follows in the application configuration:

As explained in the Customizing Asset Bundles subsection, the above configuration changes the default behavior of each bundle. In particular, Bundle A, B, C and D no longer have any asset files. They now all depend on the all bundle which contains the combined all-xyz.css and all-xyz.js files. Consequently, for Page X, instead of including the original source files from Bundle A, B and C, only these two combined files will be included; the same thing happens to Page Y.

There is one final trick to make the above approach work more smoothly. Instead of directly modifying the application configuration file, you may put the bundle customization array in a separate file and conditionally include this file in the application configuration. For example,

That is, the asset bundle configuration array is saved in assets-prod.php for production mode, and assets-dev.php for non-production mode.

Yii provides a console command named asset to automate the approach that we just described.

To use this command, you should first create a configuration file to describe what asset bundles should be combined and how they should be grouped. You can use the asset/template sub-command to generate a template first and then modify it to fit for your needs.

The command generates a file named assets.php in the current directory. The content of this file looks like the following:

You should modify this file and specify which bundles you plan to combine in the bundles option. In the targets option you should specify how the bundles should be divided into groups. You can specify one or multiple groups, as aforementioned.

Note: Because the alias @webroot and @web are not available in the console application, you should explicitly define them in the configuration.

Ресурсы - Рецепты

Yii имеет встроенный механизм публикации ресурсов (asset). Он полезен в следующих случаях:

• При оформлении кода как расширения, ресурсы которого содержатся в той же папке, что и код.
• При использовании ресурсов за корнем вебсервера.
• Для обработки ресурсов непосредственно перед публикацией. Например, сжатия CSS и JavaScript.
• При использовании одного и того же ресурса множеством компонент (для исключения дубликатов).

Примечание: Для работы с ресурсами в корне вебсервера должна быть создана папка assets с правами на запись для PHP.

Публикацией ресурсов активно пользуется сам фреймворк. Происходит это, например, при использовании CLinkPager или CGridView .

После нескольких запусков приложения в assets образуется примерно следующее содержимое:

Папки вида 1a6630a0 создаются для предотвращения конфликта имён ресурсов.

Здесь 1a6630a0 — хеш от полного пути к папке, в которой размещён подключаемый ресурс.

Подсказка: Получить текущий или задать новый полный путь к папке assets можно при помощи Yii::app()->assetManager->basePath. а URL при помощи Yii::app()->assetManager->baseUrl .

Для публикации ресурса или папки с ресурсами используется метод CAssetManager::publish. принимающий следующие параметры:

• $path — путь к ресурсу или папке с ресурсами.
• $hashByName — сохранять ли один и тот же хэш при нескольких публикациях. Полезно при использовании ресурса несколькими компонентами. По умолчанию равен false .
• $level — уровень вложенности при копировании папки. При -1 копирует всё. При 0 — только файлы в корневой папке.
• $forceCopy — копировать ресурс даже если он уже опубликован. Удобно использовать во время разработки задав значение как YII_DEBUG. Не рекомендуется использовать на живом проекте, так как производительность падает.

Возвращается абсолютный URL опубликованного ресурса.

Примечание: При публикации отдельного ресурса, во избежание ненужного копирования проверяется время его модификации. При обновлении ресурса автоматически происходит его перепубликация.

Ресурсы – Руководство пользователя Yii 2

Ресурс в Yii — это файл который может быть задан для Веб-страницы. Это может быть CSS файл, JavaScript файл, изображение или видео файл и т.д. Ресурсы размещаются в доступных для веб-сервера директориях.

Желательно, управлять ресурсами программно. Например, при использовании виджета yii\jui\DatePicker на странице, автоматически подключаются необходимые CSS и JavaScript файлы, вместо того чтобы заставлять вас в ручную искать эти файлы и подключать их. Также когда вы обновляете виджет до новой версии, будут автоматически использованы новые версии файлов-ресурсов. В этом руководстве будет описана возможность управления ресурсами представленная в Yii.

Yii управляет ресурсами как единицей комплекта ресурсов. Комплект ресурсов — это простой набор ресурсов расположенных в директории. Когда вы регистрируете комплект ресурсов в представлении. на отображаемой Веб-странице включается набор этих CSS и JavaScript файлов.

Комплект ресурсов определяется как PHP класс, расширяющийся от yii\web\AssetBundle. Имя комплекта соответствует полному имени PHP класса (без ведущей обратной косой черты — backslash "\"). Класс комплекта ресурса должен быть в состоянии возможности автозагрузки. При определении комплекта ресурсов обычно указывается где ресурсы находятся, какие CSS и JavaScript файлы содержит комплект, и как комплект зависит от других комплектов.

Следующий код определяет основной комплект ресурсов используемый в шаблоне базового приложения :

В коде выше класс AppAsset указывает, что файлы ресурса находятся в директории @webroot. которой соответствует адресу @web ; комплект содержит единственный CSS файл css/site.css и не содержит JavaScript файлов; комплект зависит от двух других комплектов: yii\web\YiiAsset и yii\bootstrap\BootstrapAsset. Более подробное описание о свойствах yii\web\AssetBundle может быть найдено ниже:

• sourcePath. определяет корневую директорию содержащую файлы ресурса в этом комплекте. Это свойство должно быть установлено, если корневая директория не доступна для веб-сервера. В противном случае, вы должны установить свойство basePath и свойство baseUrl вместо текущего. Здесь могут быть использованы псевдонимы путей .
• basePath. определяет директорию, которая доступна веб-серверу, содержащая файлы ресурсов текущего комплекта. Когда вы определяете свойство sourcePath. менеджер ресурсов опубликует ресурсы текущего комплекта в директорию доступную веб-серверу и перезапишет соответственно данное свойство. Вы должны задать данное свойство если ваши файлы ресурсов уже находятся в директории, которая доступна веб-серверу и не нужно опубликовывать эти ресурсы. Здесь могут быть использованы псевдонимы путей.
• baseUrl. определяет URL-адрес соответствующей директории basePath. Также как и для basePath. если вы определяете свойство sourcePath. менеджер ресурсов опубликует ресурсы и перезапишет это свойство соответственно. Здесь могут быть использованы псевдонимы путей .

js. массив, перечисляющий JavaScript файлы, содержащиеся в данном комплекте. Заметьте, что только прямая косая черта (forward slash — "/") может быть использована, как разделитель директорий. Каждый JavaScript файл может быть задан в одном из следующих форматов:

• относительный путь, представленный локальным JavaScript файлом (например js/main.js ). Актуальный путь файла может быть определён путём добавления yii\web\AssetManager::$basePath к относительному пути, и актуальный URL-адрес файла может быть определён путём добавления yii\web\AssetManager::$baseUrl к относительному пути.
• абсолютный URL, представленный внешним JavaScript файлом. Например, http://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js или //ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js .

Ресурсы, в зависимости от их расположения, могут быть классифицированы как:

• исходные ресурсы: файлы ресурсов, расположенные вместе с исходным кодом PHP, которые не могут быть непосредственно доступны веб-серверу. Для того, чтобы использовать исходные ресурсы на странице, они должны быть скопированы в директорию, которая доступна веб-серверу и превратиться в так называемые опубликованные ресурсы. Этот процесс называется публикацией ресурсов, который более подробно будет описан в ближайшее время.
• опубликованные ресурсы: файлы ресурсов, расположенные в директории, которая доступна веб-серверу, и таким образом эти файлы будут доступны веб-серверу.
• внешние ресурсы: файлы ресурсов, расположенные на другом веб-сервере, отличного от веб-хостинга вашего приложения.

При определении класса комплекта ресурсов, если вы задаёте свойство sourcePath. это означает, что любые перечисленные ресурсы, используя относительные пути, будут рассматриваться как исходные ресурсы. Если вы не задаёте данное свойство, это означает, что эти ресурсы — опубликованные ресурсы (в этом случае вам следует указать basePath и baseUrl. чтобы дать знать Yii где ресурсы располагаются).

Рекомендуется размещать ресурсы, принадлежащие приложению, в директорию, которая доступна веб-серверу, для того, чтобы избежать не нужного процесса публикации ресурсов. Вот почему AppAsset в предыдущем примере задаёт basePath вместо sourcePath .

Для расширений, в связи с тем, что их ресурсы располагаются вместе с их исходным кодом в директориях, которые не являются доступными для веб-сервера, необходимо указать свойство sourcePath при определении класса комплекта ресурсов для них.

Примечание. Не используйте @webroot/assets как source path. Эта директория по умолчанию используется менеджером ресурсов для сохранения файлов ресурсов, опубликованных из их исходного месторасположения. Любое содержимое этой директории расценивается как временное и может быть удалено.

Когда вы включаете несколько CSS или JavaScript файлов на веб-страницу, они должны следовать в определенном порядке, чтобы избежать переопределения при выдаче. Например, если вы используете виджет jQuery UI на веб-странице, вы должны убедиться, что jQuery JavaScript файл был включен до jQuery UI JavaScript файла. Мы называем такой порядок зависимостью между ресурсами.

Зависимости ресурсов в основном указываются через свойство yii\web\AssetBundle::$depends. Например в AppAsset. комплект ресурсов зависит от двух других комплектов ресурсов: yii\web\YiiAsset и yii\bootstrap\BootstrapAsset. это обозначает, что CSS и JavaScript файлы AppAsset будут включены после файлов этих двух комплектов зависимостей.

Зависимости ресурсов являются также зависимыми. Это значит, что если комплект А зависит от В, который зависит от С, то А тоже зависит от С.

Вы можете задать свойства cssOptions и jsOptions. чтобы настроить путь для включения CSS и JavaScript файлов для страницы. Значения этих свойств будут приняты методами yii\web\View::registerCssFile() и yii\web\View::registerJsFile() соответственно, когда они (методы) вызываются представлением. происходит включение CSS и JavaScript файлов.

Примечание. Параметры, заданные в комплекте класса применяются для каждого CSS/JavaScript-файла в комплекте. Если вы хотите использовать различные параметры для разных файлов, вы должны создать раздельные комплекты ресурсов, и использовать одну установку параметров для каждого комплекта.

Например, условно включим CSS файл для браузера IE9 или ниже. Для этого вы можете использовать следующий параметр:

Это вызовет CSS файл из комплекта, который будет подключен на страницу, используя следующие HTML-теги:

Для того чтобы обернуть созданную CSS ссылку в тег <noscript>, вы можете настроить cssOptions следующим образом:

Для включения JavaScript файла в head раздел страницы (по умолчанию, JavaScript файлы включаются в конец раздела body) используйте следующий параметр:

В выше указанном примере определён комплект ресурсов для пакета «fontawesome». Задан параметр публикации only. здесь только fonts и css поддиректории будут опубликованы.

Большинство JavaScript/CSS пакетов управляются Bower и/или NPM. Если вашим приложением или расширением используется такой пакет, то рекомендуется следовать следующим этапам для управления ресурсами библиотеки:

1. Исправить файл composer.json вашего приложения или расширения и включить пакет в список в раздел require. Следует использовать bower-asset/PackageName (для Bower пакетов) или npm-asset/PackageName (для NPM пакетов) для обращения к соответствующей библиотеке.
2. Создать класс комплекта ресурсов и перечислить JavaScript/CSS файлы, которые вы планируете использовать в вашем приложении или расширении. вы должны задать свойство sourcePath как @bower/PackageName или @npm/PackageName. Это происходит потому, что Composer устанавливает Bower или NPM пакет в директорию, соответствующую этим псевдонимам.

Примечание. В некоторых пакетах файлы дистрибутива могут находиться в поддиректории. В этом случае, вы должны задать поддиректорию как значение sourcePath. Например, yii\web\JqueryAsset использует @bower/jquery/dist вместо @bower/jquery .

Для использования комплекта ресурсов, зарегистрируйте его в представлении вызвав метод yii\web\AssetBundle::register(). Например, комплект ресурсов в представлении может быть зарегистрирован следующим образом:

Метод yii\web\AssetBundle::register() возвращает объект комплекта ресурсов, содержащий информацию о публикуемых ресурсах, таких как basePath или baseUrl .

Если вы регистрируете комплект ресурсов в других местах (т.е. не в представлении), вы должны обеспечить необходимый объект представления. Например, при регистрации комплекта ресурсов в классе widget. вы можете взять за объект представления $this->view .

Когда комплект ресурсов регистрируется в представлении, Yii регистрирует все зависимые от него комплекты ресурсов. И, если комплект ресурсов расположен в директории, которая не доступна веб-серверу, тогда он будет опубликован в директории, которая доступна веб-серверу. Затем, когда представление отображает страницу, сгенерируются теги <link> и <script> для CSS и JavaScript файлов, перечисленных в регистрируемых комплектах. Порядок этих тегов определён зависимостью среди регистрируемых комплектов, и последовательность ресурсов перечислена в yii\web\AssetBundle::$css и yii\web\AssetBundle::#js свойствах.

Yii управляет комплектами ресурсов через компонент приложения, который называется assetManager. он реализован в пространстве yii\web\AssetManager. Путём настройки свойства yii\web\AssetManager::$bundles. возможно настроить поведение комплекта ресурсов. Например, комплект ресурсов yii\web\JqueryAsset по умолчанию использует jquery.js файл из установленного jquery Bower пакета. Для повышения доступности и производительности, можно использовать версию jquery на Google хостинге. Это может быть достигнуто, настроив assetManager в конфигурации приложения следующим образом:

Можно сконфигурировать несколько комплектов ресурсов аналогично через yii\web\AssetManager::bundles. Ключи массива должны быть именами класса (без впереди стоящей обратной косой черты) комплектов ресурсов, а значения массивов должны соответствовать конфигурации массивов .

Совет. Можно условно выбрать, какой из ресурсов будет использован в комплекте ресурсов. Следующий пример показывает, как можно использовать в разработке окружения jquery.js или jquery.min.js в противном случае:

Можно запретить один или несколько комплектов ресурсов, связав false с именами комплектов ресурсов, которые вы хотите сделать недоступными. Когда вы регистрируете недоступный комплект ресурсов в представлении, обратите внимание, что зависимость комплектов будет зарегистрирована, и представление также не включит ни один из ресурсов комплекта в отображаемую страницу. Например, для запрета yii\web\JqueryAsset можно использовать следующую конфигурацию:

Можно также запретить все комплекты ресурсов, установив yii\web\AssetManager::$bundles как false .

Иногда необходимо исправить пути до файлов ресурсов, в нескольких комплектах ресурсов. Например, комплект А использует jquery.min.js версии 1.11.1, а комплект В использует jquery.js версии 2.1.1. Раньше вы могли решить данную проблему, настраивая каждый комплект ресурсов по отдельности, но более простой способ — использовать asset map возможность, чтобы найти неверные ресурсы и исправить их. Сделать это можно, сконфигурировав свойство yii\web\AssetManager::$assetMap следующим образом:

Ключи assetMap — это имена ресурсов, которые вы хотите исправить, а значения — это требуемые пути для ресурсов. Когда регистрируется комплект ресурсов в представлении, каждый соответствующий файл ресурса в css или js массивах будет рассмотрен в соответствии с этой привязкой. И, если какой-либо из ключей найден, как последняя часть пути до файла ресурса (путь на который начинается с yii\web\AssetBundle::$sourcePath по возможности), то соответствующее значение заменит ресурс и будет зарегистрировано в представлении. Например, путь до файла ресурса my/path/to/jquery.js — это соответствует ключу jquery.js .

Примечание. Ресурсы заданные только с использованием относительного пути могут использоваться в привязке ресурсов. Пути ресурсов должны быть абсолютные адреса или путь относительно yii\web\AssetManager::$basePath .

Как уже было сказано выше, если комплект ресурсов располагается в директории которая не доступна из Web, эти ресурсы будут скопированы в Web директорию, когда комплект будет зарегистрирован в представлении. Этот процесс называется публикацией ресурсов, его автоматически выполняет менеджер ресурсов .

По умолчанию, ресурсы публикуются в директорию @webroot/assets которая соответствует URL @web/assets. Можно настроить это местоположение сконфигурировав свойства basePath и baseUrl .

Вместо публикации ресурсов путём копирования файлов, можно рассмотреть использование символических ссылок, если Ваша операционная система или веб-сервер это разрешают. Эта функция может быть включена путем установки linkAssets в true.

С конфигурацией, установленной выше, менеджер ресурсов будет создавать символические ссылки на исходные пути комплекта ресурсов когда он будет публиковаться. Это быстрее, чем копирование файлов, а также может гарантировать, что опубликованные ресурсы всегда up-to-date(обновлённые/свежие).

Для веб-приложения запущенного в режиме production, считается нормальной практикой разрешить HTTP кэширование для ресурсов и других статичных источников. Недостаток такой практики в том, что всякий раз, когда изменяется ресурс и разворачивается production, пользователь может по-прежнему использовать старую версию ресурса вследствие HTTP кэширования. Чтобы избежать этого, можно использовать возможность перебора кэша, которая была добавлена в версии 2.0.3, для этого можно настроить yii\web\AssetManager следующим образом:

Делая таким образом, к URL каждого опубликованного ресурса будет добавляться временная метка его последней модификации. Например, URL для yii.js может выглядеть как /assets/5515a87c/yii.js?v=1423448645". где параметр v представляет собой временную метку последней модификации файла yii.js. Теперь если изменить ресурс, его URL тоже будет изменен, это означает что клиент получит последнюю версию ресурса.

Код ядра Yii содержит большое количество комплектов ресурсов. Среди них, следующие комплекты широко используются и могут упоминаться в Вашем приложении или коде расширения:

• yii\web\YiiAsset. Включает основной yii.js файл который реализует механизм организации JavaScript кода в модулях. Также обеспечивает специальную поддержку для data-method и data-confirm атрибутов и содержит другие полезные функции.
• yii\web\JqueryAsset. Включает jquery.js файл из jQuery Bower пакета.
• yii\bootstrap\BootstrapAsset. Включает CSS файл из Twitter Bootstrap фреймворка.
• yii\bootstrap\BootstrapPluginAsset. Включает JavaScript файл из Twitter Bootstrap фреймворка для поддержки Bootstrap JavaScript плагинов.
• yii\jui\JuiAsset. Включает CSS и JavaScript файлы из jQuery UI библиотеки.

Если Ваш код зависит от jQuery, jQuery UI или Bootstrap, Вам необходимо использовать эти предопределенные комплекты ресурсов, а не создавать свои собственные варианты. Если параметры по умолчанию этих комплектов не удовлетворяют Вашим нуждам, вы можете настроить их как описано в подразделе Настройка комплектов ресурсов .

Вместо того, чтобы напрямую писать CSS и/или JavaScript код, разработчики часто пишут его в некотором расширенном синтаксисе и используют специальные инструменты конвертации в CSS/JavaScript. Например, для CSS кода можно использовать LESS или SCSS ; а для JavaScript можно использовать TypeScript .

Можно перечислить файлы ресурсов в расширенном синтаксисе в css и js свойствах из комплекта ресурсов. Например,

Когда вы регистрируете такой комплект ресурсов в представлении, менеджер ресурсов автоматически запустит нужные инструменты препроцессора и конвертирует ресурсы в CSS/JavaScript, если их расширенный синтаксис распознан. Когда представление окончательно отобразит страницу, в неё будут включены файлы CSS/JavaScript, вместо оригинальных ресурсов в расширенном синтаксисе.

Yii использует имена расширений файлов для идентификации расширенного синтаксиса внутри ресурса. По умолчанию признаны следующие синтаксисы и имена расширений файлов:

Yii ориентируется на установленные инструменты конвертации ресурсов препроцессора. Например, используя LESS. вы должны установить команду lessc препроцессора.

Вы можете настроить команды препроцессора и поддерживать расширенный синтаксис сконфигурировав yii\web\AssetManager::$converter следующим образом:

В примере выше, вы задали поддержку расширенного синтаксиса через yii\web\AssetConverter::$commands свойство. Ключи массива — это имена расширений файлов (без ведущей точки), а значения массива — это образующийся файл ресурса имён расширений и команд для выполнения конвертации ресурса. Маркеры и в командах будут заменены соответственно исходным путём файла ресурсов и путём назначения файла ресурсов.

Примечание. Существуют другие способы работы с ресурсами расширенного синтаксиса, кроме того, который указан выше. Например, вы можете использовать инструменты построения, такие как grunt для отслеживания и автоматической конвертации ресурсов расширенного синтаксиса. В этом случае, вы должны перечислить конечные CSS/JavaScript файлы в комплекте ресурсов вместо исходных файлов.

Web страница может включать много CSS и/или JavaScript файлов. Чтобы сократить количество HTTP запросов и общий размер загрузки этих файлов, общепринятой практикой является объединение и сжатие нескольких CSS/JavaScript файлов в один или в более меньшее количество, а затем включение этих сжатых файлов вместо исходных на веб-странице.

Примечание. Комбинирование и сжатие ресурсов обычно необходимо, когда приложение находится в режиме production. В режиме разработки, использование исходных CSS/JavaScript файлов часто более удобно для отладочных целей.

Далее, мы представим подход комбинирования и сжатия файлов ресурсов без необходимости изменения Вашего существующего кода приложения.

1. Найдите все комплекты ресурсов в Вашем приложении, которые вы планируете скомбинировать и сжать.
2. Распределите эти комплекты в одну или несколько групп. Обратите внимание, что каждый комплект может принадлежать только одной группе.
3. Скомбинируйте/сожмите CSS файлы каждой группы в один файл. Сделайте то же самое для JavaScript файлов.

Определите новый комплект ресурсов для каждой группы:

• Или установите css и js свойства. Соответствующие CSS и JavaScript файлы будут объединены.
• Или настройте комплекты ресурсов каждой группы, установив их css и js свойства как пустые, и установите их depends свойство как новый комплект ресурсов, созданный для группы.

Используя этот подход, при регистрации комплекта ресурсов в представлении, автоматически регистрируется новый комплект ресурсов для группы, к которому исходный комплект принадлежит. В результате скомбинированные/сжатые файлы ресурсов включаются в страницу вместо исходных.

Давайте рассмотрим пример, чтобы объяснить вышеуказанный подход.

Предположим, ваше приложение имеет две страницы, X и Y. Страница X использует комплект ресурсов A, B и C, в то время, как страница Y использует комплект ресурсов, B, C и D.

У Вас есть два пути, чтобы разделить эти комплекты ресурсов. Первый — использовать одну группу, включающую в себя все комплекты ресурсов. Другой путь — положить комплект А в группу Х, D в группу Y, а (B, C) в группу S. Какой из этих вариантов лучше? Это зависит. Первый способ имеет преимущество в том, что в обоих страницах одинаково скомбинированы файлы CSS и JavaScript, что делает HTTP кэширование более эффективным. С другой стороны, поскольку одна группа содержит все комплекты, размер скомбинированных CSS и JavaScript файлов будет больше, и таким образом увеличится время отдачи файла (загрузки страницы). Для простоты в этом примере, мы будем использовать первый способ, то есть использовать единую группу, содержащую все пакеты.

Примечание. Разделение комплекта ресурсов на группы это не тривиальная задача. Это, как правило, требует анализа реальных данных о трафике различных ресурсов на разных страницах. В начале вы можете начать с одной группы, для простоты.

Используйте существующие инструменты (например Closure Compiler. YUI Compressor ) для объединения и сжатия CSS и JavaScript файлов во всех комплектах. Обратите внимание, что файлы должны быть объединены в том порядке, который удовлетворяет зависимости между комплектами. Например, если комплект A зависит от В, который зависит от С и D, то вы должны перечислить файлы ресурсов начиная с С и D, затем B, и только после этого А.

После объединения и сжатия, вы получите один CSS файл и один JavaScript файл. Предположим, они названы как all-xyz.css и all-xyz.js. где xyz это временная метка или хэш, который используется, чтобы создать уникальное имя файла, чтобы избежать проблем с HTTP кэшированием.

Сейчас мы находимся на последнем шаге. Настройте менеджер ресурсов в конфигурации вашего приложения, как показано ниже:

Как объяснено в подразделе Настройка Комплектов Ресурсов, приведенная выше конфигурация изменяет поведение по умолчанию каждого комплекта. В частности, комплекты A, B, C и D не имеют больше никаких файлов ресурсов. Теперь они все зависят от all комплекта, который содержит скомбинированные all-xyz.css и all-xyz.js файлы. Следовательно, для страницы X, вместо включения исходных файлов ресурсов из комплектов A, B и C, только два этих объединённых файла будут включены, то же самое произойдёт и со страницей Y.

Есть еще один трюк, чтобы сделать работу вышеуказанного подхода более отлаженной. Вместо изменения конфигурационного файла приложения напрямую, можно поставить комплект массива настроек в отдельный файл, и условно включить этот файл в конфигурацию приложения. Например,

То есть, массив конфигурации комплекта ресурсов сохраняется в assets-prod.php для режима production, и в assets-dev.php для режима не production (разработки).

Yii предоставляет консольную команду с именем asset для автоматизации подхода, который мы только что описали.

Чтобы использовать эту команду, вы должны сначала создать файл конфигурации для описания того, как комплекты ресурсов должны быть скомбинированы, и как они должны быть сгруппированы. Затем вы можете использовать подкомманду asset/template, чтобы сгенерировать первый шаблон и затем отредактировать его под свои нужды.

Данная команда сгенерирует файл с именем assets.php в текущей директории. Содержание этого файла можно увидеть ниже:

Вы должны изменить этот файл и указать в bundles параметре, какие комплекты вы планируете объединить. В параметре targets вы должны указать, как комплекты должны быть поделены в группы. Вы можете указать одну или несколько групп, как уже было сказано выше.

Примечание. Так как псевдонимы путей @webroot и @web не могут быть использованы в консольном приложении, вы должны явно задать их в файле конфигурации.