apollo29/forms-engine

FormsEngine

0.1.2 2019-08-07 18:25 UTC

Requires

• ext-json: ^1.5
• league/csv: ^9.2
• myclabs/php-enum: ^1.7
• nategood/httpful: ^0.2.20
• philipp15b/php-i18n: ^4.0
• phpcollection/phpcollection: ^0.5.0
• phpmailer/phpmailer: ^6.0
• phpoffice/phpspreadsheet: ^1.6
• rakibtg/sleekdb: ^1.0
• slim/slim: ^3.12
• tuupola/slim-jwt-auth: ^3.4
• twig/twig: ^2.0
• vlucas/phpdotenv: ^3.4

MIT

• Thomas D'Ascoli

README

Library to build forms on basis of Bootstrap 4 templates. This library includes customizable templates to use also other frameworks than Bootstrap, has multilanguage support and configurable ways to persist the form data.

• Install
• Usage
• Dependencies
• Configuration
  • set Prefix directory
  • get Configuration variable
• Translations
• Templates
• Option FormsEngine\Questions\Element\Option
• Elements FormsEngine\Questions\Element
  • Text, E-Mail, Number, Date, DateTime
  • Textarea
  • Hidden
  • Typeahead
  • Radio
  • RadioGroup
  • Checkbox
  • CheckboxGroup
  • Select
  • YesNo
  • Paragraph
  • Title
  • Button, Reset, Submit
• De-/Serialization of form definitions FormsEngine\Questions\Loader
• Pagination FormsEngine\Questions\Pagination
• API and Persistence FormsEngine\Answers\Persistence
  • CSV
  • E-Mail
  • JSON
  • JSONDB
  • MySQL
  • XLSX
  • Implement own Persistence

Install

Install using composer.

$ composer require apollo29/forms-engine

Usage

In your index.php you have to create a new FormsEngine instance first.

use FormsEngine\FormsEngine;

$engine = new FormsEngine();

Then add some Elements to create your form, and render it.

use FormsEngine\Questions\Element;

$r = $engine->renderer();

$r->add(new Element\Title('My First FormsEngine'));
$r->add(new Element\Text('Text Input Label','Text Input Placeholder','Text Input Helptext'));

$r->render();

Dependencies

A List of all Dependencies used by this Library.

CSS/JS

