1. Fabrik 3.5.2 is now available to download. Read the blog for highlights about this release.

    As always, please back up your site prior to updating and if possible test in a dev environment first.

    Also, our 3.5.1 package file was hacked, the effected dates were 1/15/2017 - 1/17/2017. If during those days you downloaded the 3.5.1 package file from the JED or our site download page, please re-install the package with a fresh copy or upgrade to Fabrik 3.5.2. Github downloads were not effected.

Placeholders

Nov 10, 2016
Placeholders
  • Throughout Fabrik we often refer to Placeholders. Placeholders are a key concept in Fabrik.

    A placeholder looks like this:
    Code (Text):
    {tablename___elementname}
    It typically consists of a table name, followed by three (3) underscores, followed by an element name, all surrounded by curly brackets.

    When included in an 'eval' box or in an e-mail template, the placeholder will be replaced with data from the specified table-element (table-field) in your database.


    Default values(top)

    Sometimes a placeholder may not have an associated value and you may wish to define a default value. The syntax for this is:

    Code (Text):

    {yourtable___foo||bar}
     
    If the placeholder 'foo' is found then its value is used. If it is not found then 'bar' is used as the placeholder value.

    Using Placeholders in Eval'ed php code(top)

    The most basic rule about placeholders in php code which will be used in an eval, is that they should always be enclosed in some sort of quotation marks, regardless of whether the placeholder is holding a string or a number.

    Raw Values (top)

    Some element types, like radio button, dropdowns, joins, etc have the concept of a "label" and a "value". So you may have a dropdown selection which has the value '2', for the label 'Option Two'. In these cases, you can append _raw to your placeholder, which will give you the "raw value" rather than the label.

    So in that example, {yourtable_yourelement} would be "Option Two", and {yourtable___yourelement_raw} would be "2".

    String values (top)

    String values are the easiest to deal with. You just ensure that the placeholder is between quotations in some form i.e. they can either be immediately around the placeholder or you can use the placeholder as part of a bigger string (e.g. "Please contact {table___name} for assistance.").

    So as examples:
    PHP:
    $custName = '{customer__name}';
    $helpText = "Please contact {staff___name} for assistance.";

    Numeric values (top)

    Because your placeholder could be empty, if you just try to use it in a calculation, the resulting php code could be invalid e.g. if your code was:
    PHP:
    $foo = {table___number};
    and table___number was empty (null or spaces), then after the placeholder has been substituted the php code would be:
    PHP:
    $foo = ;
    which is not valid php code and would result in an eval syntax error.

    So for numeric placeholders you should cast your value from string to number using one of the following forms of code:
    PHP:
    $quantity = (int) '{order___quantity}';
    $price = (float) '{product___price}';
    If the placeholder is blank or null, then these will result in (int) ' ' or (float) ' ' both of which evaluate to zero rather than giving a syntax error.

    Script Files (top)

    Note that placeholders only work in "eval'ed" code, that is, PHP code you insert in to text fields on the Fabrik backend, and which we run by using PHP's 'eval' command. For plugins that also provide a way for you to use PHP files, like the PHP form submission plugin, which we run by using PHP's 'require' command, you cannot use placeholders in those files. Instead you would need to access the data as documented in the PHP form plugin wiki, which applies to most places you can write custom code and access the $formModel, not just the form plugin.

    Using Placeholders in Email Templates(top)

    Because email templates are already strings, you do not need to enclose placeholders in quotation marks in email templates (unless of course you want the quotation marks to appear in the email).

    Types of Placeholders (top)

    {tablename___elementname}(top)

    This is the most commonly used placeholder. It is also referred to as the full element name of an element. It can be used in almost every configuration field in the back-end, and will be replaced with that element's data. In a table view it is the data of the current row.

    The full element name is displayed in the back-end when you go to the Elements list.

    When you create an element in Fabrik without assigning it to a group it is shown as {___elementname}.
    When your element is later added to a group, it then uses the table name the group belongs to as a prefix.

    Note: There are three (3) underscores between the table name and the element name.

    Example: if your element name was a text field called name, and it was added to the group details_group which was associated with the List personal_details then its full element name as a placeholder would be {personal_details___name}.

    Note: You can't access other lists' data via placeholders, for that you need to query the database.

    {$my->xxx}(top)

    This is replaced with the corresponding value of the current user. Replace xxx with any property from the Joomla JUser object.

    According to the Joomla documentation (J2.5 here, J3.x here) you can use the following:
    • {$my->id}
    • {$my->name}
    • {$my->username}
    • {$my->email}
    • {$my->block} - boolean value where True or 1 indicates the user is blocked within Joomla (or is pending authentication)
    • {$my->groups} - the Access groups that the user belongs to
    • {$my->registerDate}
    • {$my->lastvisitDate}
    • {$my->guest} - boolean value where True or 1 indicates the user is not logged in.
    Additionally for J2.5 you can use:
    • {$my->usertype} - string representing user type. For instance Registered.
    In J1.5, instead of groups you should use:
    • {$my->gid} - the Access group that the user belongs to

    {$their->yyy->xxx}(top)

    This is similar to {$my->id} - use it to access user information.
    • Replace xxx with any field from the table #__users
    • Replace yyy with the name of a request variable which contains the user id to load.
    Example: if the current url equals http://test.com?users___id=62
    the email address of the user with id 62 can be fetched using {$this->users___id->email}

    {$session->xxx.yyy}(top)


    In certain places you can use {$session->some.session.key} to access session data. This is only allowed where placeholder replacement is considered "safe", such that no user input could be interpreted and reflected back to the browser. We are slowly adding this feature (as of 10/11/2016), and currently it is only available in pre-filters and in join and CDD element 'CONCAT labels'. If you need to access session placeholders somewhere it isn't currently allowed, ask on the forums and (if it's "safe") we'll add it.

    You may optionally provide a namespace, if the data you need is outside the default Joomla namespace, by preceding the key with the namespace and a colon, like {$session->akeeba:profile}.

    There are also 3 shortcuts, available as other placeholders, simply to make naming easier to remember:

    {$session->id} - the main J! session ID
    {$session->token} - the main J! session token
    {$session->formtoken} - the current form token (if applicable)

    {$jConfig_xxx}(top)

    This is replaced with the corresponding value of the global configuration parameter. Replace xxx to get one the following placeholders:
    • {$jConfig_absolute_path} - Replaced with the constant JPATH_SITE - this is the server path to your site.
    • {$jConfig_live_site} - Replaced with JURI::base(), this is the url of your site. For instance http://mysite.com
    • {$jConfig_offset} - The site's timezone offset.
    • {$jConfig_sitename} - The site's name
    • {$jConfig_mailfrom} - The global "email from" option
    • {$jConfig_secret} - The secret string (used for AES encryption)
    Note we have deprecated the old {$mosConfig_xxx} placholders although they should still work.

    {$_SERVER->xxx}(top)

    Replace xxx with any variable found in PHP's $_SERVER global.

    A few examples are:
    • REMOTE_ADDR - The IP address from which the user is viewing the current page.
    • HTTP_REFERER - The address of the page (if any) which referred the user agent to the current page. See also {where_i_came_from} below.
    • REQUEST_URI - The URI which was given in order to access this page
    • REQUEST_TIME - The timestamp of the start of the request.
    For a full list, see the PHP manual.

    {where_i_came_from}(top)

    The URL of the previous page (HTTP referrer).

    {fabrik_referrer}(top)

    To be documented...

    {rowid}(top)

    The id of the current row. Does not work in new entries that don't carry a rowid until saved for the first time.

    {$Itemid} (or {Itemid})(top)

    The current menu item's Itemid

    {lang}(top)

    Gives us the full name for the user's language, e.g. 'en_GB' or 'fr_FR'

    {shortlang}(top)

    Gives us the sef name for the user's language, e.g. 'en' or 'et' or 'fr'

    {date}(top)


    Current date in YYYYMMDD format, uses PHP's date('Ymd'), so in whatever TZ PHP is configured to.

    Useful in (say) the file upload element's path setting for grouping uploads by date, like media/uploads/foo/{date}/

    {mysql_date}(top)


    Current date / time in MySQL's datetime format, YYYY-MM-DD HH:MM:SS, uses PHP's date('Y-m-d H:i:s'), so in whatever TX PHP is configured to.

    {session.token}(top)

    Will be replaced with the current Joomla session token.

    {new:Some text} / {edit:Some edit text} (top)

    Used in form intro fields. In the above example when adding a new record the text "Some text" will be displayed. When editing a record the text "Some edit text" will be displayed.

    {thistable} (top)

    Only available in database join concat and where fields - is replaced with the joins table name.

    {Jutility::getToken} (top)

    Inserts a security token, same token as Jutility::getToken()

    {user||{$my->id} (top)

    Will search for the variable 'user' in the request data, if not found will use the user's id instead - Useful when using fabrik in conjunction with community builder.

    See also... (top)

GorYa, daydah, ThierryM and 1 other person like this.