From 7b12e55527afbe3542c5727f0eea210e3602a485 Mon Sep 17 00:00:00 2001 From: sophie-mulard Date: Wed, 5 Apr 2023 16:21:54 +0200 Subject: [PATCH] Update documentation --- README.md | 143 +++++++++--- Resources/doc/custom_field_type.md | 210 ++++++++++++++++++ Resources/doc/elements.md | 46 ++++ Resources/doc/entities.md | 174 ++++++++++++++- Resources/doc/export.md | 11 +- Resources/doc/field_types.md | 66 +++--- Resources/doc/import.md | 127 +++++++---- .../import/Content/standalone_content.yaml | 47 ++-- Resources/doc/import/Page/custom_page.yaml | 67 ++++-- Resources/doc/tools.md | 38 +++- Resources/doc/usage.md | 78 +++++-- 11 files changed, 834 insertions(+), 173 deletions(-) create mode 100644 Resources/doc/custom_field_type.md create mode 100644 Resources/doc/elements.md diff --git a/README.md b/README.md index 6b88708d..fb96d73c 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,49 @@ # Sherlockode AdvancedContentBundle +---- + +[ ![](https://img.shields.io/packagist/l/sherlockode/advanced-content-bundle)](https://packagist.org/packages/sherlockode/advanced-content-bundle "License") +[ ![](https://img.shields.io/packagist/v/sherlockode/advanced-content-bundle)](https://packagist.org/packages/sherlockode/advanced-content-bundle "Version") +[ ![](https://poser.pugx.org/sherlockode/advanced-content-bundle/downloads)](https://packagist.org/packages/sherlockode/advanced-content-bundle "Total Downloads") +[ ![Support](https://img.shields.io/badge/support-contact%20author-blue])](https://www.sherlockode.fr/contactez-nous/?utm_source=github&utm_medium=referral&utm_campaign=plugins_acb) + +![image](https://user-images.githubusercontent.com/22291441/230099691-0fad8407-9883-4f0c-bdbd-9d6a8245a8db.png) + +## Table of Content + +---- + +* [Overview](#overview) +* [Installation](#installation) +* [Terminology](#terminology) +* [Configuration](#configuration) + * [Assets](#assets) + * [Twig](#twig) + * [Entities](#entities) + * [Upload](#upload-configuration) + * [Routing](#routing) +* [Advanced documentation](#advanced-documentation) +* [Dependencies](#dependencies) +* [License](#license) +* [Contact](#contact) + +# Overview + +---- + This bundle provides advanced CMS features for end user contribution. -Users are able to create pages with standard and custom building blocks. -These blocks are used by back-office contributors to create actual contents without coding after the setup is done. +Users can build their website pages quickly and effortlessly thanks to our intuitive interface. +Several standard elements are included, such as text block, heading, image, image carousel, video player, ... +Responsive layouts can be shaped as needed with row and column elements. +Drafts are saved automatically and it's easy to rollback to a previous version. +Custom elements can be added simply with a few lines of code. -[![Total Downloads](https://poser.pugx.org/sherlockode/advanced-content-bundle/downloads)](https://packagist.org/packages/sherlockode/advanced-content-bundle) -[![Latest Stable Version](https://poser.pugx.org/sherlockode/advanced-content-bundle/v/stable)](https://packagist.org/packages/sherlockode/advanced-content-bundle) +# Installation -Installation ------------- +---- -### Get the bundle using composer +## Get the bundle using composer The best way to install this bundle is to rely on [Composer](https://getcomposer.org/): @@ -19,7 +51,7 @@ The best way to install this bundle is to rely on [Composer](https://getcomposer $ composer require sherlockode/advanced-content-bundle ``` -### Enable the bundle +## Enable the bundle Register the bundle in your application's kernel: @@ -34,10 +66,44 @@ return [ ``` -Configuration -------------- +# Terminology + +---- + +## Entities + +---- + +A Page is linked to a PageMeta and to a Content.\ +It can optionally be linked to a PageType too. + +Content can be used independently as well.\ +For example, if several Pages include the same layer, you can create a single Content with this layer and then include the Content within the Pages.\ +As a result, if the layer has to change, you only have to change a single Content instead of all the Pages. + +You can also create a Content to make some parts of your website dynamic.\ +For example, you can create a Content which includes your footer links. This way you don't have to change your template everytime the footer has to be updated. + +Pages, PageMetas and Contents are all versionable, hence the PageVersion, PageMetaVersion and ContentVersion entities. + +Finally, if you enabled the scope management, you will be able to associate each Page and Content to one or multiple Scopes. + +## Elements + +---- + +Content data is an array of Elements.\ +Elements can either be a Layout or a FieldType.\ +Layouts include rows and columns.\ +FieldTypes include the field types we defined (text, image, video, ...) and you custom field types. -### Assets +# Configuration + +---- + +## Assets + +---- jQuery and jQuery UI are mandatory and should be required in `package.json` in order for the assets build to work. @@ -83,7 +149,9 @@ composer require symfony/webpack-encore-bundle {{ encore_entry_script_tags('app') }} ``` -### Twig +## Twig + +---- The bundle automatically uses Bootstrap 5 (or Bootstrap 4 for Symfony < 5.3) as the base form theme for all forms. @@ -96,9 +164,11 @@ you can override the bundle's base form theme file `Form/base_theme.html.twig` {% extends 'form_div_layout.html.twig' %} ``` -### Entities +## Entities + +---- -`SherlockodeAdvancedContentBundle` provides 4 entity models : Content, PageType, Page, PageMeta. +`SherlockodeAdvancedContentBundle` provides 8 entity models. To be able to use them, you need to create your own entities, see examples in the [doc](Resources/doc/entities.md), and fill the corresponding configuration : @@ -108,13 +178,18 @@ sherlockode_advanced_content: entity_class: content: App\Entity\Content content_version: App\Entity\ContentVersion - page_type: App\Entity\PageType page: App\Entity\Page page_meta: App\Entity\PageMeta + page_meta_version: App\Entity\PageMetaVersion + page_type: App\Entity\PageType + page_version: App\Entity\PageVersion + scope: App\Entity\Scope ``` -### Upload configuration +## Upload configuration + +---- If you want to use the `Image` or `File` field type, you need to configure the directory in which the images will be saved. @@ -131,17 +206,20 @@ sherlockode_advanced_content: uri_prefix: /uploads/acb_images ``` -### Routing +## Routing + +---- The routing is split into several files for better import rules. -* tools.xml : Routes for tooling pages, like import/export * content.xml : Utility routes for editing contents -* page_meta.xml : Utility routes for editing pages -* page.xml : basic CRUD routes for Pages (demo purpose) * content_crud.xml : basic CRUD routes for Content (demo purpose) +* page.xml : Utility routes for editing pages +* page_crud.xml : basic CRUD routes for Pages (demo purpose) +* scope_crud.xml : basic CRUD routes for Scopes (demo purpose) +* tools.xml : Routes for tooling pages, like import/export, Page Type CRUD * all.xml : includes all the above -* base.xml : includes tools.xml, content.xml and page_meta.xml +* base.xml : includes tools.xml, content.xml and page.xml The base.xml file is sufficient if you plan to manage all your CRUD operations in custom controllers (like if you use an external admin system). @@ -155,22 +233,37 @@ sherlockode_advanced_content: # resource: '@SherlockodeAdvancedContentBundle/Resources/config/routing/all.xml' ``` -## Advanced Documentation +# Advanced Documentation + +---- - [Entities](Resources/doc/entities.md) -- [Field Types](Resources/doc/field_types.md) +- [Elements](Resources/doc/elements.md) - [Tools](Resources/doc/tools.md) - [Import](Resources/doc/import.md) - [Export](Resources/doc/export.md) - [Usage](Resources/doc/usage.md) -## Dependencies + +# Dependencies + +---- This bundle is compatible with webpack. jQuery library is mandatory. jQuery ui sortable is advised but not required. Some field types, such as the image carousel, use Bootstrap 5 for their display. -## License + +# License + +---- This bundle is under the MIT license. Check the details in the [dedicated file](LICENSE) + + +# Contact + +---- + +If you want to contact us, the best way is to fill the form on [our website](https://www.sherlockode.fr/contactez-nous/?utm_source=github&utm_medium=referral&utm_campaign=plugins_acb) or send us an e-mail to contact@sherlockode.fr with your question(s). We guarantee that we answer as soon as we can! diff --git a/Resources/doc/custom_field_type.md b/Resources/doc/custom_field_type.md new file mode 100644 index 00000000..8ae2bca2 --- /dev/null +++ b/Resources/doc/custom_field_type.md @@ -0,0 +1,210 @@ +# Using a custom FieldType + +---- + +You can create your own FieldType class matching your needs.\ +For our example, we will add a new field type allowing you to create a collection of reviews. + +## FieldType Class + +Your class must implement `\Sherlockode\AdvancedContentBundle\FieldType\FieldTypeInterface` + +It can inherit `\Sherlockode\AdvancedContentBundle\FieldType\AbstractFieldType` +which already defines some interface methods for standard behavior. + +You will need to define a unique code for your field in the `getCode()` method. + +Example + +```php +add('reviews', RepeaterType::class, [ + 'entry_type' => ReviewType::class, + ]) + ; + } +} + +``` + +```php +add('title', TextType::class) + ->add('description', TextareaType::class) + ; + } +} + +``` + +In the admin, you can then add some reviews. Your custom form type is automatically inserted into the panel, as well as the extra configuration tabs. + +![image](https://user-images.githubusercontent.com/22291441/230105197-a8b63d0c-5154-4b83-83ae-24052b6c26b1.png) + +## Templates + +Thanks to the preview template, you can anticipate how your content will look like on the front + +![image](https://user-images.githubusercontent.com/22291441/230106951-84d6307d-e39f-4587-90a7-5a8911f1da08.png) + +Preview template +```twig +{# templates/admin/Acb/reviews.html.twig #} + +{% if reviews|length > 0 %} +
+ {% for review in reviews %} +
+
+
+ {% if review.title is not null %} +
{{ review.title }}
+ {% endif %} + {% if review.description is not null %} + {{ review.description|nl2br }} + {% endif %} +
+
+
+ {% endfor %} +
+{% endif %} + +``` + +For the front template, you should also include the extra configuration information.\ +Twig function "acb_get_element_attributes" will give you all necessary data to customize the display of your field. +This function will return an array indexed with "id", "classes" and "style" (calculated from the design configuration tab). + +```twig +{# templates/Acb/reviews.html.twig #} + +{% if reviews|length > 0 %} + {% set attributes = acb_get_element_attributes(extra|default([]), 'block') %} + {% set style = attributes.style|default('') %} + +
+ {% for review in reviews %} +
+
+
+ {% if review.title is not null %} +
{{ review.title }}
+ {% endif %} + {% if review.description is not null %} + {{ review.description|nl2br }} + {% endif %} +
+
+
+ {% endfor %} +
+{% endif %} + +``` diff --git a/Resources/doc/elements.md b/Resources/doc/elements.md new file mode 100644 index 00000000..8d38a6b5 --- /dev/null +++ b/Resources/doc/elements.md @@ -0,0 +1,46 @@ +# Elements + +---- + +Elements are used to create your Page display.\ +They are split between Layouts and FieldTypes. + +An Element is defined by: +- a unique code +- a custom FormType (optional) +- a preview template for the admin panel (optional) +- a front template + +# Layouts + +---- + +Rows and Columns will allow you to place your FieldTypes as you wish.\ +When adding a row, you can configure the columns gap, how content should be justified, and if you want to reverse the order of the columns on mobile. +You can configure the size and the offset of Columns for each breakpoint. + +![image](https://user-images.githubusercontent.com/22291441/230097935-4f85ec8f-cd7e-4271-888c-40ce9402bc2b.png) +![image](https://user-images.githubusercontent.com/22291441/230097827-3380be47-4e7c-4631-856b-ca75ac7732bb.png) + + +# Field Types + +---- + +We provide several [FieldTypes](field_types.md).\ +If you want, you can add your own field types. See [our tutorial](custom_field_type.md) for more info on custom field types. + +# Extra configuration + +---- + +On top of the Element FormType, each Element can be customized: +- border size, radius, style and color +- background color +- padding and margin +- element id and classes +- you can also decide on which devices your element should be hidden + +![img.png](https://user-images.githubusercontent.com/22291441/230097390-74edf614-0e14-41bc-9acd-a072fabc271f.png) +![image](https://user-images.githubusercontent.com/22291441/230097547-27dc4b85-da5b-4024-b56a-c5d44ce8d30d.png) + diff --git a/Resources/doc/entities.md b/Resources/doc/entities.md index f8a2aee8..cea76d51 100644 --- a/Resources/doc/entities.md +++ b/Resources/doc/entities.md @@ -1,7 +1,10 @@ -Entities -======== +# Entities -## Basics +----- + +# Basics + +---- We implemented the following models: - Content @@ -11,12 +14,17 @@ We implemented the following models: - PageVersion - PageMeta - PageMetaVersion +- Scope See the list of available field types [here](field_types.md) -When you create a new Page you will be able to fill in your Content inside. +# Implementation examples + +---- + +## Entities -## Implementation examples +---- Here are basic example implementations for the entity classes: @@ -340,3 +348,159 @@ class PageVersion extends BasePageVersion protected $pageMetaVersion; } ``` + +## Repositories + +---- + +Additionally, you can also setup the following repositories: + +```php +getByScopeQueryBuilder($scope) + ->andWhere('page.pageIdentifier = :pageIdentifier') + ->setParameter('pageIdentifier', $identifier) + ->setMaxResults(1) + ->getQuery() + ->getOneOrNullResult(); + } + + /** + * @param string $slug + * @param ScopeInterface|null $scope + * + * @return PageInterface|null + * + * @throws NonUniqueResultException + */ + public function findOneBySlug(string $slug, ?ScopeInterface $scope): ?PageInterface + { + return $this->getByScopeQueryBuilder($scope) + ->join('page.pageVersion', 'page_version') + ->join('page_version.pageMetaVersion', 'page_meta_version') + ->andWhere('page_meta_version.slug = :slug') + ->setParameter('slug', $slug) + ->setMaxResults(1) + ->getQuery() + ->getOneOrNullResult(); + } + + /** + * @param ScopeInterface|null $scope + * + * @return QueryBuilder + */ + private function getByScopeQueryBuilder(?ScopeInterface $scope): QueryBuilder + { + $qb = $this->createQueryBuilder('page'); + if ($scope !== null) { + $qb->join('page.scopes', 'scope') + ->andWhere('scope.locale = :locale') + ->setParameters([ + 'locale' => $scope->getLocale(), + ]); + } + + return $qb; + } +} +``` + +```php +getByScopeQueryBuilder($scope) + ->andWhere('content.slug = :slug') + ->setParameter('slug', $slug) + ->setMaxResults(1) + ->getQuery() + ->getOneOrNullResult(); + } + + /** + * @param ScopeInterface|null $scope + * + * @return QueryBuilder + */ + private function getByScopeQueryBuilder(?ScopeInterface $scope): QueryBuilder + { + $qb = $this->createQueryBuilder('content'); + if ($scope !== null) { + $qb->join('content.scopes', 'scope') + ->andWhere('scope.channel = :channel') + ->andWhere('scope.locale = :locale') + ->setParameters([ + 'channel' => $scope->getChannel(), + 'locale' => $scope->getLocale(), + ]); + } + + return $qb; + } +} +``` + +Don't forget to also update your entities with the repository class path: + +in src/Entity/Page.php: + +```php + * @ORM\Entity +``` +becomes + +```php + * @ORM\Entity(repositoryClass="App\Repository\PageRepository") +``` + +in src/Entity/Content.php: + +```php + * @ORM\Entity +``` +becomes + +```php + * @ORM\Entity(repositoryClass="App\Repository\ContentRepository") +``` diff --git a/Resources/doc/export.md b/Resources/doc/export.md index 1cc68686..9ae5c42e 100644 --- a/Resources/doc/export.md +++ b/Resources/doc/export.md @@ -1,10 +1,13 @@ -Export -====== +# Export -The export command will generate yaml files of your existing page types, pages and their content. +---- + +The export command will generate yaml files of your existing pages and their content. ## Configuration +---- + If you want to use our export command, you can configure the directory in which to write the files. If not defined, the export will write into var/acb directory. @@ -17,6 +20,8 @@ sherlockode_advanced_content: ## Command +---- + ```bash $ php bin/console sherlockode:acb:export ``` diff --git a/Resources/doc/field_types.md b/Resources/doc/field_types.md index e4066071..5da7bb67 100644 --- a/Resources/doc/field_types.md +++ b/Resources/doc/field_types.md @@ -1,52 +1,38 @@ -Field Types -=========== +# Field Types + +---- ## Simple field types -| Name | Code | Field Raw value | -| ---- | ---- | ------- | -| Text | text | string | -| Text Area | textarea | string | +| Name | Code | Field Raw value | +|-----------|----------|-----------------| +| Text | text | string | +| Text Area | textarea | string | ## Other field types -| Name | Code | Field Raw value | -| ---- | ---- | ------- | -| Wysiwyg Editor | wysiwyg | string | -| Link | link | array indexed by "url", "title" | -| Relative Link | relative_link | array indexed by "url", "title" - "url" will be automatically generated depending on your http scheme and host | -| Iframe | iframe | array indexed by "href" | -| File upload | file | array indexed by "src" (file name), "url" (full url to the file resource), "title" | -| Image upload | image | array indexed by "src" (file name), "url", (full url to the image resource), "alt" | - -## Using a custom FieldType - -You can create your own FieldType class matching your needs. - -### FieldType Class - -Your class must implement `\Sherlockode\AdvancedContentBundle\FieldType\FieldTypeInterface` - -It can inherit `\Sherlockode\AdvancedContentBundle\FieldType\AbstractFieldType` -which already defines some interface methods for standard behavior. +| Name | Code | Field Raw value | +|----------------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------| +| Wysiwyg Editor | wysiwyg | string | +| Link | link | "url", "title" | +| Relative Link | relative_link | "url", "title" - "url" will be automatically generated depending on your http scheme and host | +| Iframe | iframe | "href" | +| File upload | file | "src" (file name), "url" (full url to the file resource), "title" | +| Image upload | image | "src" (file name), "url", (full url to the image resource), "alt" | +| Image carousel | image_carousel | "images" array. Each image is indexed with "src", "url" and "alt". Two booleans variables are also available: displayPagination and displayArrows | +| Separator | separator | none | +| Title | title | "text" for the content of the title. "Level" (1 to 6) for the heading type. | +| Video | video | "url" for the video url. Then options for the player: "muted", "autoplay", "loop", "controls", "height", "width" | +| Content | content | "entity" contains the Content object (if found, null otherwise). "content" contains the slug of the content. | | -You will need to define a unique code for your field in the `getCode()` method. -### FieldType Service - -```yaml -# config/services.yaml -app.field_type.custom_field_type: - class: App\FieldType\CustomFieldType - tags: - - { name: sherlockode_advanced_content.fieldtype } -``` - -### Specific Form types +## Specific Form types There are some specific form types available to ease integration of specific use cases. -#### EntityType +### EntityType + +---- You can use the `Sherlockode\AdvancedContentBundle\Form\EntityType` to integrate an Entity form in your custom field type. The class directly extends the native EntityType from Symfony and adds a transformer to handle ID storage. @@ -73,7 +59,9 @@ class CustomType extends AbstractType } ``` -#### RepeaterType +### RepeaterType + +---- The `RepeaterType` lets you define easily a collection of elements in a field. The repeater will automatically and addition, removal and sorting of the elements for the end user. diff --git a/Resources/doc/import.md b/Resources/doc/import.md index b89a4db7..aa8edee1 100644 --- a/Resources/doc/import.md +++ b/Resources/doc/import.md @@ -1,17 +1,18 @@ -Import -====== +# Import -The import command will create your page types, pages and their content. +---- + +The import command will create your pages and contents. ## Configuration +---- + If you want to use our import command, you can configure the directory in which to find the source files. If not defined, the import will parse var/acb directory. By default, only creation is available. If you want to be able to update your entities, you can change the flag `allow_update` -By default, if not defined at field level, fields will be created as optional. If you want your fields to be mandatory by default, you can change the flag `field_default_required` - To import files to your contents, you need to configure the directory in which to find the source files. If not defined, the import will parse var/acb/files directory. You can either use a relative path (relative from `%kernel.project_dir%`) or an absolute path (for example `/tmp/files`) @@ -23,7 +24,6 @@ sherlockode_advanced_content: init_command: directory: custom/dir allow_update: true - field_default_required: true files_directory: custom/dir/files ``` @@ -44,6 +44,8 @@ sherlockode_advanced_content: ## Command +---- + ```bash $ php bin/console sherlockode:acb:import ``` @@ -66,26 +68,31 @@ $ php bin/console sherlockode:acb:import --dir=specific/dir #import all types / ## Source files +---- + ### Basics +---- + Source files must be in yaml format. -There must be one file per content type / per page. +There must be one file per content / per page. There is no restriction on the file naming. All files of the source directories will be parsed. ### Pages -You need to define an identifier for your Page and metas for at least one language +---- + +You need to define an identifier and meta information for your Page. ```yaml # var/acb/Page/custom_page.yaml pages: page-identifier: - metas: - en: - title: Custom Page - slug: custom-page - meta_title: 'Meta Title' # optional - meta_description: 'Meta Description' # optional + meta: + title: Custom Page + slug: custom-page + meta_title: 'Meta Title' # optional + meta_description: 'Meta Description' # optional ``` You can also define other optional information: @@ -94,26 +101,26 @@ You can also define other optional information: pages: page-identifier: status: 10 # (0: Draft (default) / 10: Published / 20: Trash) - pageType: Custom Page Type (if defined, will automatically retrieve the ContentType linked to the PageType) - contents: - en: # locale of the content - #list of elements of the Content linked to this Page - - type: text - value: hello - fr: - - type: text - value: bonjour - metas: - en: - title: Custom Page - slug: custom-page-en - meta_title: 'Meta Title' - meta_description: 'Meta Description' - fr: - title: Page personnalisée - slug: page-personnalisee - meta_title: 'Méta Titre' - meta_description: 'Méta Description' + pageType: Custom Page Type + content: + #list of elements of the Content linked to this Page + - + type: row + elements: + - + type: column + elements: + - + type: text + value: hello + - + type: text + value: How are you? + meta: + title: Custom Page + slug: custom-page-en + meta_title: 'Meta Title' + meta_description: 'Meta Description' ``` Each element declaration has the following structure: @@ -128,26 +135,70 @@ You can find a Page import file example here [doc](import/Page/custom_page.yaml) ### Contents -You need to define the name of your Content, slug and locale: +---- + +You need to define the name of your Content, its slug and its children elements: ```yaml # var/acb/Content/content.yaml contents: content-slug: name: Custom Content - locale: en + children: + - + type: row + elements: + - + type: column + elements: + - + type: heading + value: + text: Hello + level: 1 + - + type: text + value: How are you? ``` -Then, as for the content of your Pages, you need to define your elements under `children` - You can find a Content import file example here [doc](import/Content/standalone_content.yaml) These example files also show you how to create and populate File and Image field types. +### Scopes + +---- + +If you want to link scopes on your entities, you can use the following template: + +```yaml +# var/acb/Page/custom_page.yaml +pages: + page-identifier: + scopes: + - + locale: en_GB + - + locale: en_US + +# var/acb/Content/content.yaml +contents: + content-slug: + name: Custom Content + scopes: + - + locale: en_GB + - + locale: en_US +``` ### Specific field types +---- + #### File / Image FieldType +---- + When you export the content of File / Image FieldType for which you have already imported a resource, you will obtain the following structure. diff --git a/Resources/doc/import/Content/standalone_content.yaml b/Resources/doc/import/Content/standalone_content.yaml index cfc32376..e828b8e4 100644 --- a/Resources/doc/import/Content/standalone_content.yaml +++ b/Resources/doc/import/Content/standalone_content.yaml @@ -1,21 +1,34 @@ contents: standalone-content: name: Standalone Content - locale: en children: - - - type: text - value: Hello world - - - type: boolean - value: 1 - - - type: image - value: - _file: background.png - alt: Content Background - - - type: file - value: - _file: document.pdf - title: File title + - type: row + elements: + - type: column + elements: + - + type: heading + value: + text: Content title + level: 2 + extra: + advanced: + id: content-title + - + type: text + value: Hello world + extra: + advanced: + hide_on: + - lg + - xl + - + type: image + value: + _file: background.png + alt: Content Background + - + type: file + value: + _file: document.pdf + title: File title diff --git a/Resources/doc/import/Page/custom_page.yaml b/Resources/doc/import/Page/custom_page.yaml index d8ba745c..33a97856 100644 --- a/Resources/doc/import/Page/custom_page.yaml +++ b/Resources/doc/import/Page/custom_page.yaml @@ -2,27 +2,46 @@ pages: custom-identifier: status: 10 pageType: Custom Page Type - contents: - en: - - - type: text - value: Text value - - - type: my-custom-field - value: - block1: - title: Title value - block2: - title: Title layout value - elements: - - - name: First group of repeater - title - description: 'First group of repeater - description' - - - name: Second group of repeater - title - description: 'Second group of repeater
description' - metas: - en: - title: Custom Title - slug: custom-page - meta_description: "Custom Meta Description" + content: + - type: row + elements: + - type: column + elements: + - + type: text + value: Text value + extra: + design: + background_color: '#d9d9d9' + background_color_select: pick + - + type: separator + value: + - + type: content + value: + content: slug-of-the-content + config: + size: 6 + - type: column + elements: + - + type: my-custom-field + value: + block1: + title: Title value + block2: + title: Title layout value + elements: + - + name: First group of repeater - title + description: 'First group of repeater - description' + - + name: Second group of repeater - title + description: 'Second group of repeater
description' + config: + size: 6 + meta: + title: Custom Title + slug: custom-page + meta_description: "Custom Meta Description" diff --git a/Resources/doc/tools.md b/Resources/doc/tools.md index 0e2d1497..f0ba718f 100644 --- a/Resources/doc/tools.md +++ b/Resources/doc/tools.md @@ -1,7 +1,13 @@ -Tools -===== +# Tools + +---- The page acb/tools allows you to [import](import.md) / [export](export.md) your entities. +It also includes a CRUD system for scopes and page types + +## Configuration + +---- By default, the template used for this page is `@SherlockodeAdvancedContent/Tools/index.html.twig` You can override this by adding your own file in the configuration : @@ -24,8 +30,36 @@ sherlockode_sonata_advanced_content: tools: false ``` +## Import / Exports + +---- + On this page, you will be able to : - import your entities : upload any yaml file containing your entity. As long as you respect the [format](import.md), you can include as many entities in the file as you want - export your entities : you will be able to select which entity/entities you want to export. This will result in a zip file being downloaded in your browser. + + +## Scopes + +---- + +By defaut, scopes are not enabled on the bundle. +If you want to handle scopes on your Pages and Contents, you need to enable scope management and also create some scopes. +By default, the provided Scope class is locale-based. You can override the entity if it does not meet your requirements. +Scopes can be created on the tools page. + +```yaml +# config/packages/sherlockode_advanced_content.yml +sherlockode_advanced_content: + scopes: + enabled: true +``` + +## Page Types + +---- + +Typing pages allows you to categorize them and use different layouts. +However, if this functionality is not useful to you, you can setup your pages without any page type. diff --git a/Resources/doc/usage.md b/Resources/doc/usage.md index 87e28f34..a9cf5ab4 100644 --- a/Resources/doc/usage.md +++ b/Resources/doc/usage.md @@ -1,21 +1,25 @@ -Usage -====== +# Usage -## Controller +---- -### Page +## Page -To display content linked to a given page, you can have the following controller: +---- + +To display a page, you can use the following controller and template: ```php getPage(); + $page = $em->getRepository(Page::class)->findOneBySlug( + $request->attributes->get('slug'), + $scopeHandler->getCurrentScope() + ); if ($page->getStatus() !== PageInterface::STATUS_PUBLISHED || !$page->getContent() instanceof ContentInterface) { throw $this->createNotFoundException(); } - return $this->render('content.html.twig', [ - 'content' => $page->getContent(), + return $this->render('page.html.twig', [ + 'page' => $page, ]); } } ``` -### Standalone Content +```twig +{# templates/page.html.twig #} + +{% extends 'layout.html.twig' %} -If your content is not linked to any page (for example, your homepage), you can retrieve it by using its slug. +{% block title %} + {% if page.pageMeta is not null and page.pageMeta.metaTitle %} + {{ page.pageMeta.metaTitle }} + {% else %} + {{ parent() }} + {% endif %} +{% endblock %} -## Twig +{% block metatag_description %} + {% if page.pageMeta is not null and page.pageMeta.metaDescription %} + + {% endif %} +{% endblock %} -The bundle provides a twig function that will return a string or array containing formatted data for a given content. +{% block content %} + {% for element in page.content.data %} + {{ acb_render_element(element) }} + {% endfor %} +{% endblock %} -```twig -{% set rawData = acb_render_element(content.myField) %} ``` -Depending on the type and structure of the field, the data will be formatted differently. -Each class inheriting the FieldTypeInterface must implement the `getRawValue()` for this purpose. +## Content + +---- + +If your content is not linked to any page (for example, your homepage), you can retrieve it by using its slug. +If scopes management is not enabled, this method will return the single content linked to the slug. +If scopes management is enabled, this method will return the content linked to the slug and to the current front scope (current locale). +If no content is found, the twig function will return null. + +```twig +{% set content = acb_get_content_by_slug(slug) %} +{% if content is not null %} + {% for element in content.data %} + {{ acb_render_element(element) }} + {% endfor %} +{% endif %} +```