From 52d0429d108f84c9a6632bb08d39f9ce22f8600e Mon Sep 17 00:00:00 2001 From: Web-VPF Date: Sun, 2 Jan 2022 23:52:53 +0200 Subject: [PATCH 1/9] Improving structure diagrams --- backend-controllers-ajax.md | 26 ++++++++------ backend-forms.md | 17 +++++---- backend-lists.md | 17 +++++---- backend-widgets.md | 69 ++++++++++++++++++++++--------------- plugin-components.md | 20 ++++++----- plugin-localization.md | 30 ++++++++-------- plugin-settings.md | 17 +++++---- 7 files changed, 114 insertions(+), 82 deletions(-) diff --git a/backend-controllers-ajax.md b/backend-controllers-ajax.md index 0b371cdd..f421a60d 100644 --- a/backend-controllers-ajax.md +++ b/backend-controllers-ajax.md @@ -18,16 +18,20 @@ 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 +``` +πŸ“‚ 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 +240,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..50e0b3f2 100644 --- a/backend-forms.md +++ b/backend-forms.md @@ -158,13 +158,16 @@ 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 +``` +πŸ“‚ 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..d7ea8bda 100644 --- a/backend-lists.md +++ b/backend-lists.md @@ -143,13 +143,16 @@ 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 +``` +πŸ“‚ 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..96fbd8d5 100644 --- a/backend-widgets.md +++ b/backend-widgets.md @@ -24,16 +24,21 @@ 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 +``` +πŸ“‚ 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 +137,21 @@ 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 +``` +πŸ“‚ 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 +311,17 @@ 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 +``` +πŸ“‚ 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/plugin-components.md b/plugin-components.md index 1d60a230..1147c225 100644 --- a/plugin-components.md +++ b/plugin-components.md @@ -24,14 +24,18 @@ 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 +``` +πŸ“‚ 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..0e81c031 100644 --- a/plugin-localization.md +++ b/plugin-localization.md @@ -13,15 +13,17 @@ 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 - +``` +πŸ“‚ 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 +57,11 @@ 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 +πŸ“‚ 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-settings.md b/plugin-settings.md index 59dedcde..30a28556 100644 --- a/plugin-settings.md +++ b/plugin-settings.md @@ -40,13 +40,16 @@ 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 +``` +πŸ“‚ 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. From 89d205388838da248cf369b5e616bde16f69f01b Mon Sep 17 00:00:00 2001 From: Web-VPF Date: Sun, 2 Jan 2022 23:58:54 +0200 Subject: [PATCH 2/9] fix --- plugin-localization.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/plugin-localization.md b/plugin-localization.md index 0e81c031..ccbaad33 100644 --- a/plugin-localization.md +++ b/plugin-localization.md @@ -57,11 +57,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 +``` The file could contain only strings you want to override, there is no need to replace the entire file. Example: From e3c72c6c2929e9705200968ce25286661c5315ef Mon Sep 17 00:00:00 2001 From: Web-VPF Date: Mon, 3 Jan 2022 01:16:13 +0200 Subject: [PATCH 3/9] Improving structure diagrams --- backend-controllers-ajax.md | 2 +- backend-forms.md | 2 +- backend-lists.md | 2 +- backend-widgets.md | 2 +- cms-themes.md | 41 ++++++++++++++++++++++--------------- database-model.md | 22 ++++++++++++-------- plugin-components.md | 2 +- plugin-localization.md | 2 +- plugin-settings.md | 2 +- plugin-updates.md | 19 +++++++++-------- themes-development.md | 29 +++++++++++++------------- 11 files changed, 70 insertions(+), 55 deletions(-) diff --git a/backend-controllers-ajax.md b/backend-controllers-ajax.md index f421a60d..1e689fd1 100644 --- a/backend-controllers-ajax.md +++ b/backend-controllers-ajax.md @@ -19,7 +19,7 @@ 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 +πŸ“¦ plugins β”— πŸ“‚ acme β”— πŸ“‚ blog ┣ πŸ“‚ controllers diff --git a/backend-forms.md b/backend-forms.md index 50e0b3f2..4266780d 100644 --- a/backend-forms.md +++ b/backend-forms.md @@ -159,7 +159,7 @@ 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 +πŸ“¦ plugins β”— πŸ“‚ acme β”— πŸ“‚ blog β”— πŸ“‚ models <=== Plugin models directory diff --git a/backend-lists.md b/backend-lists.md index d7ea8bda..dadcb095 100644 --- a/backend-lists.md +++ b/backend-lists.md @@ -144,7 +144,7 @@ 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 +πŸ“¦ plugins β”— πŸ“‚ acme β”— πŸ“‚ blog β”— πŸ“‚ models <=== Plugin models directory diff --git a/backend-widgets.md b/backend-widgets.md index 96fbd8d5..a48b81b7 100644 --- a/backend-widgets.md +++ b/backend-widgets.md @@ -25,7 +25,7 @@ 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 +πŸ“¦ widgets ┣ πŸ“‚ form ┃ ┣ πŸ“‚ partials ┃ ┃ β”— πŸ“œ _form.htm <=== Widget partial file diff --git a/cms-themes.md b/cms-themes.md index 294e70e4..cd7ef0fc 100644 --- a/cms-themes.md +++ b/cms-themes.md @@ -74,22 +74,31 @@ 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 - ... +``` +πŸ“¦ 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..77f88555 100644 --- a/database-model.md +++ b/database-model.md @@ -25,15 +25,19 @@ 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 +``` +πŸ“¦ 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 1147c225..4dbcedc6 100644 --- a/plugin-components.md +++ b/plugin-components.md @@ -25,7 +25,7 @@ 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 +πŸ“¦ plugins β”— πŸ“‚ acme β”— πŸ“‚ myplugin ┣ πŸ“‚ components diff --git a/plugin-localization.md b/plugin-localization.md index ccbaad33..a8b6c083 100644 --- a/plugin-localization.md +++ b/plugin-localization.md @@ -58,7 +58,7 @@ 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 +πŸ“¦ lang <=== App localization directory β”— πŸ“‚ en <=== Language directory β”— πŸ“‚ acme <=== Plugin / Module directory β”— πŸ“‚ blog <===^ diff --git a/plugin-settings.md b/plugin-settings.md index 30a28556..bd773295 100644 --- a/plugin-settings.md +++ b/plugin-settings.md @@ -41,7 +41,7 @@ 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 +πŸ“¦ plugins β”— πŸ“‚ acme β”— πŸ“‚ demo β”— πŸ“‚ models diff --git a/plugin-updates.md b/plugin-updates.md index 57823630..13d7e4a0 100644 --- a/plugin-updates.md +++ b/plugin-updates.md @@ -14,15 +14,16 @@ It is good practice for plugins to maintain a change log that documents any chan The change log is stored in a YAML file called `version.yaml` inside the **/updates** directory of a plugin, which co-exists with migration and seed files. This example displays a typical plugin updates directory structure: -```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 +``` +πŸ“¦ 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 ``` diff --git a/themes-development.md b/themes-development.md index 2e1e26b8..61d6235c 100644 --- a/themes-development.md +++ b/themes-development.md @@ -18,8 +18,8 @@ The theme information file **theme.yaml** contains the theme description, the au ``` πŸ“‚ 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: @@ -52,8 +52,8 @@ The theme version file **version.yaml** defines the current theme version and th ``` πŸ“‚ themes - ┣ πŸ“‚ example-theme - ┃ β”— πŸ“œ version.yaml <-- Theme version file + β”— πŸ“‚ example-theme + β”— πŸ“œ version.yaml <-- Theme version file ``` The file format is following: @@ -71,10 +71,10 @@ The theme preview image is used in the backend theme selector. The image file ** ``` πŸ“‚ 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. @@ -189,12 +189,13 @@ 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 + β”— πŸ“‚ 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: From a5109a53d67ea9378479c399df8245ec1399ec23 Mon Sep 17 00:00:00 2001 From: WebVPF <61043464+WebVPF@users.noreply.github.com> Date: Mon, 3 Jan 2022 17:22:02 +0200 Subject: [PATCH 4/9] Update backend-controllers-ajax.md Co-authored-by: Luke Towers --- backend-controllers-ajax.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/backend-controllers-ajax.md b/backend-controllers-ajax.md index 1e689fd1..c67cec06 100644 --- a/backend-controllers-ajax.md +++ b/backend-controllers-ajax.md @@ -18,8 +18,8 @@ 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 +```css +πŸ“‚ plugins β”— πŸ“‚ acme β”— πŸ“‚ blog ┣ πŸ“‚ controllers @@ -27,11 +27,8 @@ Each controller consists of a PHP file which resides in the the **/controllers** ┃ ┃ ┣ πŸ“œ _partial.htm <=== Controller partial file ┃ ┃ ┣ πŸ“œ config_form.yaml <=== Controller config file ┃ ┃ β”— πŸ“œ index.htm <=== Controller view file - ┃ ┃ ┃ β”— πŸ“œ Users.php <=== Controller class - ┃ β”— πŸ“œ Plugin.php -``` ### Class definition From 85018257710d1c6469f981f0a00dfaaea515eefa Mon Sep 17 00:00:00 2001 From: Web-VPF Date: Mon, 3 Jan 2022 17:36:27 +0200 Subject: [PATCH 5/9] fix --- backend-controllers-ajax.md | 1 + backend-forms.md | 9 ++++----- backend-lists.md | 5 ++--- backend-widgets.md | 15 ++++----------- cms-themes.md | 8 ++------ database-model.md | 6 ++---- plugin-components.md | 6 ++---- plugin-localization.md | 7 +++---- plugin-settings.md | 5 ++--- plugin-updates.md | 5 ++--- themes-development.md | 17 ++++++++--------- 11 files changed, 32 insertions(+), 52 deletions(-) diff --git a/backend-controllers-ajax.md b/backend-controllers-ajax.md index c67cec06..c5f94336 100644 --- a/backend-controllers-ajax.md +++ b/backend-controllers-ajax.md @@ -29,6 +29,7 @@ Each controller consists of a PHP file which resides in the the **/controllers** ┃ ┃ β”— πŸ“œ index.htm <=== Controller view file ┃ β”— πŸ“œ Users.php <=== Controller class β”— πŸ“œ Plugin.php +``` ### Class definition diff --git a/backend-forms.md b/backend-forms.md index 4266780d..00deed98 100644 --- a/backend-forms.md +++ b/backend-forms.md @@ -158,14 +158,13 @@ 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 +```css +πŸ“‚ plugins β”— πŸ“‚ acme β”— πŸ“‚ blog - β”— πŸ“‚ models <=== Plugin models directory - ┣ πŸ“‚ post <=== Model configuration directory + β”— πŸ“‚ models <=== Plugin models directory + ┣ πŸ“‚ post <=== Model configuration directory ┃ β”— πŸ“œ fields.yaml <=== Model form fields config file - ┃ β”— πŸ“œ Post.php <=== model class ``` diff --git a/backend-lists.md b/backend-lists.md index dadcb095..f7ab7703 100644 --- a/backend-lists.md +++ b/backend-lists.md @@ -143,14 +143,13 @@ 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 +```css +πŸ“‚ plugins β”— πŸ“‚ acme β”— πŸ“‚ blog β”— πŸ“‚ models <=== Plugin models directory ┣ πŸ“‚ post <=== Model configuration directory ┃ β”— πŸ“œ list_columns.yaml <=== Model list columns config file - ┃ β”— πŸ“œ Post.php <=== model class ``` diff --git a/backend-widgets.md b/backend-widgets.md index a48b81b7..d6490f2f 100644 --- a/backend-widgets.md +++ b/backend-widgets.md @@ -24,19 +24,16 @@ 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 +```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 ``` @@ -137,19 +134,16 @@ 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: -``` +```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 ``` @@ -311,7 +305,7 @@ 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: -``` +```css πŸ“‚ plugins β”— πŸ“‚ winter <=== Author name β”— πŸ“‚ googleanalytics <=== Plugin name @@ -319,7 +313,6 @@ The report widget classes should extend the `Backend\Classes\ReportWidgetBase` c ┣ πŸ“‚ trafficsources <=== Widget files directory ┃ β”— πŸ“‚ partials ┃ β”— πŸ“œ _widget.htm - ┃ β”— πŸ“œ TrafficSources.php <=== Widget class file ``` diff --git a/cms-themes.md b/cms-themes.md index cd7ef0fc..0dec573b 100644 --- a/cms-themes.md +++ b/cms-themes.md @@ -74,25 +74,21 @@ 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 +```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 ┃ diff --git a/database-model.md b/database-model.md index 77f88555..a6a8360c 100644 --- a/database-model.md +++ b/database-model.md @@ -25,17 +25,15 @@ 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 +```css +πŸ“‚ plugins β”— πŸ“‚ acme β”— πŸ“‚ blog ┣ πŸ“‚ models ┃ ┣ πŸ“‚ user <=== Model config directory ┃ ┃ ┣ πŸ“œ columns.yaml <=== Model config files ┃ ┃ β”— πŸ“œ fields.yaml <==^ - ┃ ┃ ┃ β”— πŸ“œ User.php <=== Model class - ┃ β”— Plugin.php ``` diff --git a/plugin-components.md b/plugin-components.md index 4dbcedc6..21cd59d5 100644 --- a/plugin-components.md +++ b/plugin-components.md @@ -24,16 +24,14 @@ 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 +```css +πŸ“‚ plugins β”— πŸ“‚ acme β”— πŸ“‚ myplugin ┣ πŸ“‚ components ┃ ┣ πŸ“‚ componentname <=== Component partials directory ┃ ┃ β”— πŸ“œ default.htm <=== Component default markup (optional) - ┃ ┃ ┃ β”— πŸ“œ ComponentName.php <=== Component class file - ┃ β”— πŸ“œ Plugin.php ``` diff --git a/plugin-localization.md b/plugin-localization.md index a8b6c083..47f8ffd8 100644 --- a/plugin-localization.md +++ b/plugin-localization.md @@ -13,14 +13,13 @@ Plugins can have localization files in the **lang** subdirectory of the plugin d Below is an example of the plugin's lang directory: -``` +```css πŸ“‚ plugins β”— πŸ“‚ acme β”— πŸ“‚ todo <=== Plugin directory β”— πŸ“‚ lang <=== Localization directory ┣ πŸ“‚ en <=== Language directory ┃ β”— πŸ“œ lang.php <=== Localization file - ┃ β”— πŸ“‚ fr β”— πŸ“œ lang.php ``` @@ -57,8 +56,8 @@ 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 +```css +πŸ“‚ lang <=== App localization directory β”— πŸ“‚ en <=== Language directory β”— πŸ“‚ acme <=== Plugin / Module directory β”— πŸ“‚ blog <===^ diff --git a/plugin-settings.md b/plugin-settings.md index bd773295..96664540 100644 --- a/plugin-settings.md +++ b/plugin-settings.md @@ -40,14 +40,13 @@ 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 +```css +πŸ“‚ plugins β”— πŸ“‚ acme β”— πŸ“‚ demo β”— πŸ“‚ models ┣ πŸ“‚ settings <=== Model files directory ┃ β”— πŸ“œ fields.yaml <=== Model form fields - ┃ β”— πŸ“œ Settings.php <=== Model script ``` diff --git a/plugin-updates.md b/plugin-updates.md index 13d7e4a0..5aeadff1 100644 --- a/plugin-updates.md +++ b/plugin-updates.md @@ -14,15 +14,14 @@ It is good practice for plugins to maintain a change log that documents any chan The change log is stored in a YAML file called `version.yaml` inside the **/updates** directory of a plugin, which co-exists with migration and seed files. This example displays a typical plugin updates directory structure: -``` -πŸ“¦ plugins +```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 ``` diff --git a/themes-development.md b/themes-development.md index 61d6235c..0cab266d 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 + β”— πŸ“œ 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 + β”— πŸ“œ 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 + β”— πŸ“œ 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,13 +187,12 @@ Themes can provide backend localization keys through files placed in the **lang* Below is an example of the theme's lang directory: -``` -πŸ“¦themes +```css +πŸ“‚themes β”— πŸ“‚ example-theme <-- Theme directory β”— πŸ“‚ lang <-- Localization directory ┣ πŸ“‚ en <-- Specific locale directory ┃ β”— πŸ“œ lang.php <-- Localization file - ┃ β”— πŸ“‚ fr β”— πŸ“œ lang.php ``` From e59d02e8290b6227641f436c19894a3602dc97c5 Mon Sep 17 00:00:00 2001 From: Web-VPF Date: Mon, 3 Jan 2022 17:43:53 +0200 Subject: [PATCH 6/9] Improving structure diagrams --- cms-themes.md | 64 +++++++++++++++++++++++++-------------------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/cms-themes.md b/cms-themes.md index 0dec573b..e77ce62a 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. From 0e7555502ac3ae6d50da06316d3818248461f5a7 Mon Sep 17 00:00:00 2001 From: Web-VPF Date: Mon, 3 Jan 2022 18:40:18 +0200 Subject: [PATCH 7/9] Improving structure diagrams --- cms-themes.md | 1 - database-model.md | 2 +- plugin-registration.md | 146 ++++++++++++++++++++--------------------- 3 files changed, 74 insertions(+), 75 deletions(-) diff --git a/cms-themes.md b/cms-themes.md index e77ce62a..7bccbe62 100644 --- a/cms-themes.md +++ b/cms-themes.md @@ -84,7 +84,6 @@ Winter supports single level subdirectories for **pages**, **partials**, **layou ┃ β”— πŸ“œ category.htm ┣ πŸ“‚ partials ┃ ┣ πŸ“œ sidebar.htm - ┃ ┃ ┃ β”— πŸ“‚ blog <=== Subdirectory ┃ β”— πŸ“œ category-list.htm ┣ πŸ“‚ content diff --git a/database-model.md b/database-model.md index a6a8360c..089efb4b 100644 --- a/database-model.md +++ b/database-model.md @@ -34,7 +34,7 @@ Model classes reside in the **models** subdirectory of a plugin directory. An ex ┃ ┃ ┣ πŸ“œ columns.yaml <=== Model config files ┃ ┃ β”— πŸ“œ fields.yaml <==^ ┃ β”— πŸ“œ User.php <=== Model class - β”— Plugin.php + β”— πŸ“œ 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-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 */ ``` From a0ed2d57839a3f4a77212e89895f1ded589e53de Mon Sep 17 00:00:00 2001 From: Luke Towers Date: Mon, 3 Jan 2022 15:30:50 -0600 Subject: [PATCH 8/9] Update cms-themes.md --- cms-themes.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/cms-themes.md b/cms-themes.md index 7bccbe62..5492c0fd 100644 --- a/cms-themes.md +++ b/cms-themes.md @@ -86,13 +86,10 @@ Winter supports single level subdirectories for **pages**, **partials**, **layou ┃ ┣ πŸ“œ sidebar.htm ┃ β”— πŸ“‚ blog <=== Subdirectory ┃ β”— πŸ“œ category-list.htm - ┣ πŸ“‚ content - ┃ ┣ πŸ“œ footer-contacts.txt - ┃ β”— πŸ“‚ home <=== Subdirectory - ┃ β”— πŸ“œ intro.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: From 9bdabe0ce2c743abaa899c0d28178f48d773af44 Mon Sep 17 00:00:00 2001 From: Luke Towers Date: Mon, 3 Jan 2022 15:32:30 -0600 Subject: [PATCH 9/9] Update themes-development.md --- themes-development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/themes-development.md b/themes-development.md index 0cab266d..eeb01066 100644 --- a/themes-development.md +++ b/themes-development.md @@ -188,7 +188,7 @@ Themes can provide backend localization keys through files placed in the **lang* Below is an example of the theme's lang directory: ```css -πŸ“‚themes +πŸ“‚ themes β”— πŸ“‚ example-theme <-- Theme directory β”— πŸ“‚ lang <-- Localization directory ┣ πŸ“‚ en <-- Specific locale directory