Script API Reference
From FacileWiki
+++ UNDER CONSTRUCTION - STATUS OF 1.4.4 +++
ff_currentheight
- Description
- A variable holding the the displayed form height in pixels. Consider this variable read-only for custom forms, and use function ff_resizepage() to change the current page height instead of directly changing the value of the variable.
- Examples
// show the current page height alert(ff_currentheight);
- Related Links
- Location
- Built-in variable in facileforms.process.php
- Version Info
- Available in all versions
ff_currentpage
- Description
- A variable holding the number of the currently displayed page. Consider this variable read-only for custom forms, and use function ff_switchpage() to change the current page number instead of directly changing the value of the variable.
- Examples
// show the current page number alert(ff_currentpage);
- Related Links
- <a href="content/view/58/115/">ff_lastpage</a><a href="content/view/60/115/">ff_switchpage</a>
- Location
- Built-in variable in facileforms.process.php
- Version Info
- Available in all versions
ff_elements
- Description
- ff_elements is an array with information about all elements of the form. The array is created by the form processor and should not be modified by custom forms. Use the functions listed in the related links to query the list.
- Examples
var ff_elements = [
['ff_elem876', 'ff_div876', 'ftb_intro', 1, 876],
['ff_elem878', 'ff_div878', 'ftb_tag', 1, 878],
['ff_elem879', 'ff_div879', 'ftb_post', 1, 879],
['ff_elem877', 'ff_div877', 'ftb_taglist', 1, 877],
['ff_elem880', 'ff_elem880', 'ftb_task', 1, 880],
['ff_elem881', 'ff_div881', 'ftb_mtabletxt', 2, 881],
['ff_elem882', 'ff_div882', 'ftb_ctable', 2, 882],
['ff_elem883', 'ff_div883', 'ftb_ntable', 3, 883]
];
- Related Links
- Location
- Built-in variable in facileforms.process.php
- Version Info
- Available in all versions
ff_getDivByName(name)
- Description
- Get the wrapping div of a form element by the element name.
- Parameters
- name
- The name of the element as entered in the element editor.
- Return Value
- DIV object, or null in case no element with that name is found.
- Examples
// hide icon
var e = ff_getElementByName('myicon');
e.style.display = 'none';
- Related Links
- Location
- Built-in function in facileforms.process.php
- Version Info
- Available in all versions
ff_getElementByIndex(index)
- Description
- Get one of the form elements by it's index in the ff_elements table.
- Parameters
- index
- The 0-based index of the element within the ff_elements table.
- Return Value
- Element object, or null in case of invalid element index.
- Examples
// get value of element with index 2 var e = ff_getElementByIndex(2); var val = e.value;
- Related Links
- Location
- Built-in function in facileforms.process.php
- Version Info
- Available in all versions
ff_getElementByName(name)
- Description
- Get one of the form elements by it's name.</p>
- Parameters
- name
- The name of the element as entered in the element editor.
- Return Value
- Element object, or null in case no element with that name is found.
- Examples
// set value
var e = ff_getElementByName('email');
e.value = 'john.doe@hisdomain.com';
- Related Links
- Location
- Built-in function in facileforms.process.php
- Version Info
- Available in all versions
ff_getForm()
- Description
- Get the current form object.
- Parameters
- none.
- Return Value
- Current form object.
- Examples
// submit this form var myform = ff_getForm(); myform.submit();
- Related Links
- Location
- Built-in function in facileforms.process.php
- Version Info
- Available in all versions
ff_getIdByName(name)
- Description
- Get the ID of a form element by the element name.
- Parameters
- name
- The name of the element as entered in the element editor.
- Return Value
- ID of the element, or null in case no element with that name is found.
- Examples
alert( 'myicon has id = '+ff_getIdByName('myicon') );
- Related Links
- Location
- Built-in function in facileforms.process.php
- Version Info
- Available in all versions
ff_getPageByName(name)
- Description
- Get the page number of a form element by the element name.
- Parameters
- name
- The name of the element as entered in the element editor.
- Return Value
- Page number of the element, or null in case no element with that name is found.
- Examples
// switch to the page with element 'order'
ff_switchpage( ff_getPageByName('order') );
- Related Links
- Location
- Built-in function in facileforms.process.php
- Version Info
- Available in all versions
ff_homepage
Description
A variable holding the url of the homepage.
Examples
// show the home page url alert(ff_homepage);
Related Links
Location
Built-in variable in facileforms.process.php
Version Info
Available in all versions
ff_images
Description
A variable holding the image url as defined in the facile forms configuration.
Examples
// show the image url alert(ff_images);
Related Links
Location
Built-in variable in facileforms.process.php
Version Info
Available in all versions
ff_initialize(condition)
Description
This is an internal function handling form and page initialization scripts. It gets called automaticly upon form or page entry by the form processor and needs normally not be called by custom form scripts.
At form entry this function calls the form initialization script if any. At page entry it calls the defined init scripts of all elements on the current page.
Parameters
- condition
- Either 'formentry' or 'pageentry'.
Return Value
none.
Examples
none.
Related Links
<a href="content/view/80/115/">element initialization script</a>, <a href="content/view/78/115/">form initialization script</a>
Location
Built-in function in facileforms.process.php
Version Info
Available in all versions
ff_lastpage
Description
A variable holding the last page number of the form.
Examples
// show the last page number alert(ff_lastpage);
Related Links
<a href="content/view/57/115/">ff_currentpage</a>, <a href="content/view/60/115/">ff_switchpage</a>
Location
Built-in variable in facileforms.process.php
Version Info
Available in all versions
ff_nextpage()
Description
Switch the next page in multipage forms. This is a shortcut for ff_switchpage(ff_currentpage+1).
Parameters
none
Return Value
none
Examples
// switch to next ff_nextpage();
Related Links
<a href="content/view/57/115/">ff_currentpage</a>, <a href="content/view/58/115/">ff_lastpage</a>, <a href="content/view/60/115/">ff_switchpage</a>, <a href="content/view/83/115/">ff_page1...3</a>, <a href="content/view/82/115/">ff_previouspage</a>
Location
Standard library in package FF
Version Info
Available in all versions
ff_page1() ... ff_page3()
Description
Switch the page number 1, 2 or 3 in multipage forms. This are shortcuts for ff_switchpage(1) to ff_switchpage(3).
Parameters
none
Return Value
none
Examples
// switch to page 2 ff_page2();
Related Links
<a href="content/view/57/115/">ff_currentpage</a>, <a href="content/view/58/115/">ff_lastpage</a>, <a href="content/view/60/115/">ff_switchpage</a>, <a href="content/view/82/115/">ff_previouspage</a>, <a href="content/view/81/115/">ff_nextpage</a>
Location
Standard library in package FF
Version Info
Available in all versions
ff_param
Description
Object holding all GET and POST parameters passed into the form that are starting with ff_param.
Examples
// Display ff_param_foo
if (ff_param.foo)
alert('ff_param_foo was given with value '+ff_param.foo);
else
alert('ff_param_foo was not passed in as GET or POST value.');
Related Links
Location
Built-in variable in facileforms.process.php
Version Info
Available from 1.4 up
ff_previouspage()
Description
Switch the previous page in multipage forms. This is a shortcut for ff_switchpage(ff_currentpage-1).
Parameters
none
Return Value
none
Examples
// switch to previous page ff_previouspage();
Related Links
<a href="content/view/57/115/">ff_currentpage</a>, <a href="content/view/58/115/">ff_lastpage</a>, <a href="content/view/60/115/">ff_switchpage</a>, <a href="content/view/83/115/">ff_page1...3</a>, <a href="content/view/81/115/">ff_nextpage</a>
Location
Standard library in package FF
Version Info
Available in all versions
ff_redirect(url, target='self', method='post')
Description
Redirects the browser to a new URL. The function is capable of both, passing parameters in POST as well as in GET methode. In both modes the parameters are appended to the URL in GET style, they will automatically be converted to POST variables in case.
Parameters
- url
- The URL to redirect to including parameters (if any) in GET style, for example
http://anysite.com/index.php?param1=blah¶m2=foo. - target
- 'self', 'parent', 'top', 'blank'(*)
(*) only supported in POST method. - method
- 'get', 'post'
Return Value
none
Examples
// redirect this window to facile forms site
ff_redirect('http://www.facileforms.biz');
// redirect top window
ff_redirect('http://www.facileforms.biz','top');
// redirect parent window adding parameters in get mode
ff_redirect('http://mydomain.net/index.php?myparam=blah','parent','get');
Related Links
<a href="content/view/50/115/">ff_redirectParent</a>, <a href="content/view/51/115/">ff_redirectTop</a>, <a href="content/view/52/115/">ff_returnHome</a>
Location
Built-in function in facileforms.js
Version Info
Available in 1.4.0 and up
ff_redirectParent(url, method='post')
Description
Conditionally redirects the browser to a new URL. If the form is running in iframe, the parent window will be redirected, otherwise the current (self) window. The function is capable of both, passing parameters in POST as well as in GET method. In both modes the parameters are appended to the URL in GET style, they will automatically be converted to POST variables in case.
Parameters
- url
- The URL to redirect to including parameters (if any) in GET style, for example
http://anysite.com/index.php?param1=blah¶m2=foo. - method
- 'get', 'post'
Return Value
none
Examples
// redirect to facile forms site
ff_redirectParent('http://www.facileforms.biz');
// redirect parent window adding parameters in get mode
ff_redirectParent('http://mydomain.net/index.php?myparam=blah','get');
Related Links
<a href="content/view/49/115/">ff_redirect</a>, <a href="content/view/51/115/">ff_redirectTop</a>, <a href="content/view/52/115/">ff_returnHome</a>
Location
Built-in function in facileforms.js
Version Info
Available in 1.4.0 and up
ff_redirectTop(url, method='post')
Description
Redirects the browser top window to a new URL. The function is capable of both, passing parameters in POST as well as in GET method. In both modes the parameters are appended to the URL in GET style, they will automatically be converted to POST variables in case.
Parameters
- url
- The URL to redirect to including parameters (if any) in GET style, for example
http://anysite.com/index.php?param1=blah¶m2=foo. - method
- 'get', 'post'
Return Value
none
Examples
// redirect to facile forms site
ff_redirectTop('http://www.facileforms.biz');
// redirect parent window adding parameters in get mode
ff_redirectTop('http://mydomain.net/index.php?myparam=blah','get');
Related Links
<a href="content/view/49/115/">ff_redirect</a>, <a href="content/view/50/115/">ff_redirectParent</a>, <a href="content/view/52/115/">ff_returnHome</a>
Location
Built-in function in facileforms.js
Version Info
Available in 1.4.0 and up
ff_resizepage(mode, value)
Description
Resizes the currently displayed form page. Normally this needs not be called by custom forms since pages get automaticly resized when they are displayed first. However in case a custom form dynamically adds, moves or resizes elements with javascript (example: adding rows to a query list) it may be necessary to call ff_resizepage() after.
Parameters
- mode
- There are 3 modes available:
0 - Fixed height mode.
1 - Calculate size by elements on the current page. (auto)
2 - Calculate size by elements on all pages. (automax). - value
- The interpretation of value depends on the mode parameter:
For mode = 0 it is the total height of the page measured in pixels.
For mode > 0 it is an additional bottom margin measured in pixels.
Return Value
none
Examples
// resize current page to 1000 pixels ff_resizepage(0, 1000); // auto resize current page with a bottom margin of 20 pixels ff_resizepage(1, 20);
Related Links
<a href="content/view/67/115/">ff_currentheight</a>
Location
Built-in function in facileforms.process.php
Version Info
Available in all versions
ff_returnHome()
Description
Redirects to the home page of the site. In case the form is running in iframe, the parent window will be redirected, otherwise the current window.
Parameters
none
Return Value
none
Examples
// redirect to home page ff_returnHome();
Related Links
<a href="content/view/49/115/">ff_redirect</a>, <a href="content/view/50/115/">ff_redirectParent</a>, <a href="content/view/51/115/">ff_redirectTop</a>
Location
Built-in function in facileforms.js
Version Info
Available in 1.4.0 and up
ff_submitForm()
Description
Submits the current form.
After calling this javascript function no other javascript will be executed. Upon completion of the submit processing on the server, the form processor will once again send this form (*) to the browser. However to distinguish from a normal form call, the form submitted script will be executed instead of the form initialization script. So for example to switch to another page by javascript after submitting the form, put a ff_switchpage(pageno) call not after the ff_submitform() call, but into the form submitted script.
(*) Unless the submit pieces do a redirection to another form
Parameters
none.
Return Value
Function does not return, see description above.
Examples
// submit this form ff_submitForm();
Related Links
<a href="content/view/78/115/">form initialization script</a>, <a href="content/view/55/115/">form submitted script</a>
Location
Built-in function in facileforms.process.php
Version Info
Available in all versions
ff_switchpage(pagenr)
Description
Switch the displayed page in multipage forms. The new page number must be in the range 1 ... ff_lastpage und not equal ff_currentpage, otherwise the function does not do anything.
Parameters
- pagenr
- The new page number to switch to.
Return Value
none
Examples
// switch to page 2 ff_switchpage(2);
Related Links
<a href="content/view/57/115/">ff_currentpage</a>, <a href="content/view/58/115/">ff_lastpage</a>
Location
Built-in function in facileforms.process.php
Version Info
Available in all versions
ff_traceWindow()
Description
This is an internal function used by the facile forms processor to display the trace buffer in a pop-up window. Not intended for use by custom forms.
Parameters
none
Return Value
none
Examples
Related Links
none
Location
Built-in function in facileforms.js
Version Info
Available in 1.4.0 and up
ff_trim(string)
Description
Removes whitespace (newline, carriage return, tab) from begin and end of a string.
Parameters
- string
- The string to be processed.
Return Value
The string with whitespace removed from begin and end.
Examples
var s1 = ' xyz\n'; var s2 = ff_trim(s1); // s2 = 'xyz';
Related Links
Location
Built-in function in facileforms.js
Version Info
Available in 1.4.0 and up
ff_validation(page)
Description
Validates all elements of a distinct page or of all pages. In case all elements validated an empty string is returned, otherwise a string with the error message(s) to display. In case one or more element(s) failed, ff_validationFocusName will be set to the name of the first failing element and ff_validationFocus() should be called to switch to the respective page and set the focus onto that element.
Parameters
- page
- The new page number to validate, or 0 if all pages shall be validated.
Return Value
Empty string is all passed. Error message if any element validation failed.
Examples
function ff_validate_submit(element, action)
{
var error = ff_validation(0);
if (error != '') {
alert(error);
ff_validationFocus();
} else
ff_submitForm();
} // ff_validate_submit
Related Links
<a href="content/view/61/115/">Validation Script</a>, <a href="content/view/64/115/">ff_validationFocus</a>, <a href="content/view/63/115/">ff_validationFocusName</a>
Location
Built-in function in facileforms.process.php
Version Info
Available in all versions
ff_validationFocus(name)
Description
This function has 2 different uses:
- Within a validation script this function must be called with the name of the element in case the validation fails. The name of the first failing element will then be memorized in ff_validationFocusName.
- After a failing validation this function should be called without any parameter. It will switch to the page of the the first failing element and set the focus into that element.
Parameters
- elementname
- The name of the element when used withing a validation script. Ommit this parameter when the function is called after a failing validation to set the focus onto the first failing element.
Return Value
none.
Examples
function ff_validate_submit(element, action)
{
var error = ff_validation(0);
if (error != '') {
alert(error);
ff_validationFocus();
} else
ff_submitForm();
} // ff_validate_submit
Related Links
<a href="content/view/61/115/">Validation Script</a>, <a href="content/view/62/115/">ff_validation</a>, <a href="content/view/63/115/">ff_validationFocusName</a>
Location
Built-in function in facileforms.process.php
Version Info
Available in all versions
ff_validationFocusName
Description
A variable holding the name of the first failing element during the validation process. This variable is not intended to be used by custom forms. Use the related functions instead.
Examples
Related Links
<a href="content/view/61/115/">Validation Script</a>, <a href="content/view/62/115/">ff_validation</a>, <a href="content/view/64/115/">ff_validationFocus</a>
Location
Built-in variable in facileforms.process.php
Version Info
Available in all versions
Element Initializazion
Description
The Initialization Script is executed for every element whenever a page is displayed, either when the form gets initially displayed, or when the page gets switched.
The name of the initialization script must be ff_elementname_init.
Note that if you enable to switch forth and back to the page, the initialization script will be executed every time the page is redisplayed and not only the first time. If you in such case want to only once run initialization instead of every time, either check the condition parameter to be 'formentry' or put your code into the form initialization script instead.
Parameters
- element
- The validated form element object.
- condition
- The condition is either 'formentry' or 'pageentry'.
Return Value
none.
Examples
function ff_myelement_init(element, condition)
{
// initialize with user id at form entry
if (condition == 'formentry')
element.value = '<?php global my; return $my->id; ?>';
} // ff_myelement_init
Related Links
<a href="content/view/78/115/">form initialization script</a>, <a href="content/view/79/115/">ff_initialize</a>
Location
Library function or custom code defined in element settings.
Version Info
Available in all versions
Element Validation
Description
The Validation Script is executed for every element whenever ff_validation() is called either directly or indirectly by library functions such as ff_validate_nextpage() or ff_validate_submit(). The function must check if required conditions are met and return either an empty string if all is ok, or an error message respectively. In addition to the error message also the function ff_validationFocus() must be called when the conditions were not met.
Parameters
- element
- The validated form element object.
- message
- The custom validation fail message entered in the element settings. This is used primarly for library functions so the message needs not be hardcoded.
Return Value
Empty string if passed, error message if failed.
Examples
function ff_integer_or_empty(element, message)
{
if (element.value != '') {
var ex = /(^-?\d\d*$)/;
if (!ex.test(element.value)) {
if (message=='') message = element.name+" must be integer.\n";
ff_validationFocus(element.name);
return message;
} // if
} // if
return '';
} // ff_integer_or_empty
Related Links
<a href="content/view/62/115/">ff_validation</a>, <a href="content/view/64/115/">ff_validationFocus</a>, <a href="content/view/63/115/">ff_validationFocusName</a>
Location
Library function or custom code defined in element settings.
Version Info
Available in all versions
Form Initialization
Description
The Initialization Script is executed upon normal form entry.
The name of the initialization script must be ff_formname_init.
Parameters
none.
Return Value
none.
Examples
function ff_MyForm_init()
{
if (ff_param.foo)
alert('You called this form with ff_param_foo='+ff_param.foo);
} // ff_MyForm_init
Related Links
<a href="content/view/80/115/">element initialization script</a>, <a href="content/view/55/115/">form submitted script</a>, <a href="content/view/79/115/">ff_initialize</a>
Location
Library function or custom code defined in form settings.
Version Info
Available in all versions
Form Submitted
Description
The Submitted Script is executed upon return from submitting in place of the Initialization Script which gets executed upon "normal" form entry.
Parameters
- status
The return status set by the submit piece, either by the internal routines for saving records/subrecords and mailing, or by custom pieces. Status codes below 1000 are reserved for the internal routines:
- FF_STATUS_OK <dd>No errors occured.</dd>
- FF_STATUS_UNPUBLISHED <dd>Trying to submit a unpublished form.</dd>
- FF_STATUS_SAVERECORD_FAILED <dd>A error happened while saving a record to #__facileforms_records</dd>
- FF_STATUS_SAVESUBRECORD_FAILED <dd>A error happened while saving a subrecord to #__facileforms_subrecords</dd>
- FF_STATUS_UPLOAD_FAILED <dd>A error happened while uploading or moving a upload file to the destination directory. Most probably a invalid directory or unsufficient permissions (chmod) problem.</dd>
- FF_STATUS_SENDMAIL_FAILED <dd>A error happened while sending mail.</dd>
- FF_STATUS_ATTACHMENT_FAILED <dd>A error happened while trying to create the attachment file in directory components/com_facileforms/exports. Most probably a unsufficient permissions (chmod) problem.</dd>
Custom submit pieces can read and set the status as $this->status
- message
- A human readable message string in addition to the status code. May also be defined either by the internal routines for saving records/subrecords and mailing, or by custom pieces. Custom submit pieces can read or set the message as $this->message.
Return Value
none.
Examples
function ff_MyForm_submitted(status, message)
{
switch (status) {
case FF_STATUS_OK:
ff_returnHome(); // do whatever desired on success
break;
case FF_STATUS_UNPUBLISHED:
case FF_STATUS_SAVERECORD_FAILED:
case FF_STATUS_SAVESUBRECORD_FAILED:
case FF_STATUS_UPLOAD_FAILED:
case FF_STATUS_ATTACHMENT_FAILED:
case FF_STATUS_SENDMAIL_FAILED:
default:
alert(message);
} // switch
} // ff_MyForm_submitted
Related Links
<a href="content/view/77/115/">ff_submitForm</a>, <a href="content/view/78/115/">form initialization script</a>
Location
Library function or custom code defined in form settings.
Version Info
Available in all versions
ScriptAPI:ff_trim(string)