Skip to content

Core concepts

Each site is represented by a folder in the sites directory. The name of the folder must be the same as the canonical URL of the site defined in its site.yml file. As the bare minimum TwigYard requires the site.yml file and the src folder to be present for the site to be functional.

On the frontend side of things TwigYard is pretty technology agnostic. Type raw css, use grunt, gulp or whatever you like. You do not need to modify your current devstack in any way to use TwigYard. Within the site folder you are free to use any tools you like to as long as they generate the required file structure.

site.yml

TwigYard requires that each site has a main config file whose name is defined in the instance wide parameters.yml file. While the name can be anything, it is recommended to name it site.yml if possible. For simplicity we will refer to this main site config as site.yml in this manual.

The site.yml has two versions. The now deprecated version 1 functions as the fallback if no version is specified. See the middleware reference for supported configuration options.

Substitution

Some data needed in the site.yml file might be too sensitive to be commited to VCS. These secrets can be defined in a file parameters.yml which can be kept out of version control. Data from this file can be used in the site.yml via the %param_name% syntax. All parameters to be substituted must be defined in the parameters.yml as a flat map under top level parameters key. The file must be manually included in the site.yml.

Composition

The site.yml can include other files to make the configuration more flexible. For example it allows the config to be divided into multiple files for better readability.

# site.yml

...
imports:
    - { resource: 'router.yml' }
    - { resource: 'renderer.yml' }

Overloading

Imports make it possible to have the site behave differently between environments. On a staging instance, for example, we might prefer to use a different configuration then on production. Typically we need to protect the site by httpauth. This can be solved by creating a separate site_staging.yml which imports the production site.yml and set the staging instance to use this is the main config file. This way we can overload any configuration in site.yml.

Example

# parameters.yml

parameters:
    mailing_smtp_host: mail
    mailing_smtp_port: 1025
# site_staging.yml

version: 2
middlewares:
    httpauth:
        username: user
        password: pass

imports:
    - { resource: 'site.yml' }
# site.yml

version: 2

componets:
    mailer:
        smtp_host: "%mailer_smtp_host%"
        smtp_port: "%mailer_smtp_port%"
        smtp_encryption: "%mailer_smtp_encryption%"
        smtp_username: "%mailer_smtp_username%"
        smtp_password: "%mailer_smtp_password%"

middlewares:
    url:
        canonical: www.example.com
        extra: [ example.com, web.example.com ]

    locale:
        default:
            key: cs
            name: cs_CZ
        extra: { en: en_US, de: de_DE }

    data:
        contact: contact.yml
        products: products.yml

    router:
        index:
            cs_CZ: /
            en_US: /
            de_DE: /
        product:
            cs_CZ: /zbozi/{product_id | products:manufacturer.id}
            en_US: /products/{product_id | products:manufacturer.id}
            de_DE: /produkte/{product_id | products:manufacturer.id}
    form:
        contact:
            handlers:
                -   type: email
                    from:
                        name: John Doe Corp.
                        address: john@doe.com
                    recipients:
                        to: [ example_1@example.com ]
                        bcc: [ example_2@example.com ]
                    templates:
                        subject: email/subject.html.twig
                        body: email/body.html.twig
            fields:
                name: { type: string, min_length: 3, max_length: 100 }
                email: { type: email, required: true }
                message: { type: string, min_length: 10, max_length: 1000, required: true }
    renderer:
        index: index.html.twig
        product: product.html.twig

imports:
    - { resource: 'parameters.yml' }

src

All site files except site config files (i.e. site.yml, site_staging.yml, parameters.yml, etc.) are to be located according to their type in a folder within the src directory. The subfolders are:

  • data (For data yaml files used by the data middleware)
  • languages (For translation strings)
  • templates (The Twig templates)

Twig templates

TwigYard uses template engine for PHP – Twig. For more information about templates or available functions and filters please read Twig documentation.