\formsManager

Handles record forms and simple forms display and processing

The formsManager class is responsible of the generation and processing of forms for the dbRecord and dbForm inherited objects. It parses the data array of the object and builds the form fields, ordering them by pannels. Then when the form is submited, it processes the fields, detects erroneous fields if any, then generates an object of the dbRecord or dbForm class with its values filled from the submited values.

Summary

Methods
Properties
Constants
__construct()
addFieldType()
prepareData()
editForm()
editRecord()
getMicroTemplateForm()
makePrefixPanel()
makePanels()
makeFieldset()
getFieldLabel()
preDisplay()
checkAndProcessForm()
processForm()
getTagAttributes()
isRequestSecured()
checkSecValue()
makeSecValue()
addCss()
addTopJs()
addBottomJs()
addPriorSendFormJs()
addPostSendFormJs()
$tagsToBeClosed
No constants found
No protected methods found
No protected properties found
N/A
getRowAttributes()
mergeDatas()
$cssList
$topJsList
$bottomJsList
$priorSendFormJS
$postSendFormJS
$fieldTypes
N/A

Properties

$tagsToBeClosed

$tagsToBeClosed : 

Type

$cssList

$cssList : 

Type

$topJsList

$topJsList : 

Type

$bottomJsList

$bottomJsList : 

Type

$priorSendFormJS

$priorSendFormJS : 

Type

$postSendFormJS

$postSendFormJS : 

Type

$fieldTypes

$fieldTypes : 

Type

Methods

__construct()

__construct() 

addFieldType()

addFieldType(  $fieldIdentifier,   $fieldClass,   $isDummy) 

Adds a new field type that can be displayed and processed by the forms manager. Must be invoked prior prepareData() sequence, such as in a plugin's index.php file.

Parameters

$fieldIdentifier

The name of the field to specify in $myForm->data['myFieldName']['dataType'] => 'myFieldIdentifier' in order to trigger this fieldClass

$fieldClass

the class which takes car of displaying the field (must implement mf/core/interfaces/formField.php interface). The name of the class is also the field identifier to specify in $myForm->data['myFieldName']['dataType'] => 'myFieldTypeClassName'

$isDummy

set to true if the field is not due to be stored in teh database

prepareData()

prepareData() 

editForm()

editForm(  $actionURL = null,   $actionName = 'processForm',   $callBackJSFuncName = '',   $formInstance,   $moduleName,   $subModuleName,   $showSubmitButton = true,   $submitButtonLabel = '',   $submitButtonClass = 'btn btn-primary col-lg-offset-2',   $useAJAX = true,   $advancedSettings = null,   $formAttributes = null,   $recordEditTableID = null) : string

Outputs the HTML form code for editing a dbForm subclassed object in the backend

Parameters

$actionURL

string URL where the form should be submited. Default value is SUB_DIR.'/mf/core/ajax-core-json.php'

$actionName

string value for the hidden field "action". Default value is 'processForm'

$callBackJSFuncName

string name of the JS function called on the client side which will deal with the AJAX answered data

$formInstance

form the form instance to display

$moduleName

string the calling module / plugin. Set value to '' for frontend forms.

$subModuleName

string the calling submodule / plugin.. Set value to '' for frontend forms.

$showSubmitButton

boolean whether to show or not a submitButton at the end of the form

$submitButtonLabel

string the text to display on the submit button

$submitButtonClass

string the classes to apply to the submit button

$useAJAX

boolean set to true to submit the form using AJAX. Default is true.

$advancedSettings

array specifies some additional form settings. These are the default advancedSettings :

   $advancedSettings = array(
      'PHPCallbackFunctionAfterSubmit'=>'',       //invokes the supplied phpFunction after submiting the form. The function is also invoked if saving the submission fails. The supplied function must have the following profile : myCallbackFunction($status (="success" or = "error"),$formObject); If a value is returned by the function, it will be supplied as a jsondata.phpResult value in the JSON response of the submission. It can then be handled using your own JSCallbackFunctionAfterSubmit javascript function
      'submitButtonOnClick' => "sendForm();",     //customize the submit button onclick action
      'showCancelButton' => false,           //set to true if you want to show a cancel button
      'cancelButtonLabel' => '',                  //customize the save close button label with the given text
      'cancelButtonOnClick' => 'history.go(-1);', //customize the cancel button onclick action usual values would be 'history.go(-1);' for non ajax forms and 'mf.dialogManager.closeLastDialog();' when the form has been opened using mf.dialogManager.openDialog() method.
   );
