Installation

Require the package

Add iq2i/storia-bundle to your composer.json file:

composer require iq2i/storia-bundle

Register and configure the bundle

If you are using Symfony Flex, the following steps should be done automatically. Otherwise, follow the instructions.

Register the bundle

Inside config/bundles.php, add the following line:

// config/bundles.php

return [
    // ...
    IQ2i\StoriaBundle\IQ2iStoriaBundle::class => ['all' => true],
];

Add routes

Create a new routing file to add UI Storia's routes:

# config/routes/iq2i_storia.yaml
iq2i_storia:
    resource: '@IQ2iStoriaBundle/config/routes.php'
    prefix: '/storia'

Create folders where YAML files are stored

Create the storia folder at the root of your project, with two subfolders: components and pages.

Configure the bundle

By default, UI Storia will try to read YAML files in the storia folder at the root of your application. You can change this behavior by creating a configuration file config/packages/iq2i_storia.yaml with the following content:

# config/packages/iq2i_storia.yaml

iq2i_storia:
    default_path: '%kernel.project_dir%/new-folder'

When is the bundle enabled?

UI Storia is enabled when kernel.debug is true, like the Symfony profiler: in dev and test, not in prod. Its routes answer with a 404 when it is disabled. The commands (storia:test, storia:export, ...) keep working in every environment.

Force the value with the enabled option when you need to:

# config/packages/iq2i_storia.yaml

iq2i_storia:
    # expose UI Storia on a staging environment that runs with debug disabled
    enabled: true

# config/packages/iq2i_storia.yaml

iq2i_storia:
    # or turn it off everywhere, with an environment variable for easier configuration
    enabled: '%env(bool:IQ2I_STORIA_ENABLED)%'

Load your styles and scripts

UI Storia will render your interfaces without CSS or JavaScript.
To instruct UI Storia to use your styles and scripts, simply override the iframe.html.twig template following the Symfony documentation:

{# templates/bundles/IQ2iStoriaBundle/iframe.html.twig #}

{% extends '@!IQ2iStoria/iframe.html.twig' %}

{# if you use WebpackEncoreBundle #}
{% block stylesheets %}
    {{ encore_entry_link_tags('app') }}
{% endblock %}
{% block javascripts %}
   {{ encore_entry_script_tags('app') }}
{% endblock %}

{# if you use AssetMapper #}
{% block javascripts %}
   {% block importmap %}{{ importmap('app') }}{% endblock %}
{% endblock %}