What is TwitalBundle?¶

TwitalBundle is a Symfony bundle that integrates the Twital template engine into Synfony2. This enables you to use all Twig/Symfony functionalities with the Twital template engine language syntax.

To learn more about Twital, you can read the dedicated documentation.

Install¶

The recommended way to install TwitalBundle is via Composer:

composer require 'goetas/twital-bundle'

If you are using SymfonyFlex, the bundle will be automatically enabled and configured, otherwise follow the next steps.

Enable the bundle¶

To enable the bundle in the kernel:

<?php
// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new Goetas\TwitalBundle\GoetasTwitalBundle(),
        //..
    );
}

Configure¶

If you are using SymfonyFlex, the bundle is auto-configured and you can skip this step.

If you are using the symfony templating component (available in Symfony 2.x and 3.x), you have to enable the twital template engine inside your config.yml.

framework:
    templating:
        engines: ['twig', 'twital']

Optional Configurations¶

Here are some optional configurations for the bundle.

Source Adapters¶

By default Twital parses *.html.twital, *.xml.twital and *.xhtml.twital files. If you want you can customize the file types automatically parsed by Twital.

goetas_twital:
    # extra file extension matching
    source_adapter:
        - { service: twital.source_adapter.xml, pattern: ['/\.xml\.twital$/', '/\.atom\.twital$/'] }
        - { service: twital.source_adapter.html5, pattern: ['/\.html\.twital$/', '/\.htm\.twital$/'] }
        - { service: twital.source_adapter.xhtml, pattern: ['/\.xhtml\.twital$/'] }

Twital comes with the following source adapters that you can use to parse your template files:

twital.source_adapter.html5: used for most of the HTML-style templates
twital.source_adapter.xml: used for strictly XML-compliant templates
twital.source_adapter.xhtml: used for strictly XHTML-compliant templates (similar to XML but with some XHTML customizations)

Full Twig Compatibility¶

The following template is a valid Twig template, but is not a valid HTML5 document (the div tag can contain only attributes). Because of it, the Twital source adapters will not be able to parse the template.

<div {% if foo %} class="row" {% endif %}>
    Hello World
</div>

You can also enable a full Twig compatibility mode to allow this kind of templates.

goetas_twital:
    full_twig_compatibility: true

Integration¶

TwitalBundle comes with all features that are already supported by TwigBundle (forms, translations, assetic, routing, etc).

Contributing¶

This is an open source project - contributions are welcome. If your are interested, you can contribute to documentation, source code, test suite or anything else!

To start contributing right now, go to https://github.com/goetas/twital-bundle and fork it!

You can read some tips to improve your contributing experience looking into https://github.com/goetas/twital-bundle/blob/master/CONTRIBUTING.md present inside the root directory of Twital GIT repository.

Contents¶

Add your own Twital extension¶

The recommended way to add your TwitalExtension to Twital instance is registering it using the Symfony2 dependency injection system.

You have to add your extensions as services and tag them with the twital.extension tag.

Depending on your preferences, you can choose which syntax to adopt.

Using XML:

<service id="my.extension" class="...myExtensionClass...">
    <tag name="twital.extension" />
</service>

Using YAML:

services:
    my.extension:
        class: ...myExtensionClass...
        tags:
            - { name: twital.extension }

Using PHP:

<?php

 $container
    ->register('my.extension', '...myExtensionClass...')
    ->addTag('twital.extension')
;

Once you have added one of this configurations to your bundle, your extension should be available.

Add your own source adapter¶

The recommended way to add your TwitalSourceAdapter to TwitalLoader is registering it using the Symfony2 dependency injection system.

Depending on your preferences, you can choose which syntax to adopt.

Using XML:

<service id="my.source_adapter" class="...mySourceAdapterClass...">

</service>

Using YAML:

services:
    my.source_adapter:
        class: ...mySourceAdapterClass...

Using PHP:

<?php

 $container
    ->register('my.source_adapter', '...mySourceAdapterClass...')
;

Once you have added one of this configurations to your bundle, choose which file name pattern will activate the loader. To do this you have to edit your config.yml.

goetas_twital:
    source_adapter:
        my.source_adapter: ['/\.myext1\.twital$/', '/\.myext2\.twital$/']

Alternative way to add your source adapter¶

If you prefer to use the Symfony2 service tagging system, you can also use the following method:

You have to add your adapters as services and tag them with twital.source_adapter, and you also have to specify the pattern attribute.

Using XML:

<service id="my.source_adapter" class="...mySourceAdapterClass...">
    <tag name="twital.source_adapter" pattern="/\.xml\.twtal$/i" />
</service>

Using YAML:

services:
    my.source_adapter:
        class: ...mySourceAdapterClass...
        tags:
            - { name: twital.source_adapter, pattern: '/\.xml\.twtal$/i' }

Using PHP:

<?php

 $container
    ->register('my.source_adapter', '...mySourceAdapterClass...')
    ->addTag('twital.source_adapter', array('pattern' => '/\.xml\.twtal$/i'))
