Stanton commented 5 years ago

Context

The current implementation of Pulsar's Twig helpers (referred to as 'v2 helpers' in this document) provide a standardised API for building forms and introduced the concept of 'managed markup', allowing developers to create and deploy forms whose markup could be iteratively improved over time with accessibility improvements, bug fixes and feature requests without the need for product teams to revisit and make changes to multiple user interfaces.

Some time ago it was decided to standardise Jadu's product technology stack on Symfony.

Pulsar doesn't natively support Symfony forms, we need to add support at a core level to avoid separate implementations and fragmentation of feature support within each product. Accessibility, styling and markup should be managed centrally within Pulsar and shared across the platform.

To aid the successful rollout of Symfony forms across the platform we need to make it as easy for a developer to deploy a form which is automatically marked-up and styled according to Pulsar guidelines in much the same way was with v2 helpers.

The use of Symfony forms is at various states for each product.

CXM

Extensive Symfony forms (2.8) use with a custom Pulsar form theme (held in the CXM repo).

XFP

Starting to use Symfony forms (2.8) and helping develop a form theme within Pulsar based on the CXM/Pulsar form theme.

CMS

No current Symfony Forms in use.

Proposal

We will create a Pulsar Symfony Form Theme file within the Pulsar repository, drawing on the existing CXM version, to allow Symfony forms to use Pulsar markup schemes and styles, maintaining our desired level of accessibility and responsiveness.

A suite of PHPUnit tests will be written which test Symfony forms types against the expected output used by the current iteration of the Pulsar 'v2' helpers, we will aim for a 1:1 match between V2 helpers and Symfony forms, maintaining support for options such as help text, guidance popovers and appended/prepended information.

The form theme can be defined for all Symfony forms as a global setting ~~through the DEFAULT_FORM_THEME constant.~~ as a YAML configuration value:

# config/packages/twig.yaml
twig:
    form_themes: ['pulsar.html.twig']

It could also be included on a form-by-form basis by using the form_theme Twig tag:

{% form_theme myFormName '/pulsar/v2/pulsar.html.twig' %}

Further reading: https://symfony.com/doc/current/form/form_themes.html#symfony-built-in-form-themes

Initial exploration and findings

A Pulsar form theme has been created which allows basic form input types to be 'wrapped' with the expected Pulsar markup.

A PHPUnit test suite has been started which compares the output of a Symfony form type to that of a Pulsar v2 helper. At the time of writing this tests a simple text input, and a simple text input with help text as a POC.

There are a number of considerations at this stage:

1. Symfony form versions

CXM and XFP teams are currently using Symfony Forms version 2.8, this is an older unmaintained version. Any work that happens in Pulsar needs to be against whichever version product teams have deployed, however it does have a potential for wasted/duplicate effort if product teams are planning to update their forms version. A lot of this process also depends on product teams using the same version of Symfony forms. [Edit 15/4 15:23] It is planned for all products to upgrade to Symfony Forms 3.4, the Pulsar form theme will be written to support this version, with the goal of being ready in time when product teams update their Symfony version to allow to be supported.

If there's any potential or requirement for platform products to run different versions of Symfony forms at any time then Pulsar will need to cater for this, either by careful version numbering, or by moving Pulsar Forms into a separate dependency outside of Pulsar core that may have multiple supported versions.

It is expected that Pulsar will add the Symfony Forms package as a 'development dependency' and not attempt to bundle or ship this with the Pulsar repository. Jadu platform products will manage their own dependency for Symfony Forms.

2. Expected use of Symfony Forms by developers

We will require product teams to agree on a baseline implementation of how a given form will be defined within their products. This needs to include instances where child-forms are used, such as modals or dynamically revealed content.

3. Difference in option/attribute naming conventions

We will most likely change the way certain options are named so as not to cause confusion with the Symfony Forms documentation, the initial instinct is to move any Pulsar-specific options to data attributes, this allows us to intuit when an observed option is native/Pulsar, and avoid using option names which may be used/reserved by future Symfony versions.

Example:

V2

{{ 
    form.text({
        'label': 'My label',
        'name': 'form[myTextField]',
        'help': 'My help text'
    })
}}

Symfony

->add('myTextField', TextType::class, array(
    'label' => 'My label',
    'required' => false,
    'attr' => [
        'data-help-text' => 'My help text',
    ]
))

For field types which introduce specific functionality above and beyond simple form inputs, such as toggle switches or select2 dropdowns, these can be added as a new field type within Symfony for us to use and document.

4. Adding support for all Symfony input types

Pulsar will aim for 100% support for all documented Symfony input types, this will increase in difficulty when we add support for RepeatedType and CollectionType types.

5. Duplication across v2 helpers and Symfony forms

This change introduces a second place where markup is defined for form inputs, increasing the development overhead when making changes to form markup schemes in two places. There is no current plan to retire v2 helpers at this time and they will continue to be supported in tandem with Symfony forms until we reach the point where all new features being developed across-platform are built out with Symfony, then v2 helpers will be put into long-term maintenance mode.

6. Documentation

The new documentation site has the ability to display code examples for Twig and HTML strategies, this can also be used to display Symfony code examples, at some time this method will be the default option displayed, overriding the current default option showing Twig code.

All currently documented Form helper examples in Pulsar will need updating to include Symfony documentation.

Stories

960 Add support for Symfony Forms (Symfony 3.4)

979 Update to Twig 2.x

irinikp commented 4 years ago

Not sure if this is the right issue to ask this, but while trying to upgrade CXM into symfony 3.4, I've stumbled upon the need to update twig, but can't since pulsar has a requirement for an older version 1.21 while symfony 3.4 requires twig/twig: ^1.41|^2.10 https://packagist.org/packages/symfony/symfony#3.4.x-dev Are there any plans for upgrade of this dependency?

Stanton commented 4 years ago

@jamesjacobs can you work with @irinikp on this for CXM? Can't see an issue with us upgrading to latest 1.x if it's a requirement for Symfony 3.4, however we're not able to move to Twig 2.x at this time.