README

A Charcoal Charcoal service provider to add a form builder property input using form.io.

Table of Contents

• Installation
  • Dependencies
• Service Provider
  • Parameters
  • Services
• Configuration
• Usage
• Development
  • API Documentation
  • Development Dependencies
  • Coding Style
• Credits
• License

Installation

The preferred (and only supported) method is with Composer:

$ composer require locomotivemtl/charcoal-contrib-formio

Dependencies

Required

• PHP 5.6+: PHP 7 is recommended.

Configuration

Add the formio module to the modules list in the site's config file.

"modules": {
    "charcoal/formio/formio": {}
}

Usage

Three property type are provided by this package :

• formio/form (Form builder input)
• formio/schema (Form schema)
• formio/submission (To save a form submission)

"my_property": {
    "type": "formio/form",
    "l10n": false,
    "label": "My form property"
},

"my_property": {
    "type": "formio/schema",
    "l10n": false,
    "label": "My schema property"
},

"my_property_submission": {
      "type": "formio/submission",
      "l10n": false,
      "label": "My submission property"
}

Note that formio properties do not support l10n for now.

To update a form when saving the object you must call the method createOrUpdateRelation() on the property. This example saves or updates the form builder schema for a property called test. This code should be found in the object's controller.

/**
 * {@inheritdoc}
 *
 * @see StorableTrait::preSave()
 * @return boolean
 */
protected function preSave()
{
    $this->test = $this->p('test')->createOrUpdateRelation($this->test, null);

    return parent::preSave();
}

/**
 * {@inheritdoc}
 *
 * @see StorableTrait::preUpdate
 * @param array $properties Optional properties to update.
 * @return boolean
 */
protected function preUpdate(array $properties = null)
{
    $clone = clone $this; // Avoid calling `load()` on current object.
    $this->test = $this->p('test')->createOrUpdateRelation($this->test, $clone->load()->test);

    return parent::preUpdate($properties);
}

Development

To install the development environment:

$ composer install

To run the scripts (phplint, phpcs, and phpunit):

$ composer test

Resources

• The Form rendering documentation. Useful for front-end rendering of stored form.io structures. https://github.com/formio/formio.js/wiki/Form-Renderer

• The Form.io sdk documentation. http://formio.github.io/formio.js/app/sdk

• Front-end frameworks. https://help.form.io/developer/frameworks

API Documentation

• The auto-generated phpDocumentor API documentation is available at:
  https://locomotivemtl.github.io/charcoal-contrib-formio/docs/master/
• The auto-generated apigen API documentation is available at:
  https://codedoc.pub/locomotivemtl/charcoal-contrib-formio/master/

Development Dependencies

• [php-coveralls/php-coveralls][phpcov]
• [phpunit/phpunit][phpunit]
• [squizlabs/php_codesniffer][phpcs]

Coding Style

The charcoal-contrib-formio module follows the Charcoal coding-style:

• PSR-1
• PSR-2
• PSR-4, autoloading is therefore provided by Composer.
• phpDocumentor comments.
• phpcs.xml.dist and .editorconfig for coding standards.

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf.

Credits

• Locomotive

License

Charcoal is licensed under the MIT license. See LICENSE for details.