$formAttributes

array sets attributes for the "form" tag. When modifying, be carefull not to alter the default values you do not need to modify. default values are defined as is : array('method'=>'POST', 'onsubmit'=>'sendForm();', 'role'=>'form', 'class'=>'form-horizontal','enctype'=>'x-www-form-urlencoded')

$recordEditTableID

string specify a unique recordEditTableID you want to refresh after form submission here.

Returns

string —

the form html code

editRecord()

editRecord(  $record,   $moduleName,   $subModuleName = '',   $showSaveButton = true,   $showSaveCloseButton = true,   $showPreviewButton = true,   $showCloseButton = true,   $ajaxEditing,   $advancedSettings = null,   $formAttributes = null,   $recordEditTableID = null) 

Parameters

$record
$moduleName
$subModuleName
$showSaveButton
$showSaveCloseButton
$showPreviewButton
$showCloseButton
$ajaxEditing
$advancedSettings
$formAttributes
$recordEditTableID

getMicroTemplateForm()

getMicroTemplateForm(  $recordUid,   $recordClass,   $microtemplateKey,   $microtemplateIndex) 

Parameters

$recordUid
$recordClass
$microtemplateKey
$microtemplateIndex

makePrefixPanel()

makePrefixPanel(  $record,   $formID) : string

If there exists a tab with id='', it will be displayed before all the other tabs. This is intended to provide a possibility to show up some form fields outside the tabbed pannels set.

Those fields will thus remain displayed whatever is the tab shown below

Parameters

$record

object record to extract the data from

$formID

sets the unique ID of the form

Returns

string —

the HTML of the fieldset

makePanels()

makePanels(  $record,   $formID) : string

Builds the content of the tabbed panels featuring form fields

Parameters

$record

object record to extract the data from

$formID

sets the unique ID of the form

Returns

string —

the HTML of the fieldset

makeFieldset()

makeFieldset(array  $docHtml, array  $fieldsData, string  $recordClassName, array  $keysOfDatasInTab, string  $recordMode, array  $mainRecordData = NULL,   $formID,   $recordUid,   $microKey = '',   $microIndex = '',   $record) 

Builds the html for the form fields that displays in a record editing form. This is the heart of automatic form generation for record editing

Parameters

array $docHtml

The html array to append html output code to

array $fieldsData

The record data array to display the form for

string $recordClassName

The class name of the object currently displayed

array $keysOfDatasInTab

An array of the fields name to extract from the fieldsData and display in the $html (often not all fields are displayed)

string $recordMode

Allows alternating label names between 'record|' and 'template|' so the forms manager can figure when collecting the data if he has to store the data in a record column or in a more complicate structure inside a template_data type field

array $mainRecordData

When displaying $fieldsData from a template column, this function is called recursively with the content of the template_data supplied in the $fieldsData parameter. As a result, essential values from the root of the record's data structure such as $fieldsData['uid']['value'] (the current record uid) are no longer accessible. Passing the $fieldsData from the first function call in the $mainRecordData parameter ensures recursive function calls will still have access to the root of the record's data structure. This parameter is not required from the first function call.

$formID
$recordUid
$microKey
$microIndex
$record

getFieldLabel()

getFieldLabel(  $fieldData, string  $recordMode,   $key,   $recordClassName, boolean  $addBootStrapClasses = true) : string

Returns the <label> to be shown in front of the field

Parameters

$fieldData

field specification array

string $recordMode

Allows alternating label names between 'record|' and 'template|' so the forms manager can figure when collecting the data if he has to store the data in a record column or in a more complicate structure inside a template_data type field

$key

unique key name for current field, like 'country'

$recordClassName

class of the record holding the form / currently being edited

boolean $addBootStrapClasses

set to false if you need to get rid of class="col-lg-4 control-label" which is being inserted automatically in the

Returns

string

preDisplay()

preDisplay(  $key,   $value,   $fieldData,   $additionalValue = '') 

Parameters

$key
$value
$fieldData
$additionalValue

checkAndProcessForm()

checkAndProcessForm(array  $saveThoseFields = array()) : array

Checks the validity off all supplied fields and returns a populated record and a list of erroneous fields The returned record is not stored in the database. It is your responsability to store the record after having executed this function.

This will not be required for simple website forms (dbForms), but it will be for database object's editing forms (dbRecords).

Parameters

array $saveThoseFields

specifies a list of fields to be checked and saved. Those no present in the table will be ignored. This is usefull when you need to do a partial saving of a record's form content.

