diff --git a/backend-controllers-ajax.md b/backend-controllers-ajax.md index 0b371cdd..c5f94336 100644 --- a/backend-controllers-ajax.md +++ b/backend-controllers-ajax.md @@ -18,16 +18,18 @@ The Winter CMS backend implements the MVC pattern. Controllers manage backend pa Each controller consists of a PHP file which resides in the the **/controllers** subdirectory of a Plugin directory. Controller views are `.htm` files that reside in the controller view directory. The controller view directory name matches the controller class name written in lowercase. The view directory can also contain controller configuration files. An example of a controller directory structure: - plugins/ - acme/ - blog/ - controllers/ - users/ <=== Controller view directory - _partial.htm <=== Controller partial file - config_form.yaml <=== Controller config file - index.htm <=== Controller view file - Users.php <=== Controller class - Plugin.php +```css +πŸ“‚ plugins + β”— πŸ“‚ acme + β”— πŸ“‚ blog + ┣ πŸ“‚ controllers + ┃ ┣ πŸ“‚ users <=== Controller view directory + ┃ ┃ ┣ πŸ“œ _partial.htm <=== Controller partial file + ┃ ┃ ┣ πŸ“œ config_form.yaml <=== Controller config file + ┃ ┃ β”— πŸ“œ index.htm <=== Controller view file + ┃ β”— πŸ“œ Users.php <=== Controller class + β”— πŸ“œ Plugin.php +``` ### Class definition @@ -236,4 +238,4 @@ public function __construct() // Middleware functionality })->except('index'); } -``` \ No newline at end of file +``` diff --git a/backend-forms.md b/backend-forms.md index 309d5557..00deed98 100644 --- a/backend-forms.md +++ b/backend-forms.md @@ -158,13 +158,15 @@ Option | Description Form fields are defined with the YAML file. The form fields configuration is used by the form behavior for creating the form controls and binding them to the model fields. The file is placed to a subdirectory of the **models** directory of a plugin. The subdirectory name matches the model class name written in lowercase. The file name doesn't matter, but **fields.yaml** and **form_fields.yaml** are common names. Example form fields file location: - plugins/ - acme/ - blog/ - models/ <=== Plugin models directory - post/ <=== Model configuration directory - fields.yaml <=== Model form fields config file - Post.php <=== model class +```css +πŸ“‚ plugins + β”— πŸ“‚ acme + β”— πŸ“‚ blog + β”— πŸ“‚ models <=== Plugin models directory + ┣ πŸ“‚ post <=== Model configuration directory + ┃ β”— πŸ“œ fields.yaml <=== Model form fields config file + β”— πŸ“œ Post.php <=== model class +``` Fields can be placed in three areas, the **outside area**, **primary tabs** or **secondary tabs**. The next example shows the typical contents of a form fields definition file. diff --git a/backend-lists.md b/backend-lists.md index e39ccc42..f7ab7703 100644 --- a/backend-lists.md +++ b/backend-lists.md @@ -143,13 +143,15 @@ The **filter** option should make reference to a [filter configuration file](#li List columns are defined with the YAML file. The column configuration is used by the list behavior for creating the record table and displaying model columns in the table cells. The file is placed to a subdirectory of the **models** directory of a plugin. The subdirectory name matches the model class name written in lowercase. The file name doesn't matter, but the **columns.yaml** and **list_columns.yaml** are common names. Example list columns file location: - plugins/ - acme/ - blog/ - models/ <=== Plugin models directory - post/ <=== Model configuration directory - list_columns.yaml <=== Model list columns config file - Post.php <=== model class +```css +πŸ“‚ plugins + β”— πŸ“‚ acme + β”— πŸ“‚ blog + β”— πŸ“‚ models <=== Plugin models directory + ┣ πŸ“‚ post <=== Model configuration directory + ┃ β”— πŸ“œ list_columns.yaml <=== Model list columns config file + β”— πŸ“œ Post.php <=== model class +``` The next example shows the typical contents of a list column definitions file. diff --git a/backend-widgets.md b/backend-widgets.md index 22bc8d28..d6490f2f 100644 --- a/backend-widgets.md +++ b/backend-widgets.md @@ -24,16 +24,18 @@ Widgets are the backend equivalent of frontend [Components](../cms/components). Widget classes reside inside the **widgets** directory of the plugin directory. The directory name matches the name of the widget class written in lowercase. Widgets can supply assets and partials. An example widget directory structure looks like this: - widgets/ - /form - /partials - _form.htm <=== Widget partial file - /assets - /js - form.js <=== Widget JavaScript file - /css - form.css <=== Widget StyleSheet file - Form.php <=== Widget class +```css +πŸ“‚ widgets + ┣ πŸ“‚ form + ┃ ┣ πŸ“‚ partials + ┃ ┃ β”— πŸ“œ _form.htm <=== Widget partial file + ┃ β”— πŸ“‚ assets + ┃ ┣ πŸ“‚ js + ┃ ┃ β”— πŸ“œ form.js <=== Widget JavaScript file + ┃ β”— πŸ“‚ css + ┃ β”— πŸ“œ form.css <=== Widget StyleSheet file + β”— πŸ“œ Form.php <=== Widget class +``` ### Class definition @@ -132,16 +134,18 @@ With form widgets you can add new control types to the backend [forms](../backen Form Widget classes reside inside the **formwidgets** directory of the plugin directory. The directory name matches the name of the widget class written in lowercase. Widgets can supply assets and partials. An example form widget directory structure looks like this: - formwidgets/ - /form - /partials - _form.htm <=== Widget partial file - /assets - /js - form.js <=== Widget JavaScript file - /css - form.css <=== Widget StyleSheet file - Form.php <=== Widget class +```css +πŸ“‚ formwidgets + ┣ πŸ“‚ form + ┃ ┣ πŸ“‚ partials + ┃ ┃ β”— πŸ“œ _form.htm <=== Widget partial file + ┃ β”— πŸ“‚ assets + ┃ ┣ πŸ“‚ js + ┃ ┃ β”— πŸ“œ form.js <=== Widget JavaScript file + ┃ β”— πŸ“‚ css + ┃ β”— πŸ“œ form.css <=== Widget StyleSheet file + β”— πŸ“œ Form.php <=== Widget class +``` ### Class definition @@ -301,14 +305,16 @@ Report widgets can be used on the backend dashboard and in other backend report The report widget classes should extend the `Backend\Classes\ReportWidgetBase` class. As any other plugin class, generic widget controllers should belong to the [plugin namespace](../plugin/registration#namespaces). The class should override the `render` method in order to render the widget itself. Similarly to all backend widgets, report widgets use partials and a special directory layout. Example directory layout: - plugins/ - winter/ <=== Author name - googleanalytics/ <=== Plugin name - reportwidgets/ <=== Report widgets directory - trafficsources <=== Widget files directory - partials - _widget.htm - TrafficSources.php <=== Widget class file +```css +πŸ“‚ plugins + β”— πŸ“‚ winter <=== Author name + β”— πŸ“‚ googleanalytics <=== Plugin name + β”— πŸ“‚ reportwidgets <=== Report widgets directory + ┣ πŸ“‚ trafficsources <=== Widget files directory + ┃ β”— πŸ“‚ partials + ┃ β”— πŸ“œ _widget.htm + β”— πŸ“œ TrafficSources.php <=== Widget class file +``` Example report widget class definition: diff --git a/cms-themes.md b/cms-themes.md index 294e70e4..5492c0fd 100644 --- a/cms-themes.md +++ b/cms-themes.md @@ -32,39 +32,39 @@ Object | Description Below, you can see an example theme directory structure. Each Winter theme is represented with a separate directory and generally, one active theme is used for displaying the website. This example displays the "example-theme" theme directory. -``` +```css πŸ“‚ themes - ┣ πŸ“‚ example-theme - ┃ ┣ πŸ“‚ assets <-- Theme assets - ┃ ┃ ┣ πŸ“‚ css - ┃ ┃ ┣ πŸ“‚ fonts - ┃ ┃ ┣ πŸ“‚ images - ┃ ┃ ┣ πŸ“‚ javascript - ┃ ┃ ┣ πŸ“‚ scss - ┃ ┃ β”— πŸ“‚ vendor - ┃ ┣ πŸ“‚ content <-- Static content files - ┃ ┃ β”— πŸ“‚ static-pages <-- Content files from the Winter.Pages plugin - ┃ ┃ ┃ β”— πŸ“œ index.htm - ┃ ┃ β”— πŸ“œ welcome.htm - ┃ ┣ πŸ“‚ layouts <-- Theme Layouts (Page scaffolds / templates) - ┃ ┃ ┣ πŸ“œ default.htm - ┃ ┃ β”— πŸ“œ sidebar.htm - ┃ ┣ πŸ“‚ meta <-- Menu definitions and other plugin specific YAML files - ┃ ┃ ┣ πŸ“‚ menus - ┃ ┃ ┃ ┣ πŸ“œ main-menu.yaml - ┃ ┃ ┃ β”— πŸ“œ sitemap.yaml <-- Meta file describing the sitemap - ┃ ┃ β”— πŸ“œ static-pages.yaml <-- Meta file describing the structure of the Winter.Pages static pages - ┃ ┣ πŸ“‚ pages <-- Theme Pages (Contain the routing for the frontend) - ┃ ┃ ┣ πŸ“œ 404.htm <-- Page for 404 responses - ┃ ┃ ┣ πŸ“œ home.htm - ┃ ┃ ┣ πŸ“œ error.htm <-- Page for 500 responses - ┃ ┃ β”— πŸ“œ sitemap.htm <-- Page for rendering the sitemap response - ┃ ┣ πŸ“‚ partials <-- Theme Partials (Reusable pieces of HTML markup) - ┃ ┃ ┣ πŸ“œ html-footer.htm - ┃ ┃ ┣ πŸ“œ html-header.htm - ┃ ┃ β”— πŸ“œ navbar.htm - ┃ ┣ πŸ“œ theme.yaml <-- Theme information file - ┃ β”— πŸ“œ version.yaml <-- Theme updates file + β”— πŸ“‚ example-theme + ┣ πŸ“‚ assets <-- Theme assets + ┃ ┣ πŸ“‚ css + ┃ ┣ πŸ“‚ fonts + ┃ ┣ πŸ“‚ images + ┃ ┣ πŸ“‚ javascript + ┃ ┣ πŸ“‚ scss + ┃ β”— πŸ“‚ vendor + ┣ πŸ“‚ content <-- Static content files + ┃ ┣ πŸ“‚ static-pages <-- Content files from the Winter.Pages plugin + ┃ ┃ β”— πŸ“œ index.htm + ┃ β”— πŸ“œ welcome.htm + ┣ πŸ“‚ layouts <-- Theme Layouts (Page scaffolds / templates) + ┃ ┣ πŸ“œ default.htm + ┃ β”— πŸ“œ sidebar.htm + ┣ πŸ“‚ meta <-- Menu definitions and other plugin specific YAML files + ┃ ┣ πŸ“‚ menus + ┃ ┃ ┣ πŸ“œ main-menu.yaml + ┃ ┃ β”— πŸ“œ sitemap.yaml <-- Meta file describing the sitemap + ┃ β”— πŸ“œ static-pages.yaml <-- Meta file describing the structure of the Winter.Pages static pages + ┣ πŸ“‚ pages <-- Theme Pages (Contain the routing for the frontend) + ┃ ┣ πŸ“œ 404.htm <-- Page for 404 responses + ┃ ┣ πŸ“œ home.htm + ┃ ┣ πŸ“œ error.htm <-- Page for 500 responses + ┃ β”— πŸ“œ sitemap.htm <-- Page for rendering the sitemap response + ┣ πŸ“‚ partials <-- Theme Partials (Reusable pieces of HTML markup) + ┃ ┣ πŸ“œ html-footer.htm + ┃ ┣ πŸ“œ html-header.htm + ┃ β”— πŸ“œ navbar.htm + ┣ πŸ“œ theme.yaml <-- Theme information file + β”— πŸ“œ version.yaml <-- Theme updates file ``` > The active theme is set with the `activeTheme` parameter in the `config/cms.php` file or with the Theme Selector on the System > CMS > Frontend Theme backend page. The theme set with the Theme Selector overrides the value in the `config/cms.php` file. @@ -74,22 +74,23 @@ Below, you can see an example theme directory structure. Each Winter theme is re Winter supports single level subdirectories for **pages**, **partials**, **layouts** and **content** files, while the **assets** directory can have any structure. This simplifies the organization of large websites. In the example directory structure below, you can see that the **pages** and **partials** directories contain the **blog** subdirectory, and the **content** directory contains the **home** subdirectory. - themes/ - website/ - pages/ - home.htm - blog/ <=== Subdirectory - archive.htm - category.htm - partials/ - sidebar.htm - blog/ <=== Subdirectory - category-list.htm - content/ - footer-contacts.txt - home/ <=== Subdirectory - intro.htm - ... +```css +πŸ“‚ themes + β”— πŸ“‚ website + ┣ πŸ“‚ pages + ┃ ┣ πŸ“œhome.htm + ┃ β”— πŸ“‚ blog <=== Subdirectory + ┃ ┣ πŸ“œ archive.htm + ┃ β”— πŸ“œ category.htm + ┣ πŸ“‚ partials + ┃ ┣ πŸ“œ sidebar.htm + ┃ β”— πŸ“‚ blog <=== Subdirectory + ┃ β”— πŸ“œ category-list.htm + β”— πŸ“‚ content + ┣ πŸ“œ footer-contacts.txt + β”— πŸ“‚ home <=== Subdirectory + β”— πŸ“œ intro.htm +``` To refer to a partial or a content file from a subdirectory, specify the subdirectory's name before the template's name. Example of rendering a partial from a subdirectory: diff --git a/database-model.md b/database-model.md index e600ef32..089efb4b 100644 --- a/database-model.md +++ b/database-model.md @@ -25,15 +25,17 @@ Winter provides a beautiful and simple Active Record implementation for working Model classes reside in the **models** subdirectory of a plugin directory. An example of a model directory structure: - plugins/ - acme/ - blog/ - models/ - user/ <=== Model config directory - columns.yaml <=== Model config files - fields.yaml <==^ - User.php <=== Model class - Plugin.php +```css +πŸ“‚ plugins + β”— πŸ“‚ acme + β”— πŸ“‚ blog + ┣ πŸ“‚ models + ┃ ┣ πŸ“‚ user <=== Model config directory + ┃ ┃ ┣ πŸ“œ columns.yaml <=== Model config files + ┃ ┃ β”— πŸ“œ fields.yaml <==^ + ┃ β”— πŸ“œ User.php <=== Model class + β”— πŸ“œ Plugin.php +``` The model configuration directory could contain the model's [list column](../backend/lists#list-columns) and [form field](../backend/forms#form-fields) definitions. The model configuration directory name matches the model class name written in lowercase. diff --git a/plugin-components.md b/plugin-components.md index 1d60a230..21cd59d5 100644 --- a/plugin-components.md +++ b/plugin-components.md @@ -24,14 +24,16 @@ Components files and directories reside in the **/components** subdirectory of a plugin directory. Each component has a PHP file defining the component class and an optional component partials directory. The component partials directory name matches the component class name written in lowercase. An example of a component directory structure: - plugins/ - acme/ - myplugin/ - components/ - componentname/ <=== Component partials directory - default.htm <=== Component default markup (optional) - ComponentName.php <=== Component class file - Plugin.php +```css +πŸ“‚ plugins + β”— πŸ“‚ acme + β”— πŸ“‚ myplugin + ┣ πŸ“‚ components + ┃ ┣ πŸ“‚ componentname <=== Component partials directory + ┃ ┃ β”— πŸ“œ default.htm <=== Component default markup (optional) + ┃ β”— πŸ“œ ComponentName.php <=== Component class file + β”— πŸ“œ Plugin.php +``` Components must be [registered in the Plugin registration class](#component-registration) with the `registerComponents` method. diff --git a/plugin-localization.md b/plugin-localization.md index de5c2c35..47f8ffd8 100644 --- a/plugin-localization.md +++ b/plugin-localization.md @@ -13,15 +13,16 @@ Plugins can have localization files in the **lang** subdirectory of the plugin d Below is an example of the plugin's lang directory: - plugins/ - acme/ - todo/ <=== Plugin directory - lang/ <=== Localization directory - en/ <=== Language directory - lang.php <=== Localization file - fr/ - lang.php - +```css +πŸ“‚ plugins + β”— πŸ“‚ acme + β”— πŸ“‚ todo <=== Plugin directory + β”— πŸ“‚ lang <=== Localization directory + ┣ πŸ“‚ en <=== Language directory + ┃ β”— πŸ“œ lang.php <=== Localization file + β”— πŸ“‚ fr + β”— πŸ“œ lang.php +``` The **lang.php** file should define and return an array of any depth, for example: @@ -55,11 +56,13 @@ The localization strings can be loaded with the `Lang` class. The parameter it a System users can override plugin localization strings without altering the plugins' files. This is done by adding localization files to the **lang** directory. For example, to override the lang.php file of the **acme/blog** plugin you should create the file in the following location: - lang/ <=== App localization directory - en/ <=== Language directory - acme/ <=== Plugin / Module directory - blog/ <===^ - lang.php <=== Localization override file +```css +πŸ“‚ lang <=== App localization directory + β”— πŸ“‚ en <=== Language directory + β”— πŸ“‚ acme <=== Plugin / Module directory + β”— πŸ“‚ blog <===^ + β”— πŸ“œ lang.php <=== Localization override file +``` The file could contain only strings you want to override, there is no need to replace the entire file. Example: diff --git a/plugin-registration.md b/plugin-registration.md index 555758d6..ee33b914 100644 --- a/plugin-registration.md +++ b/plugin-registration.md @@ -45,9 +45,9 @@ The simplest plugins only require the **Plugin.php** file described below. ```css πŸ“‚ plugins - ┣ πŸ“‚ myauthor /* Author name */ - ┃ ┣ πŸ“‚ myplugin /* Plugin name */ - ┃ ┃ β”— πŸ“œ Plugin.php /* Plugin registration file, required */ + β”— πŸ“‚ myauthor /* Author name */ + β”— πŸ“‚ myplugin /* Plugin name */ + β”— πŸ“œ Plugin.php /* Plugin registration file, required */ ``` @@ -59,20 +59,20 @@ The following is an example of what most plugins would end up looking like when ```css πŸ“‚ plugins - ┣ πŸ“‚ myauthor /* Author name */ - ┃ ┣ πŸ“‚ myplugin /* Plugin name */ - ┃ ┃ ┣ πŸ“‚ assets /* CSS, JavaScript and image assets for pages and components */ - ┃ ┃ ┣ πŸ“‚ controllers /* Backend controllers */ - ┃ ┃ ┣ πŸ“‚ lang /* Localization files */ - ┃ ┃ ┃ β”— πŸ“‚ en /* Specific locale folder */ - ┃ ┃ ┃ ┃ β”— πŸ“œ lang.php /* Translations */ - ┃ ┃ ┣ πŸ“‚ models /* Models */ - ┃ ┃ ┣ πŸ“‚ updates /* Database migrations */ - ┃ ┃ ┃ β”— πŸ“œ version.yaml /* Changelog */ - ┃ ┃ ┣ πŸ“‚ views /* Custom view files */ - ┃ ┃ ┃ β”— πŸ“‚ mail /* Custom mail templates */ - ┃ ┃ ┣ πŸ“œ README.md /* Documentation describing the purpose of the plugin */ - ┃ ┃ β”— πŸ“œ Plugin.php /* Plugin registration class */ + β”— πŸ“‚ myauthor /* Author name */ + β”— πŸ“‚ myplugin /* Plugin name */ + ┣ πŸ“‚ assets /* CSS, JavaScript and image assets for pages and components */ + ┣ πŸ“‚ controllers /* Backend controllers */ + ┣ πŸ“‚ lang /* Localization files */ + ┃ β”— πŸ“‚ en /* Specific locale folder */ + ┃ β”— πŸ“œ lang.php /* Translations */ + ┣ πŸ“‚ models /* Models */ + ┣ πŸ“‚ updates /* Database migrations */ + ┃ β”— πŸ“œ version.yaml /* Changelog */ + ┣ πŸ“‚ views /* Custom view files */ + ┃ β”— πŸ“‚ mail /* Custom mail templates */ + ┣ πŸ“œ README.md /* Documentation describing the purpose of the plugin */ + β”— πŸ“œ Plugin.php /* Plugin registration class */ ``` @@ -82,62 +82,62 @@ The following is an example of what a complex plugin could look like when using ```css πŸ“‚ plugins - ┣ πŸ“‚ myauthor /* Author name */ - ┃ ┣ πŸ“‚ myplugin /* Plugin name */ - ┃ ┃ ┣ πŸ“‚ assets /* CSS, JavaScript and image assets for pages and components */ - ┃ ┃ ┃ ┣ πŸ“‚ css - ┃ ┃ ┃ ┣ πŸ“‚ favicons - ┃ ┃ ┃ ┣ πŸ“‚ images - ┃ ┃ ┃ ┣ πŸ“‚ js - ┃ ┃ ┃ β”— πŸ“‚ scss - ┃ ┃ ┣ πŸ“‚ behaviors /* Any custom behaviors provided by the plugin */ - ┃ ┃ ┣ πŸ“‚ classes /* Any custom classes provided by the plugin */ - ┃ ┃ ┣ πŸ“‚ config /* Configuration files */ - ┃ ┃ ┃ β”— πŸ“œ config.php - ┃ ┃ ┣ πŸ“‚ console /* Any custom CLI commands provided by the plugin */ - ┃ ┃ ┣ πŸ“‚ controllers /* Backend controllers */ - ┃ ┃ ┃ ┣ πŸ“‚ records /* Directory for the view and configuration files for the given controller */ - ┃ ┃ ┃ ┃ ┣ πŸ“œ _list_toolbar.htm /* List toolbar partial file */ - ┃ ┃ ┃ ┃ ┣ πŸ“œ config_filter.yaml /* Configuration for the Filter widget present on the controller lists */ - ┃ ┃ ┃ ┃ ┣ πŸ“œ config_form.yaml /* Configuration for the Form widget present on the controller */ - ┃ ┃ ┃ ┃ ┣ πŸ“œ config_importexport.yaml /* Configuration for the Import/Export behavior */ - ┃ ┃ ┃ ┃ ┣ πŸ“œ config_list.yaml /* Configuration for the Lists widget present on the controller */ - ┃ ┃ ┃ ┃ ┣ πŸ“œ config_relation.yaml /* Configuration for the RelationController behavior */ - ┃ ┃ ┃ ┃ ┣ πŸ“œ create.htm /* View file for the create action */ - ┃ ┃ ┃ ┃ ┣ πŸ“œ index.htm /* View file for the index action */ - ┃ ┃ ┃ ┃ ┣ πŸ“œ preview.htm /* View file for the preview action */ - ┃ ┃ ┃ ┃ β”— πŸ“œ update.htm /* View file for the update action */ - ┃ ┃ ┃ ┣ πŸ“œ Records.php /* Backend controller for the Record model */ - ┃ ┃ ┣ πŸ“‚ docs /* Any plugin-specific documentation should live here */ - ┃ ┃ ┣ πŸ“‚ formwidgets /* Any custom FormWidgets provided by the plugin */ - ┃ ┃ ┣ πŸ“‚ lang /* Localization files */ - ┃ ┃ ┃ β”— πŸ“‚ en /* Specific locale folder */ - ┃ ┃ ┃ ┃ β”— πŸ“œ lang.php /* Translations for that locale */ - ┃ ┃ ┣ πŸ“‚ layouts /* Any custom backend layouts used by the plugin */ - ┃ ┃ ┣ πŸ“‚ models /* Models provided by the plugin */ - ┃ ┃ ┃ ┣ πŸ“‚ record /* Directory containing configuration files specific to that model */ - ┃ ┃ ┃ ┃ ┣ πŸ“œ columns.yaml /* Configuration file used for the Lists widget */ - ┃ ┃ ┃ ┃ β”— πŸ“œ fields.yaml /* Configuration file used for the Form widget */ - ┃ ┃ ┃ ┣ πŸ“œ Record.php /* Model class for the Record model */ - ┃ ┃ ┣ πŸ“‚ partials /* Any custom partials used by the plugin */ - ┃ ┃ ┣ πŸ“‚ reportwidgets /* Any custom ReportWidgets provided by the plugin */ - ┃ ┃ ┣ πŸ“‚ tests /* Test suite for the plugin */ - ┃ ┃ ┣ πŸ“‚ traits /* Any custom Traits provided by the plugin */ - ┃ ┃ ┣ πŸ“‚ updates /* Database migrations */ - ┃ ┃ ┃ ┃ ┣ πŸ“‚ v1.0.0 /* Migrations for a specific version of the plugin */ - ┃ ┃ ┃ ┃ ┃ β”— πŸ“œ create_records_table.php /* Database migration file, referenced in version.yaml */ - ┃ ┃ ┃ β”— πŸ“œ version.yaml /* Changelog */ - ┃ ┃ ┣ πŸ“‚ views /* Custom view files */ - ┃ ┃ ┃ β”— πŸ“‚ mail /* Custom mail templates provided by the plugin */ - ┃ ┃ ┣ πŸ“‚ widgets /* Any custom Widgets provided by the plugin */ - ┃ ┃ ┣ πŸ“œ LICENSE /* License file */ - ┃ ┃ ┣ πŸ“œ README.md /* Documentation describing the purpose of the plugin */ - ┃ ┃ ┣ πŸ“œ Plugin.php /* Plugin registration file */ - ┃ ┃ ┣ πŸ“œ composer.json /* Composer file to manage dependencies for the plugin */ - ┃ ┃ ┣ πŸ“œ helpers.php /* Global helpers provided by the plugin loaded via composer.json */ - ┃ ┃ ┣ πŸ“œ phpunit.xml /* Unit testing configuration */ - ┃ ┃ ┣ πŸ“œ plugin.yaml /* Simplified plugin registration configuration YAML file, used by Builder plugin */ - ┃ ┃ β”— πŸ“œ routes.php /* Any custom routes provided by the plugin */ + β”— πŸ“‚ myauthor /* Author name */ + β”— πŸ“‚ myplugin /* Plugin name */ + ┣ πŸ“‚ assets /* CSS, JavaScript and image assets for pages and components */ + ┃ ┣ πŸ“‚ css + ┃ ┣ πŸ“‚ favicons + ┃ ┣ πŸ“‚ images + ┃ ┣ πŸ“‚ js + ┃ β”— πŸ“‚ scss + ┣ πŸ“‚ behaviors /* Any custom behaviors provided by the plugin */ + ┣ πŸ“‚ classes /* Any custom classes provided by the plugin */ + ┣ πŸ“‚ config /* Configuration files */ + ┃ β”— πŸ“œ config.php + ┣ πŸ“‚ console /* Any custom CLI commands provided by the plugin */ + ┣ πŸ“‚ controllers /* Backend controllers */ + ┃ ┣ πŸ“‚ records /* Directory for the view and configuration files for the given controller */ + ┃ ┃ ┣ πŸ“œ _list_toolbar.htm /* List toolbar partial file */ + ┃ ┃ ┣ πŸ“œ config_filter.yaml /* Configuration for the Filter widget present on the controller lists */ + ┃ ┃ ┣ πŸ“œ config_form.yaml /* Configuration for the Form widget present on the controller */ + ┃ ┃ ┣ πŸ“œ config_importexport.yaml /* Configuration for the Import/Export behavior */ + ┃ ┃ ┣ πŸ“œ config_list.yaml /* Configuration for the Lists widget present on the controller */ + ┃ ┃ ┣ πŸ“œ config_relation.yaml /* Configuration for the RelationController behavior */ + ┃ ┃ ┣ πŸ“œ create.htm /* View file for the create action */ + ┃ ┃ ┣ πŸ“œ index.htm /* View file for the index action */ + ┃ ┃ ┣ πŸ“œ preview.htm /* View file for the preview action */ + ┃ ┃ β”— πŸ“œ update.htm /* View file for the update action */ + ┃ β”— πŸ“œ Records.php /* Backend controller for the Record model */ + ┣ πŸ“‚ docs /* Any plugin-specific documentation should live here */ + ┣ πŸ“‚ formwidgets /* Any custom FormWidgets provided by the plugin */ + ┣ πŸ“‚ lang /* Localization files */ + ┃ β”— πŸ“‚ en /* Specific locale folder */ + ┃ β”— πŸ“œ lang.php /* Translations for that locale */ + ┣ πŸ“‚ layouts /* Any custom backend layouts used by the plugin */ + ┣ πŸ“‚ models /* Models provided by the plugin */ + ┃ ┣ πŸ“‚ record /* Directory containing configuration files specific to that model */ + ┃ ┃ ┣ πŸ“œ columns.yaml /* Configuration file used for the Lists widget */ + ┃ ┃ β”— πŸ“œ fields.yaml /* Configuration file used for the Form widget */ + ┃ β”— πŸ“œ Record.php /* Model class for the Record model */ + ┣ πŸ“‚ partials /* Any custom partials used by the plugin */ + ┣ πŸ“‚ reportwidgets /* Any custom ReportWidgets provided by the plugin */ + ┣ πŸ“‚ tests /* Test suite for the plugin */ + ┣ πŸ“‚ traits /* Any custom Traits provided by the plugin */ + ┣ πŸ“‚ updates /* Database migrations */ + ┃ ┃ β”— πŸ“‚ v1.0.0 /* Migrations for a specific version of the plugin */ + ┃ ┃ β”— πŸ“œ create_records_table.php /* Database migration file, referenced in version.yaml */ + ┃ β”— πŸ“œ version.yaml /* Changelog */ + ┣ πŸ“‚ views /* Custom view files */ + ┃ β”— πŸ“‚ mail /* Custom mail templates provided by the plugin */ + ┣ πŸ“‚ widgets /* Any custom Widgets provided by the plugin */ + ┣ πŸ“œ LICENSE /* License file */ + ┣ πŸ“œ README.md /* Documentation describing the purpose of the plugin */ + ┣ πŸ“œ Plugin.php /* Plugin registration file */ + ┣ πŸ“œ composer.json /* Composer file to manage dependencies for the plugin */ + ┣ πŸ“œ helpers.php /* Global helpers provided by the plugin loaded via composer.json */ + ┣ πŸ“œ phpunit.xml /* Unit testing configuration */ + ┣ πŸ“œ plugin.yaml /* Simplified plugin registration configuration YAML file, used by Builder plugin */ + β”— πŸ“œ routes.php /* Any custom routes provided by the plugin */ ``` diff --git a/plugin-settings.md b/plugin-settings.md index 59dedcde..96664540 100644 --- a/plugin-settings.md +++ b/plugin-settings.md @@ -40,13 +40,15 @@ The `$settingsCode` property is required for settings models. It defines the uni The `$settingsFields` property is required if are going to build a backend settings form based on the model. The property specifies a name of the YAML file containing the form fields definition. The form fields are described in the [backend forms](../backend/forms) article. The YAML file should be placed to the directory with the name matching the model class name in lowercase. For the model from the previous example the directory structure would look like this: - plugins/ - acme/ - demo/ - models/ - settings/ <=== Model files directory - fields.yaml <=== Model form fields - Settings.php <=== Model script +```css +πŸ“‚ plugins + β”— πŸ“‚ acme + β”— πŸ“‚ demo + β”— πŸ“‚ models + ┣ πŸ“‚ settings <=== Model files directory + ┃ β”— πŸ“œ fields.yaml <=== Model form fields + β”— πŸ“œ Settings.php <=== Model script +``` Settings models [can be registered](#backend-pages) to appear on the **backend Settings page**, but it is not a requirement - you can set and read settings values like any other model. diff --git a/plugin-updates.md b/plugin-updates.md index 57823630..5aeadff1 100644 --- a/plugin-updates.md +++ b/plugin-updates.md @@ -16,13 +16,13 @@ The change log is stored in a YAML file called `version.yaml` inside the **/upda ```css πŸ“‚ plugins - ┣ πŸ“‚ myauthor <-- Author name - ┃ ┣ πŸ“‚ myplugin <-- Plugin name - ┃ ┃ ┣ πŸ“‚ updates <-- Database migrations - ┃ ┃ ┃ ┃ ┣ πŸ“‚ v1.0.0 <-- Migrations for a specific version of the plugin - ┃ ┃ ┃ ┃ ┃ ┣ πŸ“œ seed_the_database.php <-- Database seed file, referenced in version.yaml - ┃ ┃ ┃ ┃ ┃ β”— πŸ“œ create_records_table.php <-- Database migration file, referenced in version.yaml - ┃ ┃ ┃ β”— πŸ“œ version.yaml <-- Changelog + β”— πŸ“‚ myauthor <-- Author name + β”— πŸ“‚ myplugin <-- Plugin name + β”— πŸ“‚ updates <-- Database migrations + ┣ πŸ“‚ v1.0.0 <-- Migrations for a specific version of the plugin + ┃ ┣ πŸ“œ seed_the_database.php <-- Database seed file, referenced in version.yaml + ┃ β”— πŸ“œ create_records_table.php <-- Database migration file, referenced in version.yaml + β”— πŸ“œ version.yaml <-- Changelog ``` diff --git a/themes-development.md b/themes-development.md index 2e1e26b8..eeb01066 100644 --- a/themes-development.md +++ b/themes-development.md @@ -16,10 +16,10 @@ The theme directory could include the **theme.yaml**, **version.yaml** and **ass The theme information file **theme.yaml** contains the theme description, the author name, URL of the author's website and some other information. The file should be placed to the theme root directory: -``` +```css πŸ“‚ themes - ┣ πŸ“‚ example-theme - ┃ β”— πŸ“œ theme.yaml <-- Theme information file + β”— πŸ“‚ example-theme + β”— πŸ“œ theme.yaml <-- Theme information file ``` The following fields are supported in the **theme.yaml** file: @@ -50,10 +50,10 @@ code: "demo" The theme version file **version.yaml** defines the current theme version and the change log. The file should be placed to the theme root directory: -``` +```css πŸ“‚ themes - ┣ πŸ“‚ example-theme - ┃ β”— πŸ“œ version.yaml <-- Theme version file + β”— πŸ“‚ example-theme + β”— πŸ“œ version.yaml <-- Theme version file ``` The file format is following: @@ -69,12 +69,12 @@ The file format is following: The theme preview image is used in the backend theme selector. The image file **theme-preview.png** should be placed to the theme's **assets/images** directory: -``` +```css πŸ“‚ themes - ┣ πŸ“‚ example-theme - ┃ ┣ πŸ“‚ assets - ┃ ┃ ┣ πŸ“‚ images - ┃ ┃ ┃ β”— πŸ“œ theme-preview.png <-- Theme Preview Image + β”— πŸ“‚ example-theme + β”— πŸ“‚ assets + β”— πŸ“‚ images + β”— πŸ“œ theme-preview.png <-- Theme Preview Image ``` The image width should be at least 600px. The ideal aspect ratio is 1.5, for example 600x400px. @@ -187,14 +187,14 @@ Themes can provide backend localization keys through files placed in the **lang* Below is an example of the theme's lang directory: -``` -πŸ“¦themes - ┣ πŸ“‚ example-theme <-- Theme directory - ┃ ┣ πŸ“‚ lang <-- Localization directory - ┃ ┃ ┣ πŸ“‚ en <-- Specific locale directory - ┃ ┃ ┃ β”— πŸ“œ lang.php <-- Localization file - ┃ ┃ ┣ πŸ“‚ fr - ┃ ┃ ┃ β”— πŸ“œ lang.php +```css +πŸ“‚ themes + β”— πŸ“‚ example-theme <-- Theme directory + β”— πŸ“‚ lang <-- Localization directory + ┣ πŸ“‚ en <-- Specific locale directory + ┃ β”— πŸ“œ lang.php <-- Localization file + β”— πŸ“‚ fr + β”— πŸ“œ lang.php ``` The **lang.php** file should define and return an array of any depth, for example: