Formbuilder

Configuration

Basics

The config-file is usually stored under: ./config/config.json

It controls how the form looks and behaves. In most cases it's the only thing that should ever be touched.

Structure

Root-Object:
{
    "controls" : false,
    "progressbar" : false,
    "success" : "success",
    "password" : <Password Object>,
    "templates": <Templates Object>
    "formhandler': [
        <Formhandler Object>,
        <Formhandler Object>,
        ....
    ],
    "pages": [
        <Page Object>,
        <Page Object>,
        ....
    ]
}

Root Object:

Name	Possible Values	Default Value	Description
controls	true, false	true	Enables/disables the display of dedicated control-buttons to switch forwards and backwards between pages. If set to false you have to define the buttons manually. (see Fieldtypes 'next' and 'back')
progressbar	true, false	true	Enables/disables the display of a bar ontop of the form that allows a visual representation of the progress the user made so far.
success	string	"success"	Defines the template to show when the form has been validated and all formhandlers successfully worked.
password	<Password Object>, false	false	Enables/disables functionality to password-protect the form.
templates	<Templates Object>	{}	Definitions for template-functionality, like template calcuations.
formhandler	Array of <Formhandler Object>	[]	A list of formhandlers that get passed the formdata and do something with it. The are called in the same order as they are defined.
pages	Array of <Page Object>	[]	A list of pages that contain the field-definitions.

Formhandler

A formhandler is an action that should be performed when data is recieved. That could be sending an email or saving it to a database.

...
"formhandler": [
    {
           "name" : "mysql",
           "config": {
                "server": "myserver.at",
                "user": "superimportantuser",
                "password": "supersecretpassword",
                "db": "supermightydatabase",
                "table": "supergreattable"
                  }
        },
        {
           "name" : "email",
           "config": {
                        "to": "important@email.com",
                        "from": "Great From-Title <info@email.com>",
                        "subject": "A great Subject to have",
                        "template": "email"
                     }
       },
      {
           "name" : "email_debug",
           "config": {
                        "to": "important@email.com",
                        "from": "Great From-Title <info@email.com>",
                        "subject": "A great Subject to have",
                        "template": "email"
                     }
       }
    }
]
...

Name	Possible Values	Default Value	Description
name (required)	string	-	The name of the formhandler that should work on the recieved data.
config (required)	List of string : string	-	A list of configuration options unique to the specified formhandler.

Formhandlers:

Email

Sends the data via email to specified recipients.

Name	Possible Values	Default Value	Description
to (required)	string	-	The recipient of the email. Can contain Template-Code
from	string	-	The sender of the email. Can contain Template-Code
subject (required)	string	-	The subject the email should have. Can contain Template-Code
template (required)	string	-	The template that defines the body of the email. Can contain Template-Code or a Template-Name

Email-Debug

The same as Email, but it does not send an email, and just prints the output. It can then be inspected in the Network-Tab of most common browsers.

Mysql

Saves the data in a specified mysql-database.

Name	Possible Values	Default Value	Description
server (required)	string	-	The server-adress or IP of the Database.
user (required)	string	-	The user that is used to connecting to the database.
password (required)	string	-	The password for the user.
db (required)	string	-	The name of the database that the data should be saved to.
table (required)	string	-	The name of the table that the data should be saved to.

Templates

Defines how templates should be handled across the library.

Example:

...
"templates" : {
    "calculations" : {
        <Template Calcuation Object>,
        <Template Calcuation Object>,
        ...
      }
    }
}
...

Name	Possible Values	Default Value	Description
calculations	List of <Template Calcuation Object>	{}	A list of objects to make operations on form-data and expose them as new template-variables. e.g. Multiply fields, Replace values, ... See \<Template Calculation Object> for more

Template Calculation Object

An object that defines a single operation that should be performed on a set of values and expose the result as template-variable.

The order of operations is important!

Example:

...
"calculations" : {
  "multiplied": {
    "method": "*",
    "fields" : ["fielda", "fieldb"]
  },
  "sumed": {
    "method": "+",
    "fields" : ["fielda", "fieldb"]
  },
  "replaced" : {
    "method": "replace",
    "replacements": {
      "string1" : "replacement1",
      "string2" : "replacement2"
    },
    "fields" : ["fielda"]
  },
  "exploded": {
    "method": "explode_count",
    "splitter": "+",
    "values" : ["fielda"]
  }
 }
...

Name	Available in	Possible Values	Default Value	Description
method (required)	all	"+", "*", "replace", "explode_count"	-	A list of objects to make operations on form-data and expose them as new template-variables. e.g. Multiply fields, Replace values, ... See \<Template Calculation Object> for more
fields (required)	all	Array of string	[]	A list of fieldnames that the operation should be performed on.
format	all	"price"	-	When passed, performes a formatting option on the final value that makes it look like a typical price (e.g. 12.345,67).
splitter	explode_count	string	-	Defines the character on which the field-value should be splitted.
replacements	replace	List of string : string	-	Defines which string should be replace by which string.

