Piece API Reference

From FacileWiki

+++ UNDER CONSTRUCTION - STATUS OF 1.4.4 +++

[edit]

ff_Constants

[edit]

ff_DisableFormTrace

[edit]

ff_DisableSubmitTrace

[edit]

ff_InitLib

Description

ff_InitLib is a piece that loads the standard PHP library of facile forms. The piece must be loaded in the before form or begin submit pieces before any of the ff_* functions in the standard PHP library can be used.

Examples

$this->execPieceByName('ff_InitLib');

Location

Standard piece library stdlib.english.xml

Version Info

Available in 1.4.0 and up

[edit]

ff_die($message="", $action="stop", $target="", $params="", $label="Continue")

Description

Gracefully terminates the form and shows a message plus opionally a CONTINUE button for further redirection.

Parameters

$message: A message to display. If no message is provided, it will display:

                   Fatal error in $formname, processing stopped.

$action: The action that should be carried out.

'stop'
Dont show a CONTINUE button (default)
'self'
Redirect to the same form
'form'
Redirect to another form
'page'
Redirect to another page of this site
'home'
Redirect to homepage of the site
'url'
Redirect to a url

$target: Target name/url for 'form', 'page' and 'url'

$params: Additional parameters for 'self' and 'form'

$label: Text for the continue button

Examples

    // Display standard message without continue button
    ff_die(); 

    // Display message without continue button
    ff_die('Sorry, cannot continue for some reason.');

    // Display standard message and return to same form with a parameter
    ff_die(null, 'self', '&ff_param_foo=bar');

    // Redirect to another form
    ff_die('Guess you are hungry now...', 'form', 'SamplePizzaShop', null, 'Order');

    // Redirect to another site page
    ff_die(
        'Something strange has happened!', 
        'page', 
        'index.php?option=com_content&task=section&id=1&Itemid=2'
    );

Location

Standard piece library stdlib.english.xml

[edit]

ff_dying()

[edit]

ff_expString($text)

[edit]

ff_getPageByName($name)

[edit]

ff_getParam($name, $default=null, $mask=0)

Description

This function is basicly a enhanced replacement for mosGetParam. It additionally takes care if the parameters starting with ff_param_ are targeted to the current form when multiple forms are on one page.

Parameters

$name: The 1st parameter is the name of the GET/POST parameter to retrieve.

$default: The optional 2nd parameter is used to supply a default value. If nothing or NULL is supplied, it will return a scalar defaulting to NULL when nothing was submitted.

$mask: The optional 3rd parameter allows controlling the masking of the parameter values:

FF_NOTRIM
Do not trim leading and trailing whitespace. By default it will be trimmed.

FF_ALLOWHTML
Do not filter HTML code. By default HTML code will get removed.

FF_ALLOWRAW
Retrieve strings unescaped. By default strings will be returned escaped, e.g. selected characters as single quotes, double quotes and NUL preceeded by backslash. (Do not use unescaped strings in SQL statements since that could enable SQL injection!)

Examples

// Get id and default it to 0 if nothing passed
$id = ff_getParam('ff_param_id', 0);

// Return empty string when nothing supplied
// Dont remove leading and trailing whitespace
// Unescape strings
$text = ff_getParam('ff_param_text', '', FF_NOTRIM | FF_ALLOWRAW);

Location

Standard piece library stdlib.english.xml

Version Info

Available in 1.4.0 and up.

$mask flag FF_ALLOWRAW available from 1.4.6 and up.

[edit]

ff_getSubmit($name, $default=null)

Preface

In begin submit pieces the traditional way in early version of FacileForms was to extract the submitted data from the submission arrays in a loop as:

$foo = ''; $bar = 2;
foreach ($this->submitdata as $data)
    switch ($data[_FF_DATA_NAME]) {
        case 'foo': $foo = $data[_FF_DATA_VALUE]; break;
        case 'bar': $bar = $data[_FF_DATA_VALUE]; break;
        default:;
    } // switch

Besides not being very intuitive, programming this loop in every form becomes tedious over time (allthough still possible and usefull in special cases). The function ff_getSubmit() automates the process and adds more convenience.

Description

Returns submitted data either as Scalar, Array or List. In case of list the values are returned as a string with the values concatenated by comma.

Parameters

$name: The 1st parameter is the name of the element.

$default: The optional 2nd parameter is used to either supply a default value when retrieving a Scalar value, or to control how to return arrayed data. If nothing or NULL is supplied, it will return a scalar defaulting to NULL when nothing was submitted.

Examples

Scalar: Optionally pass a default value as second parameter. If no default is provided, it will return NULL if no value was submitted

// return NULL if nothing submitted
$myval = ff_getSubmit('myvar');

// return 1 if nothing submitted
$myval = ff_getSubmit('myvar',1);      

// embedd the function into SQL statement
ff_query(
    "insert into #__mytable(id, name) ".
    "values (".
        "'" . ff_getSubmit('id', 0)."', ".
        "'" . ff_getSubmit('name', 'unknown')."' ".
    ")"
);

Array: Pass FF_ARRAY as 2nd Parameter to fetch values of a group (multiple elements with same name, or the ID's of a query list for example).

$myarr = $ff_getSubmit('myarr', FF_ARRAY);

foreach ($myarr as $myval) ...

List

Pass either FF_LIST, FF_SLIST or FF_DLIST as 2nd parameter to get the values of a group of input elements:
ff_query(
    "delete from #__mytable ".
    "where id in (" . ff_getSubmit('myquerylist', FF_LIST) . ")"
);
FF_LIST
Will return numeric data unquoted and strings in single quotes:
1,2,'a',4
FF_SLIST
Return all data single quoted:
'1','2','a','4'
FF_DLIST
Return all data double quoted:
"1","2","a","4"