diff --git a/docs/guide/apps-advanced.md b/docs/guide/apps-advanced.md index 728a862..25d9202 100644 --- a/docs/guide/apps-advanced.md +++ b/docs/guide/apps-advanced.md @@ -5,6 +5,42 @@ This template is for large projects developed in teams where backend is divided to multiple servers etc. This application template also goes a bit further regarding features and provides essential database, signup and password restore out of the box. +Installation +------------ + +### Install via Composer + +If you do not have [Composer](http://getcomposer.org/), you may download it from +[http://getcomposer.org/](http://getcomposer.org/) or run the following command on Linux/Unix/MacOS: + +~~~ +curl -s http://getcomposer.org/installer | php +~~~ + +You can then install the application using the following command: + +~~~ +php composer.phar create-project --stability=dev yiisoft/yii2-app-advanced /path/to/yii-application +~~~ + +Getting started +--------------- + +After you install the application, you have to conduct the following steps to initialize +the installed application. You only need to do these once for all. + +1. Execute the `init` command and select `dev` as environment. +--- +php /path/to/yii-application/init +--- +2. Create a new database. It is assumed that MySQL InnoDB is used. If not, adjust `console/migrations/m130524_201442_init.php`. +3. In `common/config/params.php` set your database details in `components.db` values. + +4. Set document roots of your Web server: + +- for frontend `/path/to/yii-application/frontend/web/` and using the URL `http://frontend/` +- for backend `/path/to/yii-application/backend/web/` and using the URL `http://backend/` + Directory structure ------------------- diff --git a/docs/guide/apps-basic.md b/docs/guide/apps-basic.md index 696219a..b8440a2 100644 --- a/docs/guide/apps-basic.md +++ b/docs/guide/apps-basic.md @@ -7,6 +7,24 @@ The application has four pages: the homepage, the about page, the contact page a The contact page displays a contact form that users can fill in to submit their inquiries to the webmaster, and the login page allows users to be authenticated before accessing privileged contents. +Installation +------------ + +If you do not have [Composer](http://getcomposer.org/), you may download it from +[http://getcomposer.org/](http://getcomposer.org/) or run the following command on Linux/Unix/MacOS: + +~~~ +curl -s http://getcomposer.org/installer | php +~~~ + +You can then install the Bootstrap Application using the following command: + +~~~ +php composer.phar create-project --stability=dev yiisoft/yii2-app-basic /path/to/yii-application +~~~ + +Now set document root directory of your Web server to /path/to/yii-application/web and you should be able to access the application using the URL `http://localhost/`. + Directory structure ------------------- @@ -139,4 +157,4 @@ For example, to use markdown helper you need to add `michelf/php-markdown`. All [packagist.org](https://packagist.org/) so feel free to browse the website for useful code. After your `composer.json` is changed you can run `php composer.phar update`, wait till packages are downloaded and -installed and then just use them. Autoloading of classes will be handled automatically. \ No newline at end of file +installed and then just use them. Autoloading of classes will be handled automatically. diff --git a/docs/guide/bootstrap-widgets.md b/docs/guide/bootstrap-widgets.md index 006c70e..acf580a 100644 --- a/docs/guide/bootstrap-widgets.md +++ b/docs/guide/bootstrap-widgets.md @@ -1,6 +1,60 @@ -Twitter Bootstrap widgets -========================= +Bootstrap widgets +================= -Overview --------- +Yii includes support of [Bootstrap 3](http://getbootstrap.com/) markup and components framework out of the box. It is an +excellent framework that allows you to speed up development a lot. +Bootstrap is generally about two parts: + +- Basics such as grid system, typography, helper classes and responsive utilities. +- Ready to use components such as menus, pagination, modal boxes, tabs etc. + +Basics +------ + +Yii doesn't wrap bootstrap basics into PHP code since HTML is very simple by itself in this case. You can find details +about using the basics at [bootstrap documentation website](http://getbootstrap.com/css/). Still Yii provides a +convenient way to include bootstrap assets in your pages with a single line added to `AppAsset.php` located in your +`config` directory: + +```php +public $depends = array( + 'yii\web\YiiAsset', + 'yii\bootstrap\BootstrapAsset', // this line +); +``` + +Using bootstrap through Yii asset manager allows you to combine and minimize its resources with your own ones when +needed. + +Yii widgets +----------- + +Most complex bootstrap components are wrapped into Yii widgets to allow more robust syntax and integrate with +framework features. All widgets belong to `\yii\bootstrap` namespace. Let's review these. + +### Alert + +### Button + +### ButtonDropdown + +### ButtonGroup + +### Carousel + +### Collapse + +### Dropdown + +### Modal + +### Nav + +### NavBar + +### Progress + +### Tabs + +### Typeahead diff --git a/docs/guide/caching.md b/docs/guide/caching.md index bc36331..422441c 100644 --- a/docs/guide/caching.md +++ b/docs/guide/caching.md @@ -119,7 +119,7 @@ public function getCachedData() $value = Yii::$app->getCache()->get($key); if ($value === false) { $value = /* regenerate value because it is not found in cache and then save it in cache for later use */; - Yii::$app->cache->set($id, $value); + Yii::$app->cache->set($key, $value); } return $value; } diff --git a/docs/guide/installation.md b/docs/guide/installation.md index c7b7cee..16a496c 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -117,7 +117,10 @@ server { set $fsn $fastcgi_script_name; } + #for php-cgi fastcgi_pass 127.0.0.1:9000; + #for php-fpm + #fastcgi_pass unix:/var/run/php5-fpm.sock; include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fsn; diff --git a/docs/guide/model.md b/docs/guide/model.md index f4c540a..fec7ac3 100644 --- a/docs/guide/model.md +++ b/docs/guide/model.md @@ -143,6 +143,9 @@ class EmployeeController extends \yii\web\Controller } ``` +In the example above we are using [Active Record](active-record.md). For basic form models it's rarely needed to +use scenarios since form model is typically used for a single form. + Validation ---------- diff --git a/docs/guide/overview.md b/docs/guide/overview.md index c7eeb42..1cb6612 100644 --- a/docs/guide/overview.md +++ b/docs/guide/overview.md @@ -5,7 +5,7 @@ Yii is a high-performance, component-based PHP framework for developing large-scale Web applications rapidly. It enables maximum reusability in Web programming and can significantly accelerate your Web application development process. The name Yii (pronounced `Yee` or `[ji:]`) is an acronym for -"**Yes It Is!**". +**Yes It Is!**. Requirements diff --git a/docs/guide/view.md b/docs/guide/view.md index e69de29..811046d 100644 --- a/docs/guide/view.md +++ b/docs/guide/view.md @@ -0,0 +1,95 @@ +View +==== + +View is an important part of MVC and is reponsible for how data is presented to the end user. + +Basics +------ + +Yii uses PHP in view templates by default so in a web application a view typically contains some HTML, `echo`, `foreach` +and such basic constructs. It may also contain widget calls. Using complex code in views is considered a bad practice. +Such code should be moved to controller or widgets. + +View is typically called from controller action like the following: + +```php +public function actionIndex() +{ + return $this->render('index', array( + 'username' => 'samdark', + )); +} +``` + +First argument is the view name. In context of the controller Yii will search for its views in `views/site/` where `site` +is controller ID. For details on how view name is resolved please refer to [yii\base\Controller::render] method. +Second argument is data array that contains key-value pairs. Value is available in the view as a variable named the same +as the corresponding key. + +So the view for the action above should be in `views/site/index.php` and can be something like: + +```php +