Methods:

Methods that can be applied to the values.

Name	method	Description
Sum	+	Sums up the field-values.
Multiply	*	Sums up the field-values.
Replace	replace	Replaces values like defined in replacements.
Explode Count	explode_count	Explodes a value on the character defined in splitter and returns how many pieces returned

Page Object

An object that defines a single page in a form.

...
"pages": [
    {
      "name": "Page 1",
      "pretext" : "This is a pretext",
      "fields" : [
        <Field Object>,
        <Field Object>,
        ...
      ]
    },
    {
      "name": "Page 2",
      "fields" : [
        <Field Object>,
        <Field Object>,
        ...
      ]
    }
 ]
 ...

Name	Possible Values	Default Value	Description
name	string	-	A name on top of the page. Represented as \<h2>
pretext	string	-	Inserts a \<div> with the class .pretext before the name. i18n-able
fields (required)	Array of <Field Object>	-	An array of fields to display on that page.

Field Object

An object that defines a single page in a form.

...
"fields" : [
    {
      "name" : "Super Text Field!",
      "type" : "text",
      "classes" : "class1 class2",
      "attributes" : {
         "attributename": "Attribute Value!",
         "attributename2": "Another Attribute Value"
      },
      "validation" : ["required"],
      "label" : false,
      "subtext" : "I am a description!",
      "props" : {
        ...
      },
      ...
    },
    ...
 ]
 ...

Name	Possible Values	Default Value	Description
name (required)	string	-	The name of the field. MUST BE UNIQUE
type (required)	string	-	The type of the field to display
classes	string	-	Add additional classes to the field.
attributes	JSON-Object	-	An object containting a key/value-pair that defines attributes.
validation	Array of string	-	An array of validations to run on the object. See Validations below.
label	string, false	-	Either disable the Label of the field, or show a name. i18nable
default	string	-	Sets a default value if applicable to the field-type.
subtext	string	-	Inserts a text below the field.
conditionals	JSON-Object	-	Refactor in Progress.
attachments	JSON-Object	-	Append attachments. Used by specific field-types.
props	JSON-Object	-	Configuration-Options for the specified field-type. See Field Types below.

Field Types

Available Fields Types

• text
• textarea
• paragraph
• breaker
• select
• radiogroup
• checkbox
• rating
• date
• upload
• submit
• forward
• backward

text

Displays a simple text field.

Config-Options:

Name	Possible Values	Default Value	Description
placeholder	string	-	Sets the placeholder-attribute on the field. i18n-able
maxlength	string	-	Sets the max-length-attribute on the field.

textarea

Displays a simple textarea field.

Config-Options:

Name	Possible Values	Default Value	Description
placeholder	string	-	Sets the placeholder-attribute on the field. i18n-able
rows	string	-	Sets the rows-attribute on the field.

paragraph

Display a \<p> with text inserted.

Name	Possible Values	Default Value	Description
text	string	-	The text to be shown in the \<p>. i18n-able

breaker

Displays a \<h3> containing the name of the field.

select

Displays a select-box.

Name	Possible Values	Default Value	Description
placeholder	string	-	If no default is set, this creates a non-selectable field. e.g. 'Please select...'.
values	Array of string	-	An array of values to be inserted as options.

radiogroup

Displays a group of radio-buttons.

Name	Possible Values	Default Value	Description
values	Array of string	-	An array of values to be inserted as buttons.

checkbox

Displays a checkbox.

Name	Possible Values	Default Value	Description
value	string [string, string]	-	Defines what values the field should show. i18n-able

value can take multiple forms:

A string:

"value1"

This will set the label of the checkbox to be value1 and the value will be set to true:

<input type="checkbox" value="true"/>
<label> value1 </label>

or a one-dimentional array:

["label1" , "value1"]

This allows for the value to be a different text then true.

<input type="checkbox" value="value1"/>
<label> label1 </label>

rating

Displays a group of ratingbuttons.

Name	Possible Values	Default Value	Description
values	number	-	Displays as many buttons as the number says

date

Displays a datepicker.

Name	Possible Values	Default Value	Description
multiple	true, false	false	Enables the ability to select multiple Days.
splitter	string	-	If multiple days are selected, what should seperate them?
days	Array of number	-	Exclude certain day from selection [0-6].
format	DateFormat	d. M, yyyy	Set a specific dateformat.

uses airpicker

upload

Displays a field where users can upload files. The urls of the files will be saved in a seperate 'files' array on the backend.

uses fineuploader

submit

Displays a Submit-Button to send the form.

Name	Possible Values	Default Value	Description
text	string	-	The Text on the button. i18n-able

forward

Display a button to navigate to the next page.

backward

Display a button to navigate to the previous page.

Password Object

Configuartion that allows you the protect a form with a password.

Example:

...
"password" : {
    "password" : "supersecretpassword",
    "fail_message" : "You shall not pass!",
    "template" : "password"
}
...

