apollo29/forms-engine

0.1.2 2019-08-07 18:25 UTC

This package is auto-updated.

Last update: 2020-01-27 15:58:58 UTC


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.

Latest Version Build Status

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

PHP

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":"test@test.test"
        },
        "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;
  }
}