# Module

## Definition

A module can be a simple CRUD tool for managing data in a database, or an advanced tool for performing complex tasks, such as a Workflow Manager for example.

Uccello helps you to manage data from a database without programming. When you create a new module all the `views`, `routes` and `controllers` are automatically available and the UI is scaffolded by itself. 

It is possible to **activate** or **deactivate** a module in some domains.

## Examples

### Classic module

```php
<?php

use Uccello\Core\Models\Module;

Module::create([
    'name' => 'person',
    'icon' => 'person',
    'model_class' => 'App\Person',
    'data' => null
]);
```

This module named `person` allows to manage people from the database.\
This name will be translated according to the module's [translation file](https://uccello.gitbook.io/doc/the-basics/translations).\
It is represented by the [material icon](https://material.io/resources/icons/?search=person\&icon=person\&style=baseline) called `person`.\
It is linked to the `App\Person` model and can access automatically to the related database table.

### Admin module

```php
<?php

use Uccello\Core\Models\Module;

Module::create([
    'name' => 'country',
    'icon' => 'terrain',
    'model_class' => 'Uccello\Address\Models\Country',
    'data' => [ "package" => "uccello/address", "admin" => true ];
]);
```

This is the code of the module called `country` , available in the [uccello/address](https://packagist.org/packages/uccello/address) package.\
As this module is part of an external package we must specify the name of the package. We can do this with `"package" => "uccello/address"`. \
In the same way, we link it to the `Uccello\Address\Models\Country`, also available in this package.\
As we use `"admin" => true`, this module is only visible in the Settings Panel by user who can administrate this module.

## Common properties

Here is the list of properties common to all modules. You can specify this properties into the `data` attribute of the module.

{% hint style="info" %}
You can use the `data` attribute to add specific properties to your module.
{% endhint %}

| Attribute     |         Type        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Default |
| ------------- | :-----------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----: |
| **admin**     |         bool        | If `true`, the module is only visible in the Settings Panel, by users who are admin or who have admin capability on this module.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `false` |
| **mandatory** |         bool        | If `true`, this cannot be deactivated from the Module Manager page.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `false` |
| **menu**      | string, bool, array | <ul><li>If the value is a <code>string</code>, this attribute is the name of the route to use, eg <code>uccello.list</code> and the translated module's name will be used as link. You can go to the <a href="routes">Routes</a> page to see all the default routes you can use.<br></li><li>If the value is a <code>false</code>, no link is added to the menu to access this module.<br></li><li><p>If the value is an <code>array</code>, all defined links are added to the menu.<br><br>Link structure :<br>- <code>label</code> : Link label. This label will be translated.<br>- <code>route</code> : Route name.<br>- <code>icon</code>   : Material icon to use. If <code>null</code>, the module's icon is used by default.<br><br>Example:<br>\[<br>  \[<br>    "label" => "menu.settings",<br>    "route" => "settings.index",<br>    "icon" => "settings\_applications"<br>  ],<br>  \[<br>    "label" => "person",<br>    "route" => "uccello.list"<br>  ],</p><p><br>]</p></li></ul><p></p> |         |
| **package**   |        string       | <p>Name of the external package in which the module is located.</p><p>This attribute is only useful for making sharable modules, installable with <a href="https://getcomposer.org/">composer</a>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |  `null` |