Merge pull request #67 from oveleon/3.0

3.0

README.md

@@ -17,6 +17,8 @@ This plugin is designed to simplify theme customizations without the need of man
 - Passing variables to the template
     - Formatting output using predefined methods or your own
 - Import / Export
+    - Automatic import of configurations from third-party bundles (Bundle configurations) [![new](https://img.shields.io/badge/-new-brightgreen?style=flat-square)](#contao-component-style-manager)
+    - Partial import [![new](https://img.shields.io/badge/-new-brightgreen?style=flat-square)](#contao-component-style-manager)
 - Available for
     - Layouts
     - Pages
@@ -51,5 +53,7 @@ composer require oveleon/contao-component-style-manager
 ## Documentation
 - [Configuration](docs/CONFIGURATION.md)
 - [Use template variables](docs/TEMPLATE_VARIABLES.md)
-- [Extend and support other extensions](docs/SUPPORT.md)
+- [Support own extensions](docs/SUPPORT.md)
 - [Import / Export](docs/IMPORT_EXPORT.md)
+- [Bundle-Configurations](docs/BUNDLE_CONFIG.md)
+- [Migration](docs/MIGRATE.md)

UPGRADE.md

@@ -0,0 +1,12 @@
+# Version 2.* to 3.0
+## Storage adjustment
+### Migration
+If you update from version 2 to version 3, you have to perform a migration, otherwise the records will break and cannot be reassigned in the StyleManager widget. If the StyleManager widget is already called before running a migration, selected properties are inserted into the DCA's CSS class field to avoid errors.
+
+[Learn more about migration](docs/MIGRATE.md)
+
+## Restructure of the Bundle
+### Namespaces
+Due to the restructuring of the bundle, the namespaces have to be adjusted, if the StyleManager was used for vendor DCAs.
+
+[Learn more about StyleManager Support](docs/SUPPORT.md)

composer.json

@@ -18,7 +18,10 @@
     }
   ],
   "require":{
-    "contao/core-bundle":"^4.4"
+    "php":">=7.4",
+    "ext-json": "*",
+    "ext-dom": "*",
+    "contao/core-bundle":">=4.13"
   },
   "require-dev": {
     "contao/manager-plugin": "^2.0"
@@ -44,7 +47,7 @@
   },
   "extra":{
     "branch-alias": {
-      "dev-master": "2.5.x-dev"
+      "dev-master": "3.0.x-dev"
     },
     "contao-manager-plugin": "Oveleon\\ContaoComponentStyleManager\\ContaoManager\\Plugin"
   }

docs/BUNDLE_CONFIG.md

@@ -0,0 +1,20 @@
+## Documentation
+- [Configuration](CONFIGURATION.md)
+- [Use template variables](TEMPLATE_VARIABLES.md)
+- [Support own extensions](SUPPORT.md)
+- [Import / Export](IMPORT_EXPORT.md)
+- __[Bundle-Configurations](BUNDLE_CONFIG.md)__
+- [Migration](docs/MIGRATE.md)
+
+---
+
+# Bundle-Configurations
+Instead of the import function, from version 3, configurations can be automatically provided by other bundles.  For the deployment, a configuration file, which can be exported via the StyleManager, must be stored under `contao/templates` of the bundle. The file needs to start with `style-manager-`. If the automatic import of these configuration files is not prevented (allowed by default), archives and CSS groups are automatically added to the defined areas.
+
+To prevent dynamic configurations from being read in, you can make the following configuration:
+```yaml
+# config.yaml
+contao_component_style_manager:
+    use_bundle_config: false
+```
+

docs/CONFIGURATION.md

@@ -1,22 +1,44 @@
-# Manage Categories:
-### Fields:
-- `Title`: The title of the category, which is displayed above the defined style groups in the backend
-- `Idenfifier`: A unique value for retrieving the classes in the template
-- `Group-Idenfifier`: In this field you can specify an alias that combines categories with the same alias and displays them as tabs in the backend.
-- `Sort-Index`: This field is used to determine the order of the categories in the backend
-
-#### Example backend view of combined categories using `Group-Idenfifier`:
+## Documentation
+- __[Configuration](CONFIGURATION.md)__
+- [Use template variables](TEMPLATE_VARIABLES.md)
+- [Support own extensions](SUPPORT.md)
+- [Import / Export](IMPORT_EXPORT.md)
+- [Bundle-Configurations](BUNDLE_CONFIG.md)
+- [Migration](docs/MIGRATE.md)
+
+---
+
+After the installation, a new navigation item "StyleManager" is displayed in the backend to create and edit the dataset of categories and CSS groups.
+
+# Categories:
+
+Categories can be considered as archives and form a logical separation of CSS groups. A special feature for the display in the backend, is the merging of these categories via the field `Group-Identifier`. This field can be filled freely to display categories with the same group identifier bundled as tab navigation in the widget.
+
+| Field              | Description                                                                                                                  |
+|--------------------|------------------------------------------------------------------------------------------------------------------------------|
+| `Title`            | The title of the category.                                                                                                   |
+| `Idenfifier`       | A unique value. This value must be used to retrieve the template variables.                                                  |
+| `Group-Idenfifier` | In this field you can specify an alias that combines categories with the same alias and displays them as tabs in the widget. |
+| `Sort-Index`       | This field is used to determine the order of the categories in the widget.                                                   |
+
+### Example backend view of combined categories using `Group-Idenfifier`:
 ![Manage Categories: Image 3](https://www.oveleon.de/share/github-assets/contao-component-style-manager/2.0/combined-groups.png)
 
 <br/>
 
-# Manage CSS-Groups:
-### Fields:
-- `Alias`: Define an alias with which the group can be accessed. This is only required for passing on to the template.
-- `Add search field`: Use of chosen for a search field within the select box
-- `Use as template variable`: This field declares whether this group is set in the class attribute of the corresponding element or passed to the template.
-- `CSS class`: To further customize the display of the backend fields, you can enter a selection of predefined CSS classes. (long, clr, separator)
-> All other fields should be self-explanatory
+# CSS-Groups:
+
+If a category has been created, any CSS groups can be created within it. A CSS group represents the actual selection of selectable options that are made available to the editor for the various areas (articles, content elements, ...).
+
+A special feature is that CSS groups can also be used as template variables via the `Use as template variable` field. In this case, the selected options are not automatically made available as a CSS class, but must be accepted manually in the template. [Learn more about template variables](TEMPLATE_VARIABLES.md).
+
+| Field                      | Description                                                                                                                                                                                            |
+|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `Alias`                    | A unique value. This value must be used to retrieve the template variables.                                                                                                                            |
+| `Add search field`         | Activates the search within the widget for this CSS group. This setting is recommended only for a larger set of options.                                                                               |
+| `Use as template variable` | This field defines the type of usage. When this field is checked, the variable is passed to the template instead of being used as a CSS class. [More about template variables](TEMPLATE_VARIABLES.md). |
+| `CSS class`                | To further customize the display of the backend fields, you can specify a selection of predefined CSS classes. (long, clr, separator)                                                                  |
+| `...`                      | All other fields should be self-explanatory                                                                                                                                                            |
 
-#### Example css group:
+### Example css group:
 ![Manage Groups: Image 1](https://www.oveleon.de/share/github-assets/contao-component-style-manager/2.0/groups-edit.png)

docs/IMPORT_EXPORT.md

@@ -1,6 +1,19 @@
-## Import / Export
+## Documentation
+- [Configuration](CONFIGURATION.md)
+- [Use template variables](TEMPLATE_VARIABLES.md)
+- [Support own extensions](SUPPORT.md)
+- __[Import / Export](IMPORT_EXPORT.md)__
+- [Bundle-Configurations](BUNDLE_CONFIG.md)
+- [Migration](docs/MIGRATE.md)
+
+---
+
+# Import / Export
 To fill projects with a default setting, the Import and Export functions are available. 
 
 When importing, the categories as well as the CSS groups are only added additively. This allows CSS classes to be added to the actual project without being deleted after an import. 
 
 > Please note that the import completes the records by the identifier (categories) and the alias (CSS groups). So if the aliases are changed in the current project, they are not overwritten / added, but a new group is created after the import.
+
+### Prepare dynamic configurations
+See also: [Bundle-Configurations](BUNDLE_CONFIG.md)

docs/MIGRATE.md

@@ -0,0 +1,21 @@
+## Documentation
+- [Configuration](CONFIGURATION.md)
+- [Use template variables](TEMPLATE_VARIABLES.md)
+- [Support own extensions](SUPPORT.md)
+- [Import / Export](IMPORT_EXPORT.md)
+- [Bundle-Configurations](BUNDLE_CONFIG.md)
+- __[Migration](docs/MIGRATE.md)__
+
+---
+
+# Migration
+
+#### Migrate from version 2 to 3
+Bundle configurations were added with version 3. This makes it necessary to migrate the StyleManager dataset. If only standard Contao tables were used and the StyleManager was not added to other / own database tables, calling the install tool is sufficient. Starting with Contao 5, the migration has to be confirmed manually by the Contao Manager. 
+
+If the StyleManager was used for other / own database tables, these tables must be migrated manually using the following command:
+
+```shell
+# vendor/bin/
+$ php contao-console contao:stylemanager:object-conversion tl_mytable
+```