Merge pull request #33 from oveleon/develop

Develop
oveleon · Sep 4, 2020 · 866d4e3 · 866d4e3
2 parents 0a150c9 + 568732a
commit 866d4e3
Show file tree

Hide file tree

Showing 20 changed files with 300 additions and 329 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# Contao Component Style Manager
+# Contao Component StyleManager
 [![maintained](https://img.shields.io/badge/oveleon-maintained-83aa0e?style=flat-square&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABMAAAAUCAYAAABvVQZ0AAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAA/xpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuNi1jMTQ1IDc5LjE2MzQ5OSwgMjAxOC8wOC8xMy0xNjo0MDoyMiAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wTU09Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9tbS8iIHhtbG5zOnN0UmVmPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvc1R5cGUvUmVzb3VyY2VSZWYjIiB4bWxuczp4bXA9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC8iIHhtbG5zOmRjPSJodHRwOi8vcHVybC5vcmcvZGMvZWxlbWVudHMvMS4xLyIgeG1wTU06T3JpZ2luYWxEb2N1bWVudElEPSJ1dWlkOjVEMjA4OTI0OTNCRkRCMTE5MTRBODU5MEQzMTUwOEM4IiB4bXBNTTpEb2N1bWVudElEPSJ4bXAuZGlkOjM5MjZBNjQzMzZFQjExRUFBMTdBQkNFQTAxNjg2RDI4IiB4bXBNTTpJbnN0YW5jZUlEPSJ4bXAuaWlkOjM5MjZBNjQyMzZFQjExRUFBMTdBQkNFQTAxNjg2RDI4IiB4bXA6Q3JlYXRvclRvb2w9IkFkb2JlIElsbHVzdHJhdG9yIENTNiAoV2luZG93cykiPiA8eG1wTU06RGVyaXZlZEZyb20gc3RSZWY6aW5zdGFuY2VJRD0idXVpZDplMDhkZDhmZC1mOTA4LTQ5YzItYWMwZC00OGE3YTI4ODc2YWEiIHN0UmVmOmRvY3VtZW50SUQ9InhtcC5kaWQ6OTA2RDhGOENERUQxRTgxMTgyMjVBMzBGQ0NBNjE4RUQiLz4gPGRjOnRpdGxlPiA8cmRmOkFsdD4gPHJkZjpsaSB4bWw6bGFuZz0ieC1kZWZhdWx0Ij5Mb2dvX292ZWxlb25fWmVpY2hlbl9yejwvcmRmOmxpPiA8L3JkZjpBbHQ+IDwvZGM6dGl0bGU+IDwvcmRmOkRlc2NyaXB0aW9uPiA8L3JkZjpSREY+IDwveDp4bXBtZXRhPiA8P3hwYWNrZXQgZW5kPSJyIj8+P8iBTQAAAbFJREFUeNqU08srRFEcB/BromGGaJRHKSIaYfIm7JRSsvHIyuM/wMorNeEfUMqKnbKwU2TBwpSUSWYWFmSBDKWmWcgwcX2Pvrc5HXfuXL/6zD2P3z2Puedouq5rilG40JPxAuUmeX84tGTkwyXsghOWYQmKoFazExzVDXFIgEeazcPV9TCnzGplRiHMl7KgCWYghy9vQAasMEfkTqQarJ9JFWw0YlhJFv2rUv8tdKiDhTib0eiHQyhOsR2xyjlp0BF5MBELdr6WohE++X6raBOz6PwWCfiCOLzDN8sRGICYyfdrgBA8Q2kmfnzQJirghlw+XZANUQ5qFmHY52R9/9lWCXjBpbRPcaubDhtHsRoOuN1reAO/1H/PpzfdaqrggzOLK7YFD6zPMqeL9at0gwWZuKa0i3hkuZf1E6tteqEZnmCRbZVwxPIOn3V83litaogzbrPuhDOIwbyUd8q8SavBOpl0rnxROadFugkFVoOJAx1h4rRJvw9e2b9u3ACrY9ENAZaD/L/E0aiHMbbfQc3v7bFxWAchqptHAAqN3HQrM0JcsXFohzzexWPYk5N+BBgAix5VyvzRZbwAAAAASUVORK5CYII=)](https://www.oveleon.de)
 [![license](https://img.shields.io/github/license/oveleon/contao-component-style-manager?color=83aa0e&style=flat-square)](https://github.com/oveleon/contao-component-style-manager/blob/master/LICENSE)
 [![stable](https://img.shields.io/badge/stable-master-83aa0e?style=flat-square)](https://github.com/oveleon/contao-component-style-manager/tree/master)
@@ -10,13 +10,13 @@ Allows you to easily manage your own CSS classes as groups provided in layouts,
 This plugin is designed to simplify theme customizations without the need of manually adding classes or creating new layouts.
 
 ## Overview
-- Many possibilities of use (grids, animations, content properties, ...)
+- Many possibilities of use (e.g. grids, animations, content properties, ...)
 - Clear representation in the backend
 - Categories and Groups 
     - Combine and output as tabs
 - Passing variables to the template
     - Formatting output using predefined methods or your own
-- Import / Export [![new](https://img.shields.io/badge/-new-83aa0e?style=flat-square)](#import--export)
+- Import / Export
 - Available for
     - Layouts
     - Pages
@@ -27,245 +27,29 @@ This plugin is designed to simplify theme customizations without the need of man
     - Form-Fields
     - News
     - Events
-    - Third-Party DCA [![new](https://img.shields.io/badge/-new-83aa0e?style=flat-square)](#support-third-party-dca)
+    - Third-Party DCA
 - Third-Party plugin support
     - Rocksolid Custom Elements 
 
-
-## Install
-```
-$ composer require oveleon/contao-component-style-manager
-```
-
-## 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`:
-![Manage Categories: Image 3](https://www.oveleon.de/share/github-assets/contao-component-style-manager/2.0/combined-groups.png)
-
-## 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, seperator)
-> All other fields should be self-explanatory
-
-##### Example css group:
-![Manage Groups: Image 1](https://www.oveleon.de/share/github-assets/contao-component-style-manager/2.0/groups-edit.png)
-
-## Passing css group variables to a template:
-If the checkbox "Use as template variable" is set, these are not automatically passed to the class of the corresponding element but are available in the template.
-To access the variables, we can access the corresponding class collection via the `styleManager` object.
-
-#### There are two ways to receive the values:
-- **get**: Return selected CSS classes of a category or a specific group
-    - Parameter:
-        - `identifier: string`: Category identifier
-        - `groups: null|array` (optional): Group aliases
-- **prepare** + **format**: Different from the get method, you can specify your own output format and a predefined or custom method to validate the output
-    - `prepare`-Parameter: 
-        - `identifier: string`: Category identifier
-        - `groups: null|array` (optional): Group aliases
-    - `format`-Parameter:
-        - `format: string`: The format parameter must contain a format string valid for `sprintf` (PHP: [sprintf](https://www.php.net/manual/de/function.sprintf.php))).
-        - `method: string` (optional): Name of Method
-
-#### Predefined methods
-- `json`: Returns a JSON object using the alias and value (e.g. `{"alias1":"my-class-1","alias2":"my-class-2"}`)
-
-#### Register your own method per Hook
-To set up a custom method for validating the values, the hook `styleManagerFormatMethod` can be registered.
-
 <br/>
 
-> Let us know if you know of any other useful methods that could be included in the standard 👋
-
-#### Examples:
-##### Using `get`-Method
-```php
-// Return of all selected CSS classes of a category
-$this->styleManager->get('myCategoryIdentifier');
-
-// Return of all selected CSS classes in specific groups of a category
-$this->styleManager->get('myCategoryIdentifier', ['alias1', 'alias2']);
-```
-
-##### Using `prepare` + `format`-Method
-```php
-// Return of all selected CSS classes of a category with class attribute
-$this->styleManager->prepare('myCategoryIdentifier')->format('class="%s"');
-
-// Often additional classes are appended to an existing class attribute. In this case, unnecessary if-else statements can be avoided.
-$this->styleManager->prepare('myCategoryIdentifier')->format(' %s');
-
-// Return of all selected CSS classes in specific groups of a category as json with data attribute
-$this->styleManager->prepare('myCategoryIdentifier', ['alias1'])->format("data-slider='%s'", 'json');
-```
-
-##### Example of use
-```
-<div class="<?=$this->styleManager->get('myCategoryIdentifier')?>">...</div>
-  or
-<div <?=$this->styleManager->prepare('myCategoryIdentifier')->format("class="%s")?>>...</div>
-
-<div class="my-class-1<?=$this->styleManager->prepare('myCategoryIdentifier')->format(' %s')?>">...</div>
-
-<div data-slider="<?=$this->styleManager->prepare('myCategoryIdentifier', ['slider-alias'])->format("data-slider='%s'", 'json')?>">...</div>
-```
-
-##### Backend view
-![Passing Variables: Image 1](https://www.oveleon.de/share/github-assets/contao-component-style-manager/2.0/template-vars-list.png)
-
-## 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. 
+<div align="center">
+    <img src="https://www.oveleon.de/share/github-assets/contao-component-style-manager/2.0/combined-groups.png">
+    <p><i>Example backend view</i></p>
+</div>
 
-> 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.
-
-## Support Third-Party DCA 
-If you have your own DCA that you want to make available for the StyleManager, you can do this in **three to four steps**.
-As in Contao itself, the DCA must contain a field where the CSS classes can be stored. The following fields are already included:
-
-- `cssID` (multiple field)
-- `cssClass` (single field)
-- `class` (single field)
-- `attributes` (multiple field)
-
-> Please note that the field size must be observed!
-
-<details>
-  <summary><b>1.</b> Extending the <b>CSS group fields</b> in tl_style_manager DCA</summary>
-
-```php
-// Extend the default palette
-Contao\CoreBundle\DataContainer\PaletteManipulator::create()
-    ->addField(array('extendMyDca'), 'publish_legend', Contao\CoreBundle\DataContainer\PaletteManipulator::POSITION_APPEND)
-    ->applyToPalette('default', 'tl_style_manager');
-
-// Extend fields
-$GLOBALS['TL_DCA']['tl_style_manager']['fields']['extendMyDca'] = array
-(
-    'label'                   => &$GLOBALS['TL_LANG']['tl_style_manager']['extendMyDca'],
-    'exclude'                 => true,
-    'filter'                  => true,
-    'inputType'               => 'checkbox',
-    'eval'                    => array('tl_class'=>'clr'),
-    'sql'                     => "char(1) NOT NULL default ''"
-);
-```
-</details>
-
-<details>
-  <summary><b>2.</b> Adding the styleManager <b>legend and field</b> to your DCA</summary>
-
-```php
-// Extend the palette
-$palette = Contao\CoreBundle\DataContainer\PaletteManipulator::create()
-    ->addLegend('style_manager_legend', 'expert_legend', Contao\CoreBundle\DataContainer\PaletteManipulator::POSITION_BEFORE)
-    ->addField(array('styleManager'), 'style_manager_legend', Contao\CoreBundle\DataContainer\PaletteManipulator::POSITION_APPEND)
-    ->applyToPalette('default', 'tl_mydca');
-
-// Extend fields
-$GLOBALS['TL_DCA']['tl_mydca']['fields']['styleManager'] = array
-(
-    'label'                   => &$GLOBALS['TL_LANG']['tl_mydca']['styleManager'],
-    'exclude'                 => true,
-    'inputType'               => 'stylemanager',
-    'eval'                    => array('tl_class'=>'clr stylemanager'),
-    'sql'                     => "blob NULL"
-);
-
-// Adding callback methods for the CSS-Class field (cssID, cssClass, class or attributes)
-$GLOBALS['TL_DCA']['tl_mydca']['fields']['attributes']['load_callback'][] = array('\\Oveleon\\ContaoComponentStyleManager\\StyleManager', 'onLoad');
-$GLOBALS['TL_DCA']['tl_mydca']['fields']['attributes']['save_callback'][] = array('\\Oveleon\\ContaoComponentStyleManager\\StyleManager', 'onSave');
-```
-</details>
-
-<details>
-  <summary><b>3.</b> Provide the StyleManager the new DCA</summary>
-
-To get the selected CSS groups for the new DCA and to provide them in the backend, it is necessary to provide the StyleManager with the new DCA. In order to make this possible the **styleManagerFindByTable**-Hook is prepared.
-
-```php
-// HOOK
-$GLOBALS['TL_HOOKS']['styleManagerFindByTable'][] = array('\\Namespace\\Class', 'onFindByTable');
-```
-
-```php
-use Oveleon\ContaoComponentStyleManager\StyleManagerModel;
-
-/**
- * Find css groups using their table
- *
- * @param string $strTable
- * @param array $arrOptions
- *
- * @return \Model\Collection|StyleManagerModel[]|StyleManagerModel|null A collection of models or null if there are no css groups
- */
-public function onFindByTable($strTable, $arrOptions)
-{
-    if($strTable === 'tl_mydca')
-    {
-        return StyleManagerModel::findBy(array('extendMyDca=1'), null, $arrOptions);
-    }
-
-    return null;
-}
-```
-</details>
-
-<details>
-  <summary><b>4.</b> <b>Skip fields</b> that should not be displayed in the Backend Select-Widget</summary>
-
-📌 _This step is only necessary for tables with different types like tl_content, tl_module or tl_form_fields_
+## Install
 
-If the DCA provides several types, which can be selected individually under the CSS groups, a further check has to take place to display them only for certain types.
+#### Installation via Contao Manager
+Search for `oveleon/contao-component-style-manager` in the Contao Manager and add it to your installation. Finally, update the packages.
 
-```php
-// HOOK
-$GLOBALS['TL_HOOKS']['styleManagerSkipField'][] = array('\\Namespace\\Class', 'onSkipField');
+#### Manual installation
 ```
-
-```php
-/**
- * StyleManager Support
- *
- * If the field is not selected in the CSS group, it is skipped
- *
- * @param $objStyleGroups
- * @param $objWidget
- *
- * @return bool Skip field
- */
-public function onSkipField($objStyleGroups, $objWidget)
-{
-    if(!!$objStyleGroups->extendMyDca && $objWidget->strTable === 'tl_mydca')
-    {
-        $arrDcaTypes = \StringUtil::deserialize($objStyleGroups->dcaTypes);
-
-        if($arrDcaTypes !== null && !in_array($objWidget->activeRecord->type, $arrDcaTypes))
-        {
-            return true;
-        }
-    }
-
-    return false;
-}
+$ composer require oveleon/contao-component-style-manager
 ```
-</details>
 
-## Support Rocksolid Custom Elements
-see: [Rocksolid Custom Elements](https://github.com/madeyourday/contao-rocksolid-custom-elements)
-
-Use the callback function `onloadCallback` in your custom element configuration and reference the following function:
-```
- 'onloadCallback' => array(
-      array('Oveleon\ContaoComponentStyleManager\Support', 'extendRockSolidCustomElementsPalettes')
-  )
-```
+## Documentation
+- [Configuration](docs/CONFIGURATION.md)
+- [Use template variables](docs/TEMPLATE_VARIABLES.md)
+- [Extend and support other extensions](docs/SUPPORT.md)
+- [Import / Export](docs/IMPORT_EXPORT.md)
diff --git a/composer.json b/composer.json
@@ -10,14 +10,16 @@
       "name":"Oveleon",
       "homepage":"https://oveleon.de/",
       "role":"Developer"
+    },
+    {
+      "name":"Daniele Sciannimanica",
+      "homepage":"https://github.com/doishub",
+      "role":"Developer"
     }
   ],
   "require":{
     "contao/core-bundle":"^4.4"
   },
-  "suggest": {
-    "contao-thememanager/core": "Contao ThemeManager"
-  },
   "require-dev": {
     "contao/manager-plugin": "^2.0"
   },
@@ -41,6 +43,9 @@
     ]
   },
   "extra":{
+    "branch-alias": {
+      "dev-master": "2.4.x-dev"
+    },
     "contao-manager-plugin": "Oveleon\\ContaoComponentStyleManager\\ContaoManager\\Plugin"
   }
 }
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
@@ -0,0 +1,22 @@
+# 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`:
+![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, seperator)
+> All other fields should be self-explanatory
+
+#### Example css group:
+![Manage Groups: Image 1](https://www.oveleon.de/share/github-assets/contao-component-style-manager/2.0/groups-edit.png)
diff --git a/docs/IMPORT_EXPORT.md b/docs/IMPORT_EXPORT.md
@@ -0,0 +1,6 @@
+## 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.