# The Icing on the CakePHP

## Installation

### Install CakePHP

You can install CakePHP and connect it to the database. Clear all warnings generated on the CakePHP welcome page before proceeding.

```
composer create-project --prefer-dist cakephp/app FOLDER_NAME ~5.0
```

Pull up the CakePHP dev landing page and make sure that all warnings have been dealt with before proceeding. (Database config, URL rewrting etc.)

### Install Icing

Open the composer.json file and add the private repository:

```json
"repositories": [
{
"type": "vcs",
"url": "https://whetham-solutions@bitbucket.org/whetham-solutions/icing.git"
}
]
```

You will need to change to your own username.

Then you can install the plugin:

```
composer require whetham-solutions/icing ~5.0
```

And load the plugin (we're calling cake's plugin load method, then icing's load method):

```
bin\cake plugin load Icing
bin\cake load_icing
```
You should just get a bunch of success messages. Otherwise, review the errors to implement what the automatic installation is supposed to.

## Baking

When baking, make sure to use the Icing Theme:

```
bin\cake bake ...  --theme=Icing
```

If using `bake all --everything` which bakes all of the models controllers and templates for all tables, be sure to remove everything created from the icing
tables. For example, the table for Icing.Users is named ws_icing_users and this will create an MVC for WsIcingUsers.
Everything from Icing is prefixed with WsIcing so it should be easy to remove.

Alternatively, you can bake all each table one at a time, which may be preferrable anyways depending on the number of tables.

## OVERIDES

### TEMPLATES

Overriding an Icing template is standard:
https://book.cakephp.org/4/en/plugins.html#overriding-plugin-templates-from-inside-your-application

In summary, make a file with the path the Icing template starting from:
```/templates/plugin/Icing/SAME_PATH_FROM_ICING_TEMPLATES_FOLDER```

For example, the template for the users index will be searched for in order at these locations:

```
app/src/templates/plugin/Icing/Users/index.php
app/vendor/whetham-solutions/Icing/templates/Users/index.php
```

### CONTROLLERS

You can override Icing controllers by extending them with the same name as the Icing controller within the `APP/src/Controller` folder.

For example:

```php
namespace App\Controller

class UsersController extends \Icing\Controller\UsersController {

    public function index() {
        parent::index(); // optionally do whatever the parent does, or remove this to take full control
        $this->set('users', $this->Users->find('Admin')); //override the users view var
    }

}
```

Overridden controllers are automatically detected an used instead if present.

### MODELS

You can override Icing tables by placing the override class in the `APP/src/Model/Table/Icing` folder with the same name of the Icing table.

```php
namespace App\Model\Table\Icing;

class UsersTable extends \Icing\Model\Table\UsersTable {
   ...
}
```

You can override Icing entities similarly by placing the override class in the `APP/src/Model/Entity/Icing` folder with the same name of the Icing entity.

```php
namespace App\Model\Entity\Icing;

class User extends \Icing\Model\Entity\User {
   ...
}
```

Overridden tables and/or entities are automatically detected and used instead if present.

## Theme

### Layout

You can copy the entire `icing/templates/element/theme` folder into your `app/templates/plugin/Icing` folder and modify any of the content. <br>
**WARNING**: Copying the entire folder, rather than each file individulally means that future updates will not be applied.

### Navigation

Icing will look for the first nav template in order from the following locations:

```
app/templates/plugin/icing/element/nav/USER_GROUP_NAME.php
app/templates/plugin/icing/element/nav/default.php
app/vendor/zinnin8r/icing/templates/element/nav/USER_GROUP_NAME.php
app/vendor/zinnin8r/icing/templates/element/nav/default.php
```

`USER_GROUP_NAME` is the underscored name of the current logged in user group. <br>
For example: `Senior Manager --> ../senior_manager.php`

This allows for multiple nav menus based on the user group name of the logged in user.

You can use the NavHelper to render the nav menu. When you copy `icing/templates/element/nav/default.php` you can see how that works.