Hello, !

+``` + +Intead of just scalar values you can pass anything else such as arrays or objects. + +Layout +------ + +Partials +-------- + + +Widgets +------- + +Security +-------- + +One of the main security principles is to always escape output. If violated it leads to script execution and, +most probably, to cross-site scripting known as XSS leading to leaking of admin passwords, making a user to automatically +perform actions etc. + +Yii provides a good toolset in order help you escaping your output. The very basic thing to escape is a text without any +markup. You can deal with it like the following: + +```php + + +
+ name); ?> +
+``` + +When you want to render HTML it becomes complex so we're delegating the task to excellent +[HTMLPurifier](http://htmlpurifier.org/) library. In order to use it you need to modify your `composer.json` first by +adding the following to `require`: + +```javascript +"ezyang/htmlpurifier": "v4.5.0" +``` + +After it's done run `php composer.phar install` and wait till package is downloaded. Now everything is prepared to use +Yii's HtmlPurifier helper: + +```php + + +
+ text); ?> +
+``` + +Note that besides HTMLPurifier does excellent job making output safe it's not very fast so consider +[caching result](caching.md). + +Alternative template languages +------------------------------ + +There are offlicial extensions for [Smarty](http://www.smarty.net/) and [Twig](http://twig.sensiolabs.org/). In order +to learn more refer to [Using template engines](template.md) section of the guide. diff --git a/extensions/composer/README.md b/extensions/composer/README.md index 871d1e3..986fc6c 100644 --- a/extensions/composer/README.md +++ b/extensions/composer/README.md @@ -1,5 +1,5 @@ Yii 2.0 Public Preview - Composer Installer -====================== +=========================================== Thank you for choosing Yii - a high-performance component-based PHP framework. @@ -13,33 +13,32 @@ without prior notices. **Yii 2.0 is not ready for production use yet.** This is the yii2 composer installer. + Installation ----------------- +------------ This extension offers you enhanced composer handling for your yii2-project. It will therefor require you to use composer. ` -php composer.phar require yiisoft/yii2-composer * +php composer.phar require yiisoft/yii2-composer "*" ` *Note: You might have to run `php composer.phar selfupdate` before using this extension.* Usage & Documentation ------------ +--------------------- + This extensions allows you to hook to certain composer events and prepare your yii2-app for usage. After the package is installed, the composer.json file has to be modified to enable this extension. To see it in action take a look at the example apps in the repository: -[Basic](https://github.com/suralc/yii2/blob/master/apps/basic/composer.json#L27) -[Advanced](https://github.com/suralc/yii2/blob/extensions-readme/apps/advanced/composer.json) - -However it might be useful to read through the official composer [documentation](http://getcomposer.org/doc/articles/scripts.md) to understand what this extension can to for you and what it can't. - -You can also use this as an template to create your own composer additions to ease development and deployment of your app. - - +- [Basic](https://github.com/suralc/yii2/blob/master/apps/basic/composer.json#L27) +- [Advanced](https://github.com/suralc/yii2/blob/extensions-readme/apps/advanced/composer.json) +However it might be useful to read through the official composer [documentation](http://getcomposer.org/doc/articles/scripts.md) +to understand what this extension can do for you and what it can't. +You can also use this as a template to create your own composer additions to ease development and deployment of your app. diff --git a/extensions/jui/README.md b/extensions/jui/README.md index 6025ac4..0403acb 100644 --- a/extensions/jui/README.md +++ b/extensions/jui/README.md @@ -1,5 +1,5 @@ Yii 2.0 Public Preview - JUI Extension -====================== +====================================== Thank you for choosing Yii - a high-performance component-based PHP framework. @@ -13,13 +13,15 @@ without prior notices. **Yii 2.0 is not ready for production use yet.** This is the yii2-jui extension. + Installation ----------------- +------------ + The preferred way to install this extension is [composer](http://getcomposer.org/download/). Either run ``` -php composer.phar require yiisoft/yii2-jui* +php composer.phar require yiisoft/yii2-jui "*" ``` or add @@ -33,23 +35,21 @@ to the require section of your composer.json. Usage & Documentation ------------ +--------------------- This extension provides multiple widgets to work with jquery.ui, as well as a set of compatible jquery.ui files. You can use these widgets in your view files after you have registered the corresponding assets. Example: ------------ + ```php echo ProgressBar::widget(array( 'clientOptions' => array( 'value' => 75, ), )); +``` -For further instructions refer to the guide (once it is finished) - - - +For further instructions refer to the yii guide. diff --git a/extensions/mutex/README.md b/extensions/mutex/README.md index e3a697d..161ee8a 100644 --- a/extensions/mutex/README.md +++ b/extensions/mutex/README.md @@ -1,5 +1,5 @@ Yii 2.0 Public Preview - Mutex Extension -====================== +======================================== Thank you for choosing Yii - a high-performance component-based PHP framework. @@ -13,13 +13,15 @@ without prior notices. **Yii 2.0 is not ready for production use yet.** This is the yii2-mutex extension. + Installation ----------------- +------------ + The prefered way to install this extension is through [composer](http://getcomposer.org/download/). Either run ``` -php composer.phar require yiisoft/yii2-mutex * +php composer.phar require yiisoft/yii2-mutex "*" ``` or add @@ -33,12 +35,8 @@ to the require section of your composer.json. Usage & Documentation ------------ +--------------------- This component can be used to perform actions similar to the concept of [mutual exclusion](http://en.wikipedia.org/wiki/Mutual_exclusion). -For concrete examples and advanced usage refer to the guide. - - - - +For concrete examples and advanced usage refer to the yii guide. diff --git a/extensions/smarty/README.md b/extensions/smarty/README.md index c40226c..adf764f 100644 --- a/extensions/smarty/README.md +++ b/extensions/smarty/README.md @@ -1,5 +1,5 @@ Yii 2.0 Public Preview - Smarty View Renderer -====================== +============================================= Thank you for choosing Yii - a high-performance component-based PHP framework. @@ -13,13 +13,15 @@ without prior notices. **Yii 2.0 is not ready for production use yet.** This is the yii2-smarty extension. + Installation ----------------- +------------ + The prefered way to install this extension is through [composer](http://getcomposer.org/download/). Either run ``` -php composer.phar require yiisoft/yii2-smarty * +php composer.phar require yiisoft/yii2-smarty "*" ``` or add @@ -33,12 +35,13 @@ to the require section of your composer.json. Usage & Documentation ------------ +--------------------- This extension has to be registered prior to usage. To enable this view renderer add it to the $rendereres property of your view object. -Example: +Example: + ```php getTimestamp(); } else { diff --git a/framework/yii/bootstrap/Dropdown.php b/framework/yii/bootstrap/Dropdown.php index 0568fe4..c8c1b7d 100644 --- a/framework/yii/bootstrap/Dropdown.php +++ b/framework/yii/bootstrap/Dropdown.php @@ -21,8 +21,9 @@ use yii\helpers\Html; class Dropdown extends Widget { /** - * @var array list of menu items in the dropdown. Each array element represents a single - * menu with the following structure: + * @var array list of menu items in the dropdown. Each array element can be either an HTML string, + * or an array representing a single menu with the following structure: + * * - label: string, required, the label of the item link * - url: string, optional, the url of the item link. Defaults to "#". * - linkOptions: array, optional, the HTML attributes of the item link. diff --git a/framework/yii/helpers/HtmlBase.php b/framework/yii/helpers/HtmlBase.php index d6ee2b5..1e9a6a7 100644 --- a/framework/yii/helpers/HtmlBase.php +++ b/framework/yii/helpers/HtmlBase.php @@ -935,6 +935,30 @@ class HtmlBase } /** + * Generates a tag that contains the first validation error of the specified model attribute. + * Note that even if there is no validation error, this method will still return an empty error tag. + * @param Model $model the model object + * @param string $attribute the attribute name or expression. See [[getAttributeName()]] for the format + * about attribute expression. + * @param array $options the tag options in terms of name-value pairs. The values will be HTML-encoded + * using [[encode()]]. If a value is null, the corresponding attribute will not be rendered. + * + * The following options are specially handled: + * + * - tag: this specifies the tag name. If not set, "p" will be used. + * + * @return string the generated label tag + */ + public static function error($model, $attribute, $options = array()) + { + $attribute = static::getAttributeName($attribute); + $error = $model->getFirstError($attribute); + $tag = isset($options['tag']) ? $options['tag'] : 'p'; + unset($options['tag']); + return Html::tag($tag, Html::encode($error), $options); + } + + /** * Generates an input tag for the given model attribute. * This method will generate the "name" and "value" tag attributes automatically for the model attribute * unless they are explicitly specified in `$options`. diff --git a/framework/yii/widgets/ActiveField.php b/framework/yii/widgets/ActiveField.php index 747d97d..f42e611 100644 --- a/framework/yii/widgets/ActiveField.php +++ b/framework/yii/widgets/ActiveField.php @@ -146,7 +146,6 @@ class ActiveField extends Component protected function getClientOptions() { $enableClientValidation = $this->enableClientValidation || $this->enableClientValidation === null && $this->form->enableClientValidation; - $enableAjaxValidation = $this->enableAjaxValidation || $this->enableAjaxValidation === null && $this->form->enableAjaxValidation; if ($enableClientValidation) { $attribute = Html::getAttributeName($this->attribute); $validators = array(); @@ -162,6 +161,7 @@ class ActiveField extends Component } } + $enableAjaxValidation = $this->enableAjaxValidation || $this->enableAjaxValidation === null && $this->form->enableAjaxValidation; if ($enableAjaxValidation) { $options['enableAjaxValidation'] = 1; } @@ -169,12 +169,7 @@ class ActiveField extends Component if ($enableClientValidation && !empty($options['validate']) || $enableAjaxValidation) { $inputID = Html::getInputId($this->model, $this->attribute); $options['name'] = $inputID; - $names = array( - 'validateOnChange', - 'validateOnType', - 'validationDelay', - ); - foreach ($names as $name) { + foreach (array('validateOnChange', 'validateOnType', 'validationDelay') as $name) { $options[$name] = $this->$name === null ? $this->form->$name : $this->$name; } $options['container'] = isset($this->selectors['container']) ? $this->selectors['container'] : ".field-$inputID"; @@ -216,22 +211,18 @@ class ActiveField extends Component * Note that even if there is no validation error, this method will still return an empty error tag. * @param array $options the tag options in terms of name-value pairs. It will be merged with [[errorOptions]]. * The options will be rendered as the attributes of the resulting tag. The values will be HTML-encoded - * using [[encode()]]. If a value is null, the corresponding attribute will not be rendered. + * using [[Html::encode()]]. If a value is null, the corresponding attribute will not be rendered. * * The following options are specially handled: * - * - tag: this specifies the tag name. If not set, "span" will be used. + * - tag: this specifies the tag name. If not set, "p" will be used. * * @return string the generated label tag */ public function error($options = array()) { $options = array_merge($this->errorOptions, $options); - $attribute = Html::getAttributeName($this->attribute); - $error = $this->model->getFirstError($attribute); - $tag = isset($options['tag']) ? $options['tag'] : 'span'; - unset($options['tag']); - return Html::tag($tag, Html::encode($error), $options); + return Html::error($this->model, $this->attribute, $options); } /**