All dollar functions such as $page, $list, $link, etc. are implemented using the dollar_function model. This model makes it easy to implement new dollar functions as the need arises. Dollar functions must be implemented in the system site so that they can be used within all other sites. All dollar functions must be named (stowed as) dollar_some_name, where some_name is what you want to call the dollar function.

Establishing Dollar Function Parameters

Almost all of the dollar functions you create will most likely require one or more parameters to be passed into the function. In most cases you will want to arrange the parameters in order of importance. Generally, the first few parameters will be required and the required parameters may be followed by one or more optional parameters. It is also possible that one or more of the trailing parameters may repeat as a group.

Dollar Function Example

This help will review the setup of the if_mobile dollar function. Let's review the initial set of parameters to this function.

if_mobile dollar function parameters

Short Description

The short description is shown to developers when they list the dollar functions. Enter something that will help them understand how the dollar function is to be used.

Extends

In most cases you won't use the extends option. On rare occasions you may have several dollar functions that perform similar or related functions. In such cases, you can define common code within a base class and then the related dollar functions would extend this base class and inherit common code as needed. The base class would normally be defined using the php_class model and it would extend dollar_function_base.

Return Type

Most dollar functions return a string. In some cases, the dollar function may set certain runtime options but not actually return anything. Set the return type value according to what is normally returned when the dollar function executes.

Required Parameters

If some of the parameters must be provided in order for the dollar function call to proceed, enter the number of required parameters.

Device Specific

If the contents returned by the dollar function may vary according to the device on which it is executing, check this option. The if_mobile is a textbook example of this capability since its purpose if to return the first supplied parameter when running on a mobile device and the second parameter if executing on a desktop device. Setting this option will allow you to test the function while simulating either a mobile or a desktop device.

Don't Parse Return Value

Normally, when a dollar_function returns other dollar functions, these returned dollar functions would be parsed right away before returning the results to the caller. If this dollar function would never return a dollar function or if you would want to postpone the parsing of a returned dollar function check this option.

Disallow Test

In most editors it is possible to bring up help for dollar functions by clicking on the function and pressing <ctrl>g. This help function normally allows you to execute the dollar function to experiment with the function and review the output. Sometimes dollar functions cannot be tested in this context or perhaps the dollar functions do not return any content so testing does not add value or is dangerous. In such cases, check this option.

Hide Rendered Result

There may be situations where you don't want to allow developers to see the code that is rendered (output) by a dollar function. For example, perhaps the dollar function returns confidential or sensitive information. In such cases, check this option.

Repeat Last N Parms

The dollar_function parser allows one or more parameters to be repeated. In this case, the parameters are passed into the dollar function as array values rather than scalars. If only the last parameter can be repeated, enter 1 here. If the last two parameters can be repeated enter 2, etc.  

Parameter Definition

The parameter grid contains one row for each parameter that can be passed into the dollar function. These must be entered in the same order that you want users to pass parameters to the generated dollar function. Required parameters must be entered first followed by optional parameters. Repeating parameters must be last.

Parm Name

Enter a descriptive name for the parameter.

Format

If the parameter must be supplied in a specific format enter that here, otherwise choose mixed.

UI Control

Indicate the type of HTML input control that should be used to collect the parameter value within the function help form.

UI Parms

This allows you to supply additional parameters used to configure the HTML Input field within the function help form. For example, if the field should be a certain size you would enter this here. All values must be entered in json format. If a parameter is used to enter a page id, you might configure this parameter by entering something like: *based-on:pageid,size:30. This allows you to inherit the properties of the predefined html_field_type page.

Default Value

If this parameter should be assigned a default value in cases where the user did not supply a value for the parameter, enter the default here. If no default is provided, non-supplied (optional) parameters will default to NULL. Quotes are not required when supplying a default string unless you want the default to be an empty string in which case you should enter two single quotes.

Postpone Resolve

Normally when the parameters to a dollar function contain other dollar functions these are resolved before calling the outer function. Usually this is desirable however there are some situations where it is better to defer the expansion of these parameters. Consider the following dollar function reference.

$if_mobile($page(narrow),$page(wide))

Since the purpose of the $if_mobile function is to generate one set of code on mobile devices and a different set of code on desktop devices, only one of these $page functions will ultimately need to be expanded. Since page expansion may be resource intensive it does not make sense to expand both of these. Instead, we will pass the dollar functions into the if_mobile handler and it will return exactly one of the dollar functions back to the caller and this output would then be expanded thereby avoiding the need to ever expand the $page function that does not apply to the current device.

Execute Function

Every dollar function must define an execute function. It is not required (or allowed) to enter the execute function statement, only the body of the function must be entered. The role of this function is to implement the logic of the function and either return a value or configure the runtime environment according to the purpose of the function.

Let's review the following code of the if_mobile function:

if_mobile function code

Notice that the parameter names defined in the parameter definition are available as class variables (properties). The variable$this->mobile_content contains the first parameter passed to the function and $this->desktop_content contains the second parameter.

In the code we first call the site's mobile_browser() method to determine whether we are currently executing on a mobile device. If we are, we return the contents of $this->mobile_device unless this has not been set (passed) in which case it returns and empty string. If we are not on a mobile device the function returns the contents of $this->desktop_content or an empty string if this was not passed in.

Miscellaneous Functions

This editing area can be used to code other functions that may be called by the execute function.

Sharing Values Between Functions

Sometimes you may want to set values within your functions that are used by other functions or by the main execute method. The base class defines a cache array intended for this purpose. In this example, the dollar_imagelink model sets a value for consumption by the inherited image model.

$this->cache['called_by_imagelink'] = true;
return parent::execute();

Raising Errors

Sometime the dollar function may determine that it cannot proceed with the supplied parameters. In such a case it can raise an error by calling the inherited set_error_message method and passing an error message to be generated in place of the normal return value. A value of false should be returned in addition to setting the error message. Here we see an example of raising an error in the dollar_assign class which is used to assign a session variable.

if (substr($this->session_index,0,1) === '_') {
    $this->set_error_message('Session variables beginning with _ are reserved by the framework');
    return false; 
}
$this->site->start_session();
if ($this->assign_value === 'NULL'){
    unset($_SESSION[$this->session_index]);
}
elseif ($this->value_type === 'string'){
	$_SESSION[$this->session_index] = $this->assign_value;
}
else {
	$_SESSION[$this->session_index] = \system\variable::cast($this->assign_value, $this->value_type);
}

Let's review the key statements in this code.

  • The first if statement is used to raise an error if the session variable supplied begins with an underscore.
  • Next we call a method of the system object to start the session (most dollar functions won't do this, only the ones related to session variables).
  • Since the value to be assigned to the session variable is a required parameter we have designated the string 'NULL' as a means to unset the session variable.
  • If the session variable is of type string, we can assign it directly. Otherwise, we need to convert the supplied string to the desired format by calling a system function. 

Describing Parameters

The dollar function description and a description of all parameters should be coded within a translation object whose name matches that of the dollar function (including the dollar_ prefix). These translation definitions are stowed within the genhelm site (not the system site where the dollar function is stowed). After launching the translation model you can use the command "example dollar_function" to automatically populate the columns you will need to define.

Here we see the English help information defined in the translation object named dollar_if_mobile.

if_mobile Translations

The first row, named extended_description, is used as the function description shown within the dollar function help popup. The other information is used to describe the fields on this popup as we see here:

Help used by if_mobile dollar function

Learn More

All of the dollar functions are supplied in source form so you can review the code for any function by logging onto the system site (logon system) and editing the specifications that start with dollar_ (e dollar_*).

dollar_function help inputs
🡇
dollar_function help outputs