Packages¶

In order to ease development and collaboration, eQual organizes application logic into themed packages represented by folders, located under the /packages directory.

These packages contain several components : models, views, controllers, and translation files. Models define data structure, views describe user interface, controllers manage data flow, and translations support i18n features.

Package structure¶

Each package is defined as follows :

package_name
├── classes
│   └── */*.class.php
├── actions
│   └── */*.php
├── apps
│   └── */*.php
├── data
│   └── */*.php
├── tests
│   └── */*.php
├── init
│   ├── data
│   |   └── *.json
|   ├── test
│   |   └── *.json
│   ├── demo
│   |   └── *.json
│   ├── bin
│   |   └── *.*
│   ├── routes
│   |   └── *.json
│   └── assets
│       ├── css
│       ├── fonts
│       ├── img
│       |   └── brand
│       └── js
├── views
│   └── *
│       └── *.json
├── i18n
│   └── *
│       └── *.json
├── manifest.json         
├── config.json
└── readme.md

Folder	Role	Example
`classes`	model	`core\User.class.php`, `core\Group.class.php`, `core\Permission.class.php`
`actions`	action handler (controller)	`core_manage`, `core_utils`
`apps`	applications related to the package	`auth`, `apps`
`data`	data provider	`core_model_read`, `core_config_packages`
`tests`	test units	`default.php`
`init`	initialize the package (entities, data, routes)	`core_Group.json`
`views`	templates	`User.form.default.json`, `User.list.default.json`
`i18n`	translations	`User.json`
`assets`	static content (resources)	js scripts, stylesheets, fonts, images

Self description (root)¶

README.md¶

A markdown file containing various relevant information about the package, its installation, configuration, and the features it offers.

manifest.json¶

Packages manifests are an essential tool for managing the packages ecosystem and ensure compatibility between different components and versions of software libraries, facilitating seamless integration and streamlined development processes.

Each package has a manifest file (manifest.json) containing information about the package along with the apps it provides and the dependencies it requires.

Property	Role	Example
`name`	`(string)` Name of the package, also used as an identifier. It should match the name of the folder of the package.	`"core"`
`version`	`(string)` The version of the package, ensuring accurate versionning.	`"2.0"`
`description`	`(string)` Short description of the package.	`"A short and yet explicit description of the package."`
`license`	`(string)` The license (and version) of the package.	`"LGPL-3"`
`authors`	`(array <string>)` List of the name(s) of the author(s).	`["Cedric Francoys"]`
`tags`	`(array <string>)` List of descriptive tags or keywords associated with the package for easier categorization and searchability.	`["Cedric Francoys"]`
`depends_on`	`(array <string>)` List of packages that need to be present and initialized in order for the package to work.	`[]`
`requires`	`(object)` Map specifying external libraries or packages required by the package, along with version constraints using semantic versionning.	`"requires": {"swiftmailer/swiftmailer": "^6.2"}`
`config`	`(object)` Map associating config constants to the values specific to the package.	`"config": {"APP_LOGO_URL": "/assets/img/brand/logo.svg"}`
`apps`	`(array <string \| object>)` Applications embedded in the package. The list provides either Apps names (identifier) or descriptors for virtual apps to be used with the STD App (see below).	`["apps", "auth", "app", "settings"]`

Example:

{
    "name": "core",
    "description": "Foundation package holding common application logic and elementary entities.",
    "version": "2.0",
    "authors": ["Author Names"],
    "license": "License Type",
    "tags": [ "equal", "core" ],
    "depends_on": [],
    "requires": {
        "swiftmailer/swiftmailer": "^6.2",
        "phpoffice/phpspreadsheet": "^1.4",
        "dompdf/dompdf": "^0.8.3"
    },
    "apps": [ "apps", "auth", "app", "settings", "workbench", "welcome" ]
}

`requires` property¶

eQual is versionned so that there is a specific PHP version expected as "standard" environement (e.g. equal 1.0 = PHP 7.4, equal 2.0 = PHP 8.3).

In the manifest.json file of a package, dependencies are specified in the "requires" property.

When dependency constraints vary between different PHP versions, by convention, a requires_ property is added in the manifest.

Example:

"requires_php8.3": {

}

This notation is not taken into account during the package initialization nor Composer, but serves as a reminder for specific dependencies in cases where installation is performed in a non-standard environment.

`apps` property¶

The apps property might either contain strings or descriptor objects. The app application, defined in the core package, can act as surrogate for creating custom Apps using all standard features without having to write additional Angular components. In such case, the descriptor is expected to be a full descriptor of the app, similar to the ones used in the manifest of Apps.

Example of custom App definition

{
        "id": "inventory",
        "name": "Inventory",
        "extends": "app",
        "description": "Application inventory",
        "icon": "analytics",
        "color": "#6C3483",
        "text_color": "#050505",
        "access": {
            "groups": [
                "users"
            ]
        },
        "params": {
            "menus": {
                "left": "inventory.left",
                "top": "inventory.top"
            }
        }
}

apps folder¶

manifest.json¶

Property	Role	Example
name	The name of the application.	`Settings`
description	A short description of the role and usage of the application.
url	Relative URL of the application.	`/settings`
icon (optional)	Identifier of the (material) icon for representing the application.	`settings`
color (optional)	Color used for the button (background-color). Defaults to `#b0b0b0`	`#FF9741`
text_color (optional)	Color used for the text of the button (color). Defaults to `#ffffff`	`#000000`
extends (optional)	String telling which application it extends from, if any.	`app`
access/groups	List of groups the access to the application is restricted to.	`['users']`
params	Object to be relayed to the targeted App targeted with `extends`(if supported).	`"params": { "menus" : { "left": "myApp.left" } }`
params.menus	The menu to be displayed for the App (possible menus are 'left' and 'right').
params.context	The context to be used for the root URL ('/').
show_in_apps	Flag telling if the application must be listed in the dashboard Apps list.	default: `false`
tags (optional)	List of labels for tagging of the application.	`["equal", "core"]`

params¶

The params property allows to provide the surrogate application (app) with parameters specific to the application being described. It can be used to define which menus must be loaded and which context must be displayed by default.

Example:

"params": {
    "menus": {
        "left": "settings.left",
        "top": "settings.top"
    },
    "context": {
        "entity": "core\\User"
        "view": "list.default",
        "order": "id",
        "sort": "asc"
    }
}

actions folder¶

data folder¶

tests folder¶

init folder¶

Subfolder	Description
data	The name of the application.
test	A short description of the role and usage of the application.
demo	Relative URL of the application.
bin
routes
assets	HTML dependencies (img, js, css) to be copied in the `public/assets` folder.

Packages¶

Package structure¶

Self description (root)¶

README.md¶

manifest.json¶

requires property¶

apps property¶

apps folder¶

manifest.json¶

params¶

actions folder¶

data folder¶

tests folder¶

init folder¶

`requires` property¶

`apps` property¶