output-theming.md 3.46 KB
Newer Older
1 2 3
Theming
=======

4
> Note: This section is under development.
Qiang Xue committed
5

6
A theme is a directory of view and layout files. Each file of the theme overrides corresponding file of an application
7
when rendered. A single application may use multiple themes and each may provide totally different experiences. At any
8 9
time only one theme can be active.

10 11
> Note: Themes are usually not meant to be redistributed since views are too application specific. If you want to
  redistribute a customized look and feel, consider CSS and JavaScript files in the form of [asset bundles](structure-assets.md) instead.
12

13 14
Configuring a theme
-------------------
15

16 17
Theme configuration is specified via the `view` component of the application. In order to set up a theme to work with basic
application views, the following should be in your application config file:
18 19 20

```php
'components' => [
21 22
    'view' => [
        'theme' => [
23
            'pathMap' => ['@app/views' => '@app/themes/basic'],
24 25 26
            'baseUrl' => '@web/themes/basic',
        ],
    ],
27
],
28 29
```

30 31
In the above, `pathMap` defines a map of original paths to themed paths while `baseUrl` defines the base URL for
resources referenced by theme files.
32 33 34 35 36 37 38 39 40

In our case `pathMap` is `['@app/views' => '@app/themes/basic']`. That means that every view in `@app/views` will be
first searched under `@app/themes/basic` and if a view exists in the theme directory it will be used instead of the
original view.

For example, with a configuration above a themed version of a view file `@app/views/site/index.php` will be
`@app/themes/basic/site/index.php`. It basically replaces `@app/views` in `@app/views/site/index.php` with
`@app/themes/basic`.

41 42 43 44 45 46 47 48 49 50 51
In order to configure theme runtime you can use the following code before rendering a view. Typically it will be
placed in controller:

```php
$this->getView()->theme = Yii::createObject([
    'class' => '\yii\base\Theme',
    'pathMap' => ['@app/views' => '@app/themes/basic'],
    'baseUrl' => '@web/themes/basic',
]);
```

52 53
### Theming modules

54
In order to theme modules, `pathMap` may look like the following:
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69

```php
'components' => [
    'view' => [
        'theme' => [
            'pathMap' => [
                '@app/views' => '@app/themes/basic',
                '@app/modules' => '@app/themes/basic/modules', // <-- !!!
            ],
        ],
    ],
],
```

It will allow you to theme `@app/modules/blog/views/comment/index.php` with `@app/themes/basic/modules/blog/views/comment/index.php`.
70

71 72
### Theming widgets

73 74
In order to theme a widget view located at `@app/widgets/currency/views/index.php`, you need the following configuration for
the view component theme:
75 76 77 78 79

```php
'components' => [
    'view' => [
        'theme' => [
80
            'pathMap' => ['@app/widgets' => '@app/themes/basic/widgets'],
81 82 83 84 85
        ],
    ],
],
```

86
With the configuration above you can create a themed version of the `@app/widgets/currency/index.php` view in
87
`@app/themes/basic/widgets/currency/index.php`.
88

89 90 91
Using multiple paths
--------------------

92
It is possible to map a single path to multiple theme paths. For example,
93 94 95

```php
'pathMap' => [
96 97 98
    '@app/views' => [
        '@app/themes/christmas',
        '@app/themes/basic',
99
    ],
100 101 102
]
```

103 104
In this case, first the view will be searched for in `@app/themes/christmas/site/index.php` then if it's not found it will check
`@app/themes/basic/site/index.php`. If there's no view there as well, then the application view will be used.
105

106
This ability is especially useful if you want to temporarily or conditionally override some views.