diff --git a/README.md b/README.md new file mode 100644 index 0000000..dd2915b --- /dev/null +++ b/README.md @@ -0,0 +1,182 @@ +# UI Storia + +## Overview + +UI Storia is a powerful tool designed to simplify and speed up the development process of user interfaces by providing a visual and modular development environment for interface in your Symfony application. + +![UI Storia, a powerful tool designed to simplify and speed up the development process of user interfaces by providing a visual and modular development environment for interface in your Symfony application.](/doc/images/ui-storia-promo.png) + +Unlike Fractal or StoryBook, which rely on a port of Twig to JS for Symfony projects, UI Storia allows direct work on project templates, thus enabling the safe use of the latest Twig features available. + +## Sponsors + +

+ + Mezcalito - Agence Digitale à Grenoble depuis 2006 + +

+ +## Installation + +To install UI Storia into your Symfony project, follow these steps: + +1. Make sure you have Symfony installed locally. +2. Add UI Storia to your project using Composer: + ```bash + composer require iq2i/storia-bundle + ``` +3. Once installation is complete, activate the bundle in the `config/bundles.php` file: + ```php + return [ + // ... + IQ2i\StoriaBundle\IQ2iStoriaBundle::class => ['all' => true], + ]; + ``` +4. Create a new routing file to add UI Storia's routes: + ```yaml + # config/routes/is2i_storia.yaml + iq2i_storia: + resource: '@IQ2iStoriaBundle/config/routes.php' + prefix: '/storia' + ``` +5. Create the `storia` folder at the root of your project, with two subfolders: `components` and `pages`. +6. Configure UI Storia following the detailed configuration steps below. + +## Configuration + +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: + +```yaml +# config/packages/iq2i_storia.yaml + +iq2i_storia: + default_path: '%kernel.project_dir%/new-folder' +``` + +It is also possible, from this same file, to enable or disable the bundle (specifically to condition its routes) with a configuration parameter: + +```yaml +# config/packages/iq2i_storia.yaml + +iq2i_storia: + # use an environment variable for easier configuration + enabled: '%env(IQ2I_STORIA_ENABLED)%' +``` + +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](https://symfony.com/doc/current/bundles/override.html#templates): + + +```twig +{# 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 %} +``` + +> [!TIP] +> Note the use of `!` in the extended template name to override only the blocks you need rather than the entire template. + +## Interfaces + +UI Storia allows you to create interfaces for individual components or more complete pages. +You can work with Twig templates from your Symfony application or with local templates that will be used only for UI Storia. + +To describe your interfaces, simply create a YAML file in the `storia/components` or `storia/pages` folder as follows: + +```yaml +# storia/components/progress.yaml + +template: ui/progress.html.twig +variants: + small: + args: + height: 1.5 + + default: + args: + height: 2.5 + + large: + args: + height: 4 + + extra_large: + args: + height: 6 +``` + +The difference between the `storia/components` folder and the `storia/pages` folder is as follows: +By convention, use the `storia/components` folder for interfaces related to macro components and the `storia/pages` folder for interfaces for more complete pages. + +Here's the configuration details: + +* `template`: Corresponds to the path to the Twig template of your Symfony application that you want to work with. +* `variants`: This is the list of different variants you want to create. + +### Template / Component + +The `template` key is optional because you can also use a Twig template at the same level and with the same name as your YAML file. +For example, for your YAML file `storia/components/progress.yaml`, you can create a file `storia/components/progress.html.twig` and this file will be used by UI Storia. + +UI Storia also provides native support for [Twig Component](https://symfony.com/bundles/ux-twig-component/current/index.html) for your interfaces. To do this, simply replace the `template` key with the `component` key as shown below: + +```yaml +# storia/components/button.yaml + +component: Button +variants: + plain: + args: + class: plain + label: Plain button + + outline: + args: + class: outline + label: Outline button +``` + +### Variants + +The `variants` key lists the different variations of your interface, passing different arguments to your template. + +Each variant is described with a name (which can be overridden as shown in the example below) and an array of arguments called `args`. +Twig Component support also brings a `blocks` key to configure [HTML blocks](https://symfony.com/bundles/ux-twig-component/current/index.html#passing-html-to-components-via-blocks) that will be passed to your component. + +```yaml +# storia/components/button.yaml + +component: Button +variants: + plain: + args: + class: plain + blocks: + content: Plain button + svg: '' + + outline: + name: My outline button + args: + class: outline + blocks: + content: Outline button + svg: '' +``` + +> [!IMPORTANT] +> Note here that the `content` block is the default block for Twig Component according to the documentation ([see here](https://symfony.com/bundles/ux-twig-component/current/index.html#passing-html-to-components)), so it will have a different behavior that we will detail later. diff --git a/doc/images/mezcalito.png b/doc/images/mezcalito.png new file mode 100644 index 0000000..1c51673 Binary files /dev/null and b/doc/images/mezcalito.png differ diff --git a/doc/images/ui-storia-promo.png b/doc/images/ui-storia-promo.png new file mode 100644 index 0000000..a89916e Binary files /dev/null and b/doc/images/ui-storia-promo.png differ