# 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` |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://uccello.gitbook.io/doc/the-basics/module.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.