;

Tags provided¶

Here you can find the documentation for all attributes provided by TwitalBundle for a better integration of Synfony2 Functionalities.

`trans`¶

The t:trans attribute is an alias of the trans Symfony tag and allows you to translate the content of a node.

Let’s see how does it work:

<div t:trans="">
    Hello world
</div>

This option will allow Symfony to extract and translate the “Hello world” sentence.

Of course, you can also use any variable inside your text.

<div t:trans="{'%name%':'John'}">
    Hello %name%
</div>

You can also specify different domains for your translations.

<div t:trans="{'%name%':'John'}, 'app'">
    Hello %name%
</div>

Tip

See here http://symfony.com/it/doc/current/book/translation.html to learn more about the Symfony translation system.

`trans-n`¶

The t:trans-n attribute is an alias of the transchoice Symfony tag and allows you to translate the content of a node with plurals.

Let’s see how does it work:

<div t:trans-n="applesCount">
    {0} There are no apples|{1} There is one apple|]1,Inf] There are %count% apples
</div>

Of course, you can also use variables in your text.

<div t:trans-n="applesCount, {'%name%':'John'}">
    {0} %name% don't like apples|{1} %name% is eating one apple|]1,Inf] %name% is eating %count% apples
</div>

You can also specify different domains for your translations.

<div t:trans-n="applesCount, {'%name%':'John'}, 'app'">
    {0} %name% don't like apples|{1} %name% is eating one apple|]1,Inf] %name% is eating %count% apples
</div>

Tip

See here http://symfony.com/it/doc/current/book/translation.html to learn more about the Symfony translation system.

`trans-attr`¶

The t:trans-attr attribute is an alias of the trans Symfony tag, but it works only with HTML/XML attributes, and allows you to translate the content of one or more attributes.

The main advantage of t:trans-attr is the preservation of the original document structure: you do not need to change the value attribute with dirty code.

Let’s see how does it work:

<inpiut value="Apple" t:trans-attr="value"/>

This option will allow Symfony to extract and translate the “Apple” word.

Of course, you can also use variables inside your text.

<inpiut value="The pen is on the %place%" t:trans-attr="value:{'%place%':'table'}"/>

You can also translate more than one attribute on the same node.

<inpiut
    value="The pen is on the %place%"
    title="My favorite color is %color%"
    t:trans-attr="value:{'%place%':'table'}, title:{'%color%':'red'}"/>

You can also specify different domains for your translations.

<inpiut
    value="The pen is on the %place%"
    title="My favorite color is %color%"
    t:trans-attr="value:[{'%place%':'table'}, 'app'], title:[{'%color%':'red'}, 'colors']"/>

Tip

See here http://symfony.com/it/doc/current/book/translation.html to learn more about the Symfony translation system.

`trans-attr-n`¶

The t:trans-attr-n attribute is an alias of the transchoice Symfony tag, but it works only with HTML/XML attributes, and allows you to translate the content of one or more attribute using also plural forms.

Let’s see how does it work:

<inpiut
    value="There is one apple|There are %count% apples"
    t:trans-attr-n="value:[3, {'%count%':3}]" />

This option will allow Symfony to extract and translate the “There is one apple”, “There are %count% apples”, and “%count% apples” sentences.

Of course, you can also use variables in your text.

<inpiut
    value="%name% is eating one apple|%name% is eating %count% apples"
    t:trans-attr-n="value:[3, {'%count%':3, '%name%':'John'}]" />

You can also translate more than one attribute on the same node.

<inpiut
    value="%name% is eating one apple|%name% is eating %count% apples"
    title="There is one apple|There are %count% apples"
    t:trans-attr-n="value:[3, {'%count%':3, '%name%':'John'}], title:[3, {'%count%':3}]" />

You can also specify different domains for your translations.

<inpiut
    value="%name% is eating one apple|%name% is eating %count% apples"
    t:trans-attr-n="value:[3, {'%count%':3, '%name%':'John'}, 'app']" />

You can also combine plural and non-plural translations

<inpiut
    value="%name% is eating one apple|%name% is eating %count% apples"
    title="The pen is on the %place%"

    t:trans-attr="title:{'%place%':'table'}"
    t:trans-attr-n="value:[3, {'%count%':3, '%name%':'John'}]" />

Tip

See here http://symfony.com/it/doc/current/book/translation.html to learn more about the Symfony translation system.

Note¶

I’m sorry for the terrible english fluency used inside the documentation, I’m trying to improve it. Pull Requests are welcome.

What is TwitalBundle?¶

Install¶

Enable the bundle¶

Configure¶

Optional Configurations¶

Source Adapters¶

Full Twig Compatibility¶

Integration¶

Contributing¶

Contents¶

Add your own Twital extension¶

Add your own source adapter¶

Alternative way to add your source adapter¶

Tags provided¶

trans¶

trans-n¶

trans-attr¶

trans-attr-n¶

Note¶

`trans`¶

`trans-n`¶

`trans-attr`¶

`trans-attr-n`¶