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://packagist.org/packages/sherlockode/advanced-content-bundle "License")
+[ ](https://packagist.org/packages/sherlockode/advanced-content-bundle "Version")
+[ ](https://packagist.org/packages/sherlockode/advanced-content-bundle "Total Downloads")
+[ ](https://www.sherlockode.fr/contactez-nous/?utm_source=github&utm_medium=referral&utm_campaign=plugins_acb)
+
+
+
+## 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.
-[](https://packagist.org/packages/sherlockode/advanced-content-bundle)
-[](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.
+
+
+
+## Templates
+
+Thanks to the preview template, you can anticipate how your content will look like on the front
+
+
+
+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.
+
+
+
+
+
+# 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
+
+
+
+
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 %}
+```