# Introduction

Welcome to the Sylius CMS Plugin docs.

If you just want to get started, head over to the [installation instructions](/getting-started/installation).

If you have any feedback on the plugin or the docs, please don't hesitate to email us at <info@setono.com>.


# Installation

Before you can install the plugin you need a packagist token. You get a token once you buy the plugin. If you haven't done so yet, go to [sylius-cms.com](https://sylius-cms.com) and hit the big buy button ;)

{% hint style="info" %}
If you have Flex installed and just want the plugin installed with the default settings, go directly to [Installing the plugin](#installing-the-plugin)
{% endhint %}

### Installing the plugin

Since the plugin is being provided through packagist.com you just have two steps to take before you can install the plugin:

**1. Add repository to composer.json**:

```shell
composer config repositories.private-packagist composer https://setono.repo.packagist.com/acme/
```

Remember to replace `acme` with the short name given to you.

**2. Add token to composer auth**:

```shell
composer config --global --auth http-basic.setono.repo.packagist.com token your_token
```

Remember to replace `your_token` with the token given to you.

Now you should be able to install the plugin using the normal `composer require` command:

```shell
composer require setono/sylius-cms-plugin
```

### Enabling the plugin

If you have Flex enabled the `composer require` will automatically add the bundles and the plugin to `bundles.php`. If not you should manually add them:

```php
    // ...

    Setono\SyliusCMSPlugin\SetonoSyliusCMSPlugin::class => ['all' => true],
    Sylius\Bundle\GridBundle\SyliusGridBundle::class => ['all' => true],
    
    // ...
```

{% hint style="info" %}
**NOTICE:** It's important that you add the plugin *before* the `SyliusGridBundle`.
{% endhint %}

### Add configuration file

Create the file `config/packages/setono_sylius_cms.yaml` and add the following:

```yaml
# config/packages/setono_sylius_cms.yaml
imports:
    - { resource: "@SetonoSyliusCMSPlugin/Resources/config/app/config.yaml" }

    # Uncomment next line if you want some default fixtures for this plugin
    # - { resource: "@SetonoSyliusCMSPlugin/Resources/config/app/fixtures.yaml" }
```

### Include routes configuration

Create the file `config/routes/setono_sylius_cms.yaml` and add the following:

```yaml
# config/routes/setono_sylius_cms.yaml
setono_sylius_cms:
    resource: "@SetonoSyliusCMSPlugin/Resources/config/routes.yaml"
```

{% hint style="info" %}
The plugin also provides a routes file for non localized stores. All you do is to use `@SetonoSyliusCMSPlugin/Resources/config/routes_no_locale.yaml` instead of `@SetonoSyliusCMSPlugin/Resources/config/routes.yaml`
{% endhint %}

### Update your database

Run the two following commands to create the tables needed for the CMS plugin:

```bash
php bin/console doctrine:migrations:diff
php bin/console doctrine:migrations:migrate
```

### Install assets

```bash
php bin/console assets:install
```

**You're good to go!**


# Your first page

Creating your first page is a great start to getting to know the CMS capabilities. It will guide you through the process of creating templates, views, and blocks.

When a page is requested, the CMS will go through this *flow*:

1. See if that page exists and is eligible to be shown
2. Then render the view associated with the page
3. The view in turn renders the blocks and the blocks are rendered in places determined by the template

### Creating your first template

From this short description, you can deduce that the basis for our page is the template, so let's create a template. Click on `Templates` in the menu and click `Create`. Input `first_template` in the `Code` field and the following to the `Source` field:

```twig
{% block sscms_section_content %}
    Default content for this section
{% endblock %}
```

The internal description field is used for your internal usage to better identify templates later on. Here is a screenshot of what you should have now:

![First template](https://1528177949-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLsMmokp2IwN4RyI8hmoy%2Fuploads%2Fgit-blob-800768feff262ee681ffafbde151410a891254b9%2Ffirst_page_template.png?alt=media)

{% hint style="info" %}
The prefix `sscms_section_` is how you denote sections inside templates. Hence, we have just created a section inside our template named `content`.
{% endhint %}

Last, but not least, hit `Create`.

### Creating your first block

Next up is creating the blocks we want to appear in the `content` section of the template. Go to `Blocks` and click `Create`. Input `first_block` in the `Code` field and add your content to the content fields. You should end up with something like this:

![First block](https://1528177949-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLsMmokp2IwN4RyI8hmoy%2Fuploads%2Fgit-blob-ee0c29e9f301b1bb202afc7bbe5e92b2ea686a80%2Ffirst_block.png?alt=media)

Hit `Create`.

### Creating your first view

Now we have to tie the blocks to the section we defined in the template. We do this in a view. Click on `Views` and then `Create`.

Now, in the `Code` your input `first_view` and for the template you choose `first_template`. When you select the template the available sections for the template appears on the right. Now you select `first_block` and you should have something like the following image:

![First block](https://1528177949-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLsMmokp2IwN4RyI8hmoy%2Fuploads%2Fgit-blob-e337641f13d8821d9ca539d2e07b6843e60fb29d%2Ffirst_view.png?alt=media)

Remember to hit `Create`

### Creating your first page

Last step! We will now create our page. Go to `Pages` and click `Create`. Input `first_page` in the `Code` field and select the view we just created, namely `first_view`, and input `first-page` in the `Slug` field. Again, here is an image showing what it could look like:

![First block](https://1528177949-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLsMmokp2IwN4RyI8hmoy%2Fuploads%2Fgit-blob-4ed8a2016e5031cc45cfa1e61c485b4b66561bac%2Ffirst_page.png?alt=media)

Click `Create`.

You're done! Go to `/en_US/first-page` to see your new page!


# Templates

Templates are your starting point when you want to create a landing page, a layout of your taxon description, or a section with multiple rows or columns in your product page.

Technically the templates are Twig templates and are loaded as Twig templates. This comes with a lot of built-in advantages:

* You have the full power of Twig available
* You can reference a template created in the CMS directly in your Sylius application
* Cache is already handled

### The power of Twig

Twig is the template language used in Symfony applications (hence also in Sylius). It's very powerful in and of itself as you can read by going through the extensive [documentation](https://twig.symfony.com/).

This also implies that you can use all the tags, filters, functions etc. from Twig. Let's say you wanted to create a base template for landing pages and use that template in other child templates; just use the `extends` tag. There are lots of built-in [features](https://twig.symfony.com/doc/2.x/) to choose from, but if you want something specific to your use case, just ask your developer to create a Twig extension, and it will be available for you to use in your templates.

### Reference templates directly in your Sylius application

Say you wanted to control the layout of your product page. Just create a template named `product` and reference this template in your Sylius application instead of the built-in templates. Now you are in complete control of everything that happens on your product page.

### Cache is handled

By using Twig we gain a few advantages with regard to speed: Cache and compilation. First, all Twig templates are compiled into simple PHP files. Secondly, these PHP files are saved on the filesystem (the cache).

So when you create a template, and it's referenced, what happens is that it gets compiled and saved to the filesystem. This implies that you should not worry about the speed of having templates saved in the database in contrast to saving them on the filesystem. There is literally no difference - both are *fast*!


# Blocks

The name *blocks* gives the concept away. These are the building blocks of anything else. This is what everything else is made up of.

To render a block in a template you write `{{ sscms_block('your block code') }}`.

Though simple, we have added a few things to make it shine. The interface looks like this:

![Create block interface](https://1528177949-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLsMmokp2IwN4RyI8hmoy%2Fuploads%2Fgit-blob-90ea05838c9203f4ea0e0ec75e76e1e3bbc10539%2Fcreate_block.png?alt=media)

### Default content

As you can see we have added a default content field. Let's say you want to output **BLACK FRIDAY** in a block to all your users, no matter their language. This is the field for that. This way you don't have to copy 'BLACK FRIDAY' in all the content fields. It's also very useful when you add new languages. With the default content field these new languages will have content to show instead of nothing.

### The editor

The editor we use is the [editorjs](https://editorjs.io/). It's what's called a block-based or block-styled editor much like the Gutenberg in Wordpress. All paragraph, images, quotes etc. are made up of small pieces that are then turned into JSON and subsequently turned into HTML. If you want a new feature in the editor please reach out or if it's very specific to your business have your developer create a plugin for the editor (it's rather simple ;)).

### Content is rendered as Twig

Woohooo! If you read the [templates](/concepts/templates) page you know the power of Twig. Instead of just outputting the HTML generated, we generate Twig and when blocks are rendered, they are rendered in the Twig engine. This means you can for example output/use global Twig variables directly in your blocks. I.e. `{{ sylius.channel.code }}` would output the `code` for the current channel.


# Views

Views are the glue between templates and blocks. If you want a practical example of this, please refer to the guide: [Your first page](/getting-started/your-first-page).


# Pages

Pages is where you create your landing pages, content pages etc. for your store. Below is the interface for creating a page, and we will go through the different features here.

![Edit page interface](https://1528177949-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLsMmokp2IwN4RyI8hmoy%2Fuploads%2Fgit-blob-3ea77f20fef3dbb44ea7f47df76277a9c43bf13f%2Fedit_page.png?alt=media)

1. Notice that the content of your page is determined by the associated view (see [views](/concepts/views)). This has the (great) side effect that if you have some content (an example could be terms and conditions) that you want in multiple places, but also on a separate page, you create that content as a view, and then you can use that view for outputting directly in templates, but also associating that view with a page (i.e. a URL).
2. Secondly you have eligibility. The example is for Black Friday, and we want the page to go live at `00:00` on Black Friday and go offline again at `23:59`. Here you also find the toggling of `Enabled` and channels.
3. On the right you have the features that make this a page, i.e. the URL and title along with meta description for SEO purposes.
4. In the right-hand corner you have the `Preview` button, which as the name suggest, will allow you to preview your page despite it not being eligible to show to users yet.


# Assets

Assets is an umbrella term for all your images, videos, files etc. Most likely you will use assets for images most of the time and to render an image asset you write `{{ sscms_asset('your asset code') }}` in your template.

Below you see an example of an existing asset.

![Edit asset interface](https://1528177949-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLsMmokp2IwN4RyI8hmoy%2Fuploads%2Fgit-blob-421a3dcfdbcbcd904511d92baa66b26c7bcde8d9%2Fedit_asset.png?alt=media)

### Technicalities

When developing the plugin we have chosen *not* to utilize the `LiipImagineBundle` for image assets because of a few reasons:

1. Out of the box, the imagine library will make the image quality poorer, and we trust that frontenders / marketing people are used to creating pixel perfect high quality images, and we don't want to get in the way of that.
2. If we created a filter set, what settings would we choose? Would we choose a maximum of 2000 px wide images? And why? Would we choose a quality of 100 or 80? Instead of trying to make a decision for you, we give you the bare asset.

Rendering an image asset will give you something like `<img src="https://example.com/cms/asset/21">`. This URL has cache headers which means it will be cached by 1) browsers, but also by 2) reverse proxies like Cloudflare. The implication of that is that it's unwise to change an asset once created because that asset might be cached.


# Upgrade to v0.6

First run `php bin/console doctrine:migrations:diff` to get a fresh migration file. Now search for `code VARCHAR(255) NOT NULL` within that file. Immediately after that line add the following line:

```
$this->addSql("UPDATE setono_sylius_cms__asset SET code=SUBSTR(REPLACE(path, '/', ''), 1, 32)");
```

This will make sure the newly added `code` field will be unique.


# Contact

As a paying customer you have free email and chat support. Please send an email to <info@setono.com> if you have any issues with the plugin.

You can also reach out to `loevgaard` at the [Sylius Slack channel](https://sylius-slackin.herokuapp.com).


# Feedback

We would love to hear from you! Any feedback is welcome. Please email <info@setono.com> with great ideas, new ways to help you out or anything else.