-
-
Notifications
You must be signed in to change notification settings - Fork 44
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
e0d7405
commit 58ee17f
Showing
9 changed files
with
470 additions
and
145 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,181 @@ | ||
| <p align="center"> | ||
| <a href="https://github.com/yiisoft" target="_blank"> | ||
| <img src="https://yiisoft.github.io/docs/images/yii_logo.svg" height="100px"> | ||
| </a> | ||
| <h1 align="center">Yii View Rendering Library</h1> | ||
| <br> | ||
| </p> | ||
|
|
||
| [](https://packagist.org/packages/yiisoft/view) | ||
| [](https://packagist.org/packages/yiisoft/view) | ||
| [](https://github.com/yiisoft/view/actions?query=workflow%3Abuild) | ||
| [](https://codecov.io/gh/yiisoft/view) | ||
| [](https://dashboard.stryker-mutator.io/reports/github.com/yiisoft/view/master) | ||
| [](https://github.com/yiisoft/view/actions?query=workflow%3A%22static+analysis%22) | ||
| [](https://shepherd.dev/github/yiisoft/view) | ||
|
|
||
| This library provides templates rendering abstraction supporting layout-view-subview hierarchy, custom renderers with | ||
| PHP-based as default, and more. It's used in [Yii Framework](https://www.yiiframework.com/) but is usable separately. | ||
|
|
||
| ## Requirements | ||
|
|
||
| - PHP 8.0 or higher. | ||
|
|
||
| ## Installation | ||
|
|
||
| The package could be installed with [Composer](https://getcomposer.org): | ||
|
|
||
| ```shell | ||
| composer require yiisoft/view | ||
| ``` | ||
|
|
||
| ## General usage | ||
|
|
||
| The package provides two use cases for managing view templates: | ||
|
|
||
| - [Basic functionality for use in any environment or Advanced functionality for use in a web environment](docs/guide/en/README.md) | ||
| - [Funcionalidade básica para uso em qualquer ambiente ou funcionalidade avançada para uso em ambiente web](docs/guide/pt-BR/README.md) | ||
|
|
||
| , [中国人](docs/guide/zh-CN/README.md), [Français](docs/guide/fr/README.md), [日本語](docs/guide/ja/README.md), [Português - Brasil](docs/guide/pt-BR/README.md), [Русский](docs/guide/ru/README.md), [Spanish](docs/guide/es/README.md) | ||
|
|
||
| - [Basic functionality](docs/basic-functionality.md) for use in any environment. | ||
| - Advanced functionality for [use in a web environment](docs/use-in-web-environment.md). | ||
|
|
||
| ### State of `View` and `WebView` services | ||
|
|
||
| While being immutable and, by itself, stateless, both `View` and `WebView` services have sets of stateful and mutable | ||
| data. | ||
|
|
||
| `View` service: | ||
| - parameters, | ||
| - blocks, | ||
| - theme, | ||
| - locale. | ||
|
|
||
| `WebView` service: | ||
| - parameters, | ||
| - blocks, | ||
| - theme, | ||
| - locale, | ||
| - title, | ||
| - meta and link tags, | ||
| - JS/CSS strings, | ||
| - JS/CSS files. | ||
|
|
||
| The state of `View` and `WebView` isn't cloned when the services are cloned. So when | ||
| using `with*()`, both new and old instances are sharing the same set of stateful mutable data. It allows, for example, | ||
| to get `WebView` via type-hinting in a controller and change context path: | ||
|
|
||
| ```php | ||
| final class BlogController { | ||
| private WebView $view; | ||
| public function __construct (WebView $view) { | ||
| $this->view = $view->withContextPath(__DIR__.'/views'); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| and then register CSS in a widget: | ||
|
|
||
| ```php | ||
| final class LastPosts extends Widget | ||
| { | ||
| private WebView $view; | ||
| public function __construct (WebView $view) { | ||
| $this->view = $view; | ||
| } | ||
| protected function run(): string | ||
| { | ||
| ... | ||
| $this->view->registerCss('.lastPosts { background: #f1f1f1; }'); | ||
| ... | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| #### Locale state | ||
|
|
||
| You can change the locale by using `setLocale()`, which will be applied to all other instances that used current state | ||
| including existing ones. If you need to change the locale only for a single instance, you can use the immutable | ||
| `withLocale()` method. Locale will be applied to all views rendered within views with `render()` calls. | ||
|
|
||
| Example with mutable method: | ||
|
|
||
| ```php | ||
| final class LocaleMiddleware implements MiddlewareInterface | ||
| { | ||
| ... | ||
| private WebView $view; | ||
| ... | ||
| public function __construct ( | ||
| ... | ||
| WebView $view | ||
| ... | ||
| ) { | ||
| $this->view = $view; | ||
| } | ||
| public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface | ||
| { | ||
| ... | ||
| $this->view->setLocale($locale); | ||
| ... | ||
| } | ||
| } | ||
| ```` | ||
|
|
||
| Example with immutable method: | ||
|
|
||
| ```php | ||
| final class BlogController { | ||
| private WebView $view; | ||
| public function __construct (WebView $view) { | ||
| $this->view = $view; | ||
| } | ||
| public function index() { | ||
| return $this->view->withLocale('es')->render('index'); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| #### Reset state | ||
|
|
||
| To get a deep cloned `View` or `WebView` use `withClearedState()`: | ||
|
|
||
| ```php | ||
| $view = $view->withClearedState(); | ||
| ``` | ||
|
|
||
| ## Extensions | ||
|
|
||
| - [yiisoft/yii-view](https://github.com/yiisoft/yii-view) - a wrapper that's used in | ||
| [Yii Framework]((https://www.yiiframework.com/)). | ||
| Adds extra functionality for a web environment and compatibility | ||
| with [PSR-7](https://www.php-fig.org/psr/psr-7) interfaces. | ||
| - [yiisoft/view-twig](https://github.com/yiisoft/view-twig) - an extension that provides a view renderer that will | ||
| allow you to use the [Twig](https://twig.symfony.com) view template engine, instead of the default PHP renderer. | ||
|
|
||
| ## Documentation | ||
|
|
||
| - [Internals](docs/internals.md) | ||
|
|
||
| If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that. | ||
| You may also check out other [Yii Community Resources](https://www.yiiframework.com/community). | ||
|
|
||
| ## License | ||
|
|
||
| The Yii View Rendering Library is free software. It's released under the terms of the BSD License. | ||
| Please see [`LICENSE`](./LICENSE.md) for more information. | ||
|
|
||
| Maintained by [Yii Software](https://www.yiiframework.com/). | ||
|
|
||
| ### Support the project | ||
|
|
||
| [](https://opencollective.com/yiisoft) | ||
|
|
||
| ### Follow updates | ||
|
|
||
| [](https://www.yiiframework.com/) | ||
| [](https://twitter.com/yiiframework) | ||
| [](https://t.me/yii3en) | ||
| [](https://www.facebook.com/groups/yiitalk) | ||
| [](https://yiiframework.com/go/slack) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.