• bootstrap
• material
• jquery-typeahead
• Parsley.JS Input validation
• JOII (JavaScript Object Inheritance Implementation used for JS Objects of FormsEngine\Questions\Element

PHP

• twig/twig templating
• myclabs/php-enum
• phpcollection/phpcollection Sets, Sequences, Collections
• philipp15b/php-i18n i18n
• slim/slim RESTful
• nategood/httpful HTTP calls
• league/csv CSV
• rakibtg/sleekdb JSONDB
• phpmailer/phpmailer E-Mail
• phpoffice/phpspreadsheet Excel

Configuration

Set a session var with name configFile and the path and json-filename of your own config.json. See below the standardconfig.json as an example. If your happy with the standard config.json, you don't need to set the session var.

$_SESSION['configFile'] = __DIR__ . '/config.json';

config.json

{
    "addDirPrefix":true,
    "templateDir":"/Templates/",
    "langDir":"/Translations/",
    "form" : {
        "dir":"/forms/",
        "name":"defaultForm",
        "method":"ajax",
        "messageAfterSubmit":true,
        "createAnother":true,
        "addTimestamp":false
    },
    "pagination": {
      "active":true,
      "reset":false
    },
    "render" : {
        "load":"COOKIE",
        "config":"jsonForm"
    },
    "persistence" : {
        "type":"JSONDB",
        "email": {
            "emailTo":"[e-mail]"
        },
        "externalConfigs":[]
    }
}

set Prefix directory

todo

Config::setDirPrefix(__DIR__, "dir");
Config::setDirPrefix(__DIR__, "langDir");
Config::setDirPrefix(__DIR__, "templateDir");

get Configuration variable

todo

Config::getInstance()->get('form','name')

Translations

todo

Templates

todo

Option FormsEngine\Questions\Element\Option

Used for RadioGroup, CheckboxGroup, Typeahead and Select Elements.

Usage

$option = new Option();

$option->add('first',1);
$option->add('second',2);
$option->add('third',3);

Public Methods

• __construct() constructor
• add($label, $value, $selected = false) add values to Option Element
• addAll($options) add an Array of Option Elements
• all() get All Elements
• static create($label, $value, $selected = false) returns an Option Element
• serialize() get serialized Element for persistence, array with all attributes and values.
• static deserialize($object) deserialize Object to Element

Private Methods

• static camelCase($str, array $noStrip = []) get String camelCased, used for id

Elements FormsEngine\Questions\Element

All Elements are - mostly - standard HTML5 input fields and have the following methods:

Public Methods

• ___construct($label) when not otherwise stated, this is the default constructor
• serialize() get serialized Element for persistence, array with all attributes and values.
• prepare() see serialize()
• static deserialize($object) deserialize Object to Element
• toObjectVar($key, $value, $class = null) used to map an array to key/value of Element.
• script() get all JavaScript code to render.
• required() set Element as required
• readonly() set Element as readonly
• disabled() set Element as disabled
• inputmask($mask,$type = 'mask') set Inputmask (see Dependencies for further Documentation)
• addStyle($style)add additional CSS class
• attr($attr, $value) add attributes

Private Methods

• setId($id,$isName = false) set id and optional also name attribute
• setName($name) set name attribute
• static camelCase($str, array $noStrip = []) get String camelCased, used for setId and setName

Text, E-Mail, Number, Date, DateTime

Extends from Input

Usage

$text   = new Text('Label','Placeholder','Helptext');

$email  = new Email('Label','Placeholder','Helptext');

$number = new Number('Label','Placeholder','Helptext');

$date     = new Date('Label','Placeholder','Helptext');
$dateTime = new DateTime('Label','Placeholder','Helptext');

Template/HTML (type is different according to Element)

<div class="form-group">
  <label for="label">Label</label>
  <input type="text" class="form-control" id="label" name="label" placeholder="Placeholder" aria-describedby="label-helptext">
  <small id="label-helptext" class="form-text text-muted">Helptext</small>
</div>

Public Methods

• __construct($label, $placeholder = null, $helptext = null) constructor
• render($twig) render Method for Twig Template Engine

Textarea

Extends from Input

Usage

$element = new Textarea('Label','Helptext');

Template/HTML

<div class="form-group">
  <label for="label">Label</label>
  <textarea
    class="form-control"
    id="label"
    name="label"
    rows="3"
    aria-describedby="label-helptext">
  </textarea>
  <small id="label-helptext" class="form-text text-muted">Helptext</small>
</div>

Public Methods

• __construct($label, $helptext = null) constructor
• render($twig) render Method for Twig Template Engine

Hidden

Extends from Element

Usage

$element = new Hidden('id','Value');

Template/HTML

<input
    type="hidden"
    id="id"
    name="id"
    value="Value">

Public Methods

• __construct($id, $value = null) constructor
• render($twig) render Method for Twig Template Engine

Typeahead

Extends from Text

Usage, with Array

$options = array('first','second','third','fourth');

$array = new Typeahead('Label',$options,'Placeholder','Helptext');

Usage, with Option. See Option for more information

$option = new Option();
$option->add('Germany','GER');
$option->add('Italy','ITA');
$option->add('Switzerland','SUI');

$option = new Typeahead('Label',$option,'Placeholder','Helptext');

Template/HTML

<div class="form-group typeahead__container">
  <label for="label">Label</label>
  <input type="text" class="form-control" id="label" name="label" placeholder="Placeholder" aria-describedby="label-helptext" autocomplete="off">
  <small id="label-helptext" class="form-text text-muted">Helptext</small>
</div>

Public Methods

• __construct($label, $options, $placeholder = null, $helptext = null) constructor
• render($twig) render Method for Twig Template Engine

Radio

Extends from Element

Usage

$element = new Radio('Label','Value','Name',true);

Template/HTML

<div class="form-group">
  <div class="custom-control custom-radio">
    <input
      type="radio"
      class="custom-control-input"
      id="Label"
      value="Value"
      name="Name"
      checked="checked">
    <label class="custom-control-label" for="Label">Label</label>
  </div>
</div>

Public Methods

• __construct($label, $value, $name, $checked = false) constructor
• render($twig) render Method for Twig Template Engine

RadioGroup

Extends from Element

Usage, see Option for more information

$option = new Option();
$option->add('first',1);
$option->add('second',2);
$option->add('third',3);

$element = new RadioGroup('Label',$option,'Name');

Template/HTML

<div class="form-group">
  <label for="label">Label</label>
  <div class="mt-2" id="label">
    <!-- Renders all Option Elements -->
    <div class="custom-control custom-radio">
        <input
            type="radio"
            class="custom-control-input"
            id="first"
            name="Name"
            value="1">
        <label class="custom-control-label" for="first">first</label>
    </div>
    <!-- /End -->
  </div>
</div>

Public Methods

• __construct($label, $options, $name = null) constructor
• render($twig) render Method for Twig Template Engine

Checkbox

Extends from Element

Usage

$element = new Checkbox('Label','Value',true);

Template/HTML

<div class="form-group">
  <div class="custom-control custom-checkbox">
    <input
      type="checkbox"
      class="custom-control-input"
      id="Label"
      value="Value"
      checked="checked">
    <label class="custom-control-label" for="Label">Label</label>
  </div>
</div>

Public Methods

• __construct($label, $value, $checked = false) constructor
• render($twig) render Method for Twig Template Engine

CheckboxGroup

Extends from Element

Usage, see Option for more information

$option = new Option();
$option->add('first',1);
$option->add('second',2);
$option->add('third',3);

$element = new CheckboxGroup('Label',$option);

Template/HTML

<div class="form-group">
  <label for="label">Label</label>
  <div class="mt-2" id="label">
    <!-- Renders all Option Elements -->
    <div class="custom-control custom-checkbox">
        <input
            type="checkbox"
            class="custom-control-input"
            id="first"
            name="first"
            value="1">
        <label class="custom-control-label" for="first">first</label>
    </div>
    <!-- /End -->
  </div>
</div>

Public Methods

• __construct($label, $options) constructor
• render($twig) render Method for Twig Template Engine
• elementKeys() all Option Keys

Select

Extends from Element

Usage, see Option for more information

$option = new Option();
$option->add('first',1);
$option->add('second',2);
$option->add('third',3);

$element = new Select('Label',$option,true,'Helptext');

Template/HTML

<div class="form-group">
  <label for="label">Label</label>
  <select class="custom-select" id="label" name="label">
    <!-- Renders all Option Elements -->
    <option value="1">first</option>
    <!-- /End -->
  </select>
  <small id="label-helptext" class="form-text text-muted">Helptext</small>
</div>

Public Methods

• __construct($label,$options,$nullable = false,$helptext = null) constructor
• render($twig) render Method for Twig Template Engine

YesNo

Renders a Yes/No Radio Element, with "Yes" / "No" or boolean values.

Extends from ElementGroup

Usage

$element = new YesNo('Name',true);

Template/HTML, see Radio Element

Public Methods

• __construct($name, $booleans = false) constructor
• render($twig) render Method for Twig Template Engine

Paragraph

Extends from Element

Usage

$element = new Paragraph('Title','Description');

Template/HTML

<h2>Title</h2>
<p>Description</p>

Public Methods

• __construct($title=null,$description=null) constructor
• render($twig) render Method for Twig Template Engine

Title

There is only one Title Element allowed per Form.

Extends from Paragraph

Usage

$element = new Title('Form Title','Description');

Template/HTML

<h1>Form Title</h1>
<p>Description</p>

Public Methods

• __construct($title,$description=null) constructor
• render($twig) render Method for Twig Template Engine

Button, Reset, Submit

See #26.

Extends from Element

Usage

$button       = new Button('Button');

$reset        = new Reset('Reset'); // Shorthand
$resetButton  = new Button('Reset Button');

$submit       = new Submit('Submit'); // Shorthand
$submitButton = new Button('Submit Button');

Template/HTML

<button type="button" class="btn btn-secondary">
  Button
</button>

<button type="reset" class="btn btn-light">
  Reset
</button>

<button type="submit" class="btn btn-primary">
  Submit
</button>

Public Methods

• __construct($label,$buttonType=null) constructor
• render($twig) render Method for Twig Template Engine

De-/Serialization of form definitions FormsEngine\Questions\Loader

todo

Pagination FormsEngine\Questions\Pagination

todo

API and Persistence FormsEngine\Answers\Persistence

todo

CSV

E-Mail

JSON

JSONDB

MySQL

XLSX

Implement own Persistence

namespace Somewhere\Persistence;

use \FormsEngine\Answers\Persistence\Persistence;

class TestPersistence implements Persistence {

  public static function persist($name, $data){
    echo 'Insert Data into '.$name.': '.\implode(',',$data);
  }

  public static function load($name){
      echo 'Load Data from '.$name;
  }
}