Returns

array —

returns an array with the following structure : array( record => an instance of the processed record, or 0 if the record failed to be processed errorFields => an array of the erroneous record keys names, all erroneous fields in the form ( 'key_name' => 'text_of_error_message' ) )

processForm()

processForm(\dbRecord  $record = null) : \the

Processes a form submission (requires the form to have been created using the formsManager or to comply with MindFlow form requirements) The returned record is not stored in the database. It is your responsability to store the record after having executed this function.

This will not be required for simple website forms (dbForms), but it will be for database object's editing forms (dbRecords).

Parameters

\dbRecord $record

speed optimization : if the record has already been loaded by the calling function (such as in checkAndProcessForm()), pass it as a parameter to prevent loading it again

Returns

\the —

record loaded and filled with values from the form submited, 0 if failure.

getTagAttributes()

getTagAttributes(  $tag,   $key,   $fieldData) : array

Retreives the the various attributes assigned to a given tag and separates the class value from the other attributes into an array so they are ready to insert into a form tag

Parameters

$tag

the tag identifier, such as 'div', 'label', or 'field' (this latest is for inputs)

$key
$fieldData

Returns

array —

$result['classes'] contains the class value (ex : 'col-lg-3') specified and $result['attributes'] contains the concatenated tag attributes arguments (ex: 'onclick="alert(\'hello\'); rel="external" '

isRequestSecured()

isRequestSecured() : boolean

Security function. Verifies the 'sec'/'fields' combo of a request in order to make sure the form hasn't been altered Will return false if the value of the 'fields' value is empty. It is recommended to always supply an 'action' field so the value of the sec/fields combo can not be reused for attacking other available actions.

Returns

boolean —

true if validation succeeds, false if the form was altered

checkSecValue()

checkSecValue(  $secHash,   $secKeys) 

Parameters

$secHash
$secKeys

makeSecValue()

makeSecValue(  $lockedKeys) 

Parameters

$lockedKeys

addCss()

addCss(  $uniqueKey,   $cssTag) 

Adds a CSS HTML tag to the current form

Parameters

$uniqueKey

string a unique identifier for the tag. If the addCss() method is called twice with the same $uniqueKey, the tag will be output once. But if the $uniqueKey is changed, incremented for exemple, both tags will be output

$cssTag

string the full css tag, such as ''

addTopJs()

addTopJs(  $uniqueKey,   $jsTag) 

Adds a script tag to the top of the rendered pages

Parameters

$uniqueKey

string a unique identifier for the tag. If the addTopJs() method is called twice with the same $uniqueKey, the tag will be output once. But if the $uniqueKey is changed, incremented for exemple, both tags will be output

$jsTag

string the full js tag, such as ''

addBottomJs()

addBottomJs(  $uniqueKey,   $jsTag) 

Adds a script tag to the bottom of the rendered pages

Parameters

$uniqueKey

string a unique identifier for the tag. If the addBottomJs() method is called twice with the same $uniqueKey, the tag will be output once. But if the $uniqueKey is changed, incremented for exemple, both tags will be output

$jsTag

string the full js tag, such as ''

addPriorSendFormJs()

addPriorSendFormJs(  $uniqueKey,   $jsCode) 

Adds a piece of javascript (DO NOT surround it with <script> tags) to execute before a form is sent. This is especially usefull for for formFields wich can run their custom JS code before form submission

Parameters

$uniqueKey

string a unique identifier for the tag. If the addPriorSendFormJs() method is called twice with the same $uniqueKey, the tag will be output once. But if the $uniqueKey is changed, incremented for exemple, both tags will be output

$jsCode

string custom field javascript processing code to add to the sendForm() method of forms

addPostSendFormJs()

addPostSendFormJs(  $uniqueKey,   $jsCode) 

Adds a piece of javascript (DO NOT surround it with <script> tags) to execute after a form has been sent. This is especially usefull for for formFields wich can run their custom JS code after form submission

Parameters

$uniqueKey

string a unique identifier for the tag. If the addPriorSendFormJs() method is called twice with the same $uniqueKey, the tag will be output once. But if the $uniqueKey is changed, incremented for exemple, both tags will be output

$jsCode

string custom field javascript processing code to add to the sendForm() method of forms

getRowAttributes()

getRowAttributes(  $key,   $fieldData) 

Parameters

$key
$fieldData

mergeDatas()

mergeDatas(  $templateArray,   $recordArray) 

Parameters

$templateArray
$recordArray