From 88339b0cf62d2ae8657acb14b7da68cd24720304 Mon Sep 17 00:00:00 2001 From: Alexander Makarov Date: Tue, 13 Aug 2013 17:25:02 +0400 Subject: [PATCH] basic application usage guide --- docs/guide/apps-basic.md | 138 ++++++++++++++++++++++++++++++++++++++++++++++- docs/guide/index.md | 1 + 2 files changed, 138 insertions(+), 1 deletion(-) diff --git a/docs/guide/apps-basic.md b/docs/guide/apps-basic.md index 98dc4f0..d55f16c 100644 --- a/docs/guide/apps-basic.md +++ b/docs/guide/apps-basic.md @@ -1,6 +1,142 @@ Basic application template ========================== +This template is a perfect fit for small projects or learning Yii2. + The application has four pages: the homepage, the about page, the contact page and the login page. 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. \ No newline at end of file +and the login page allows users to be authenticated before accessing privileged contents. + +Directory structure +------------------- + +The basic application does not divide application directories much. Here's the basic structure: + +- `commands` - console controllers. +- `config` - configuration. +- `controllers` - web controllers. +- `models` - application models. +- `runtime` - logs, states, file cache. +- `views` - view templates. +- `web` - webroot. + +Root directory contains a set of files. + +- `.gitignore` contains a list of directories ignored by git version system. If you need something never get to your source +code repository, add it there. +- `codeception.yml` - Codeception config. +- `composer.json` - Composer config described in detail below. +- `LICENSE.md` - license info. Put your project license there. Especially when opensourcing. +- `README.md` - basic info about installing template. Consider replacing it with information about your project and its + installation. +- `requirements.php` - Yii requirements checker. Don't forget to delete it when deployed to the server. +- `yii` - console application bootstrap. +- `yii.bat` - console application bootstrap for Windows. + + +### config + +This directory contains configuration files: + +- `AppAsset.php` - definition of application assets such as CSS, JavaScript etc. Check [Managing assets](assets.md) for + details. +- `console.php` - console application configuration. +- `params.php` - common application parameters. +- `web.php` - web application configuration. +- `web-test.php` - web application configuration used when running functional tests. + +All these files except `AppAsset.php` are returning arrays used to configure corresponding application properties. Check +[Configuration](configuration.md) guide section for details. + +### views + +Views directory contains templates your application is using. In the basic template there are: + +``` +layouts + main.php +site + about.php + contact.php + error.php + index.php + login.php +``` + +`layouts` contains HTML layouts i.e. page markup except content: doctype, head section, main menu, footer etc. +The rest are typically controller views. By convention these are located in subdirectories matching controller id. For +`SiteController` views are under `site`. Names of the views themselves are typically match controller action names. +Partials are often named starting with underscore. + +### web + +Directory is a webroot. Typically a webserver is pointed into it. + +``` +assets +css +index.php +index-test.php +``` + +`assets` contains published asset files such as CSS, JavaScript etc. Publishing process is automatic so you don't need +to do anything with this directory other than making sure Yii has enough permissions to write to it. + +`css` contains plain CSS files and is useful for global CSS that isn't going to be compressed or merged by assets manager. + +`index.php` is the main web application bootstrap and is the central entry point for it. `index-test.php` is the entry +point for functional testing. + +Configuring Composer +-------------------- + +After application template is installed it's a good idea to adjust defaul `composer.json` that can be found in the root +directory: + +```javascript +{ + "name": "yiisoft/yii2-app-basic", + "description": "Yii 2 Basic Application Template", + "keywords": ["yii", "framework", "basic", "application template"], + "homepage": "http://www.yiiframework.com/", + "type": "project", + "license": "BSD-3-Clause", + "support": { + "issues": "https://github.com/yiisoft/yii2/issues?state=open", + "forum": "http://www.yiiframework.com/forum/", + "wiki": "http://www.yiiframework.com/wiki/", + "irc": "irc://irc.freenode.net/yii", + "source": "https://github.com/yiisoft/yii2" + }, + "minimum-stability": "dev", + "require": { + "php": ">=5.3.0", + "yiisoft/yii2": "dev-master", + "yiisoft/yii2-composer": "dev-master" + }, + "scripts": { + "post-create-project-cmd": [ + "yii\\composer\\InstallHandler::setPermissions" + ] + }, + "extra": { + "yii-install-writable": [ + "runtime", + "web/assets" + ], + "yii-install-executable": [ + "yii" + ] + } +} +``` + +First we're updating basic information. Change `name`, `description`, `keywords`, `homepage` and `support` to match +your project. + +Now the interesting part. You can add more packages your application needs to `require` section. +For example, to use markdown helper you need to add `michelf/php-markdown`. All these packages are coming from +[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 diff --git a/docs/guide/index.md b/docs/guide/index.md index 7675a8a..df16890 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -75,5 +75,6 @@ More - [Theming](theming.md) - [Console Application](console.md) - [Performance Tuning](performance.md) +- [Managing assets](assets.md) - [Testing](testing.md) - [Upgrading from 1.1 to 2.0](upgrade-from-v1.md)