Browse Source

Added detailed docs about assets setup (#232)

detailed docs about assets setup added
tags/2.0.8
Paul Klimov 7 years ago committed by GitHub
parent
commit
1e925752b5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
  1. 1
      docs/guide/README.md
  2. 187
      docs/guide/assets-setup.md

1
docs/guide/README.md

@ -14,6 +14,7 @@ Getting Started
---------------
* [Installation](installation.md)
* [Assets Setup](assets-setup.md)
* [Basic Usage](basic-usage.md)
Usage

187
docs/guide/assets-setup.md

@ -0,0 +1,187 @@
Assets Setup
============
This extensions relies on [Bower](http://bower.io/) and/or [NPM](https://www.npmjs.org/) packages for the asset installation.
Before using this package you should decide in which way you will install those packages in your project.
## Using asset-packagist repository
You can setup [asset-packagist.org](https://asset-packagist.org) as package source for the Bootstrap assets.
In the `composer.json` of your project, add the following lines:
```json
"repositories": [
{
"type": "composer",
"url": "https://asset-packagist.org"
}
]
```
Adjust `@npm` and `@bower` in you application configuration:
```php
return [
//...
'aliases' => [
'@bower' => '@vendor/bower-asset',
'@npm' => '@vendor/npm-asset',
],
//...
];
```
## Using composer asset plugin
Install [composer asset plugin](https://github.com/francoispluchino/composer-asset-plugin/) globally, using following command:
```
composer global require "fxp/composer-asset-plugin:^1.4.0"
```
Add the following lines to `composer.json` of your project to adjust directories where the installed packages
will be placed, if you want to publish them using Yii:
```json
"extra": {
"asset-installer-paths": {
"npm-asset-library": "vendor/npm",
"bower-asset-library": "vendor/bower"
}
}
```
Then you can run composer install/update command to pick up Bootstrap assets.
> Note: `fxp/composer-asset-plugin` significantly slows down the `composer update` command in comparison
to asset-packagist.
## Using Bower/NPM client directly
You can install Bootstrap assets directly via Bower or NPM client.
In the `package.json` of your project, add the following lines:
```json
{
...
"dependencies": {
"bootstrap": "3.3.5",
...
}
...
}
```
In the `composer.json` of your project, add the following lines in order to prevent redundant Bootstrap asset installation:
```json
"replace": {
"bower-asset/bootstrap": ">=3.3.0"
},
```
## Using CDN
You may use Bootstrap assets from [official CDN](https://www.bootstrapcdn.com).
In the `composer.json` of your project, add the following lines in order to prevent redundant Bootstrap asset installation:
```json
"replace": {
"bower-asset/bootstrap": ">=3.3.0"
},
```
Configure 'assetManager' application component, overriding Bootstrap assent bundles with CDN links:
```php
return [
'components' => [
'assetManager' => [
// override bundles to use CDN :
'bundles' => [
'yii\bootstrap\BootstrapAsset' => [
'sourcePath' => null,
'baseUrl' => 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7',
'css' => [
'css/bootstrap.min.css'
],
],
'yii\bootstrap\BootstrapPluginAsset' => [
'sourcePath' => null,
'baseUrl' => 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7',
'js' => [
'js/bootstrap.min.js'
],
],
'yii\bootstrap\BootstrapThemeAsset' => [
'sourcePath' => null,
'baseUrl' => 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7',
'css' => [
'css/bootstrap-theme.min.css'
]
],
],
],
// ...
],
// ...
];
```
## Compiling from the .less files
If you want to customize the Bootstrap CSS source directly, you may want to compile it from source *.less files.
In such case installing Bootstrap assets from Composer or Bower/NPM makes no sense, since you can not modify files
inside 'vendor' directory.
You'll have to downloaded Bootstrap assets manually and place them somewhere inside you project source code,
for example at 'assets/source/bootstrap' folder.
In the `composer.json` of your project, add the following lines in order to prevent redundant Bootstrap asset installation:
```json
"replace": {
"bower-asset/bootstrap": ">=3.3.0"
},
```
Configure 'assetManager' application component, overriding Bootstrap assent bundles and specifying compiler for CSS files:
```php
return [
'components' => [
'assetManager' => [
// setup asset converter for *.less files :
'converter' => [
'class' => 'yii\web\AssetConverter',
'commands' => [
'less' => ['css', 'lessc {from} {to} --no-color'],
],
],
// override bundles to use local project files :
'bundles' => [
'yii\bootstrap\BootstrapAsset' => [
'sourcePath' => '@app/assets/source/bootstrap',
'css' => [
'css/bootstrap.less'
],
],
'yii\bootstrap\BootstrapPluginAsset' => [
'sourcePath' => '@app/assets/source/bootstrap',
],
'yii\bootstrap\BootstrapThemeAsset' => [
'sourcePath' => '@app/assets/source/bootstrap',
],
],
],
// ...
],
// ...
];
```
Loading…
Cancel
Save