Name	Possible Values	Default Value	Description
password	string	""	The password that should unlock the form.
fail_message	string	"Wrong Password"	A message that is displayed when the user enters the wrong password
template	string	"password"	The template that defines the input-field. Gets passed %-msg-% and %-url-%

Special Template Syntax

Templates use a custom template engine. At the moment it is not a real language and more akin to a fancy regex and replace.

When the Templater parses a document it gets variables. These come from the data the user entered on the form, combined with defined calculations. The combination of those values is called templatevariables.

A templatevariables can be printed, or used for logical operations(if).

Every block of templatecode is terminated by defined opening and ending-tags. Default: %- -%
They can be changed in the Templates Config if need be.

Templatecode can be inserted into Strings or HTML and is used in many parts of the formbuilder. Like the template for successfully sending the form, or basically any field in the email-formhandler.

Printing Variables

Writing only the variablename just prints the value of that variable.

<div class="text">
    %-templatevariable-%
</div>

if

The if-structure allows to check for certain conditions like in other programming languages. It as a rather restricted features-set for now, and contains only the most basic functionalities.

An if-block always has the following signature:

%-if:<expression>-%
    // Content to display when true
%-endif:<expression>-%

!! Important: The start and the end-tag MUST both contain the same expression so the engine nows what endif belongs to which if. While the formbuilder will not crash from that, but the template will display as empty and output an errormessage (%-if:...-% - Limit reached). This is a constraint of it not beeing a fully fledged language.

\<expression>:

The expression can now be a magintude of things know from other programming languages to check for the state of a variable:

// isset or empty

%-if:variablename-%

// Returns false if 'variablename' is either emtpy ("") or not set at all.

// Equals

%-if:variablename==checkme-%

// Returns false if 'variablename' is not of value 'checkme'.

// Not equals

%-if:variablename!=checkme-%

// Returns false if 'variablename' is of value 'checkme'.

Multiple Expressions can also be chained with && and || to check for multiple states at once.

%-if:variablename||variablename2-%

// Returns true if 'variablename' OR 'variablename2' are set

%-if:variablename&&variablename2-%

// Returns true if 'variablename' AND 'variablename2' are set

%-if:variablename&&variablename!=idontwannabeshown-%

// Returns true if 'variablename' is set, not has the value 'idontwannabeshown'

The Templateengine beeing added to the Formbuilder - ca. 2020 colorized

Internationaqlization

Language Files

The Lang files can be found under ./lang/<language>.json.

They are simple json-files that contain a key/value-pair of translations.

Example:

{
    "variable1": "This is a text",
    "variable2": "This is another text",
    ....
}

The variablename can then be used together with a prefix in i18n-enabled config-fields.

config.json

i18n-enabled fields can be filled with a variablename instead of text. The default prefix ist $i18n_. The prefix can be chanced in the i18n.class.php file if needed.

Example:

{
   "name": "i18nable Textfield!",
   "type": "text",
   "label": "$i18n_labeltext",
   "props": {
      "placeholder": "$i18n_placeholder"
   }
}

The i18n-class will replace the text with the corresponding variables from the language-file. If it does not find a language or a corresponding Language File it will use de as a default language. If it does not find a de.json file it will just print the text in the field.

Templates

Templates get exposed a special variable that holds the current language.

%-if:i18n_lang==de-%
    <p>Deutscher Absatz</p>
%-endif:i18n_lang==de-%

%-if:i18n_lang==en-%
    <p>English paragraph</p>
%-endif:i18n_lang==en-%

Development

Formhandlers

A Formhandler is a class that implements a specific interface and is called by the formbuilder to do something with the recieved data.

interface iFormhandler
{
    public function __construct($_config, $handler_config);
    public function handle($data);
}

All Fromhandlers are located in /formhandler/

In the constructor it recives the config of the complete form, as well as the config for the specific Formhandler that is called. That's because a form can have multiple Formhandlers of the same type, but with different configurations attached. (Mostly when multiple emails should be send).

The handle-Method is called when the data is recieved. The input has the following structure:

$data[
    'fields' => [...], // An array of fieldvalues. Flattened.
    'files' => [...],  // An array of strings containing the urls for attached files, only present if there are files
    'raw' => [...]     // The raw data recieved from the $_POST
];

Validator

A Validator is a class that implements a interface and is used to determine if the value of a field is correct or wrong.

interface iValidator
{
    public static function validate($value, $field, $data = null);
    public static function message($value, $fieldname = null);
}

All Validators are located in /validator/

The validate-method recieves the Value and the Field Object, alongside the complete recieved formdata. It returns either true or false.

The message-Method is called when validate returned false and returns a errormessage, that is then sent to the frontend for display.

Field

Technically fields are dynamically depenency-injected. That means the class for a specific field is only called and an object created when needed. They use a shared interface with a method that is called:

interface iField
{
    public static function print($field, $page, $form_id);
}

All Fields are located in /fields/

The print-method recieves the Field Object, the pagenumber (starting with 0) it is on, and a form-id that is unique to this request.

From there on it is up to the class to print the necessary html.