Skip to content

JSX like component syntax for Twig templating language

Notifications You must be signed in to change notification settings

lmc-eu/twigx-bundle

Repository files navigation

TwigX Bundle

Latest Stable Version Coverage Status

Symfony bundle extending Twig template engine with JSX-like markup.

Requirements

  • PHP 7.4 || 8.1
  • Symfony 4.4+ || 5.4+ || ^6.1
  • Twig >=1.44.6 || >=2.12.5 || 3+

Changelog

See CHANGELOG

How to install

Step 1

Download using composer

Install package

composer require lmc/twigx-bundle

Step 2

Add TwigXBundle into bundles (under all bundles). If you use Symfony flex, it will be configured automatically.

bundles.php

    return [
        ...,
        Lmc\TwigXBundle\TwigXBundle::class => ['all' => true],
    ];

Step 3 (optional)

If you want to change the default settings, create a config

config/packages/twigx.yml

    # all parameters are optional
    twigx:
        # define one or more paths to expand or overload components (uses glob patterns)
        paths:
            - "%kernel.project_dir%/templates/components"
        paths_alias: 'jobs-ui' # alias for twig paths above (default is 'spirit')

Usage

Now you can use Twig components with HTML-like syntax in your Symfony project. You only need to remember that, unlike in HTML, component tags must always start with a capital letter:

<ComponentName attr="value">Some other content</ComponentName>
  ...
<ComponentName attr="value" />

You can pass attributes like this:

<ComponentName
:any="'any' ~ 'prop'" // this return as "any" prop with value "anyprop"
other="{{'this' ~ 'works' ~ 'too'}}"
anotherProp="or this still work"
not-this="{{'this' ~ 'does'}}{{ 'not work' }}" // this returns syntax as plain text but prop with dash work
ifCondition="{{ variable == 'success' ? 'true' : 'false' }}"  // condition can only be written via the ternary operator
jsXCondition={ variable == 'success' ? 'true' : 'false' }  // condition can only be written via the ternary operator
isBoolean={false}  // if value is false
numberValue={11}  // if value is number 11
isOpen  // if no value is defined, it is set to true
>
    Submit
</ComponentName>

or pure original implementation

{% embed "@spirit/componentName.twig" with { props: {
    attr: 'value'
}} %}
    {% block content %}
        Some other content
    {% endblock %}
{% endembed %}

Allowed parenthesis

You can pass variables to props using two syntaxes. JSX-like syntax uses single {...} parentheses or Twig-like syntax that uses {{...}} parentheses. In both cases, there can be a whitespace around the value that is used. See the examples below.

JSX-like syntax example:

<ComponentName variable={value} anotherVariable={ value } />

Twig like syntax example:

<ComponentName variable={{value}} anotherVariable={{ value }} />

if you want to extend these components, an example guide is here. if you want to contribute, read guide here.