A Guide to CMS Functions

How to Set Function Parameters

Many functions require some information from the user before executing their logic. The user passes the required information to the functions via function parameters.

By default, the function parameters are presented in the Basic view where you can quickly set the parameters in the corresponding fields and override the default values.

Figure 23: Parameters of a function to insert (Basic view)

For more control over values in the parameters, you may want to switch to the Advanced view.

Figure 24: Parameters of a function to insert (Advanced view)

When you set parameters in the Function Properties window, you normally have a choice of three types of parameters:

Figure 25: Parameter types in the Function Properties window

If any of those are not available for a particular function, they usually do not appear in the GUI.

Figure 26: Default parameter type not used

Besides, the parameters might be required or optional. If at least one of the required parameter is not set, the function will not work correctly, and normally, you will not be able to insert it via GUI.

Other parameters are optional, which means that you can skip setting these parameters. They are either set to some smart defaults or not set because they extend the function’s possibilities and thus can be skipped in the most basic scenario.

Required parameters are normally marked as in the GUI, while optional parameters are indicated as . When the value of the required parameter is set or the default value of an optional parameter is modified, the parameter is marked as .

To set a parameter of a function:

  1. Insert or edit a function.
  2. Select a parameter.
  3. If necessary, change the parameter type by clicking the corresponding Parameter Type button.
  4. Specify the value.
  5. Click save the changes.

Please note that the currently used parameter type is normally disabled in the Function Properties window.

Default Parameters

Some functions come with predefined values for their parameters, normally acceptable for the first run or the most common usage scenario. When you insert such a function, it sets its parameters to these defaults.

However, you can always override the default values:

  1. Edit the function properties.
  2. Change the parameter type from the default value to a constant value or a function call.
  3. Set the new value by replacing the existing one if necessary.
  4. Click OK.

Tip: If you want to view what value is used by default, you can change the default parameter type to the constant one. Normally, the constant value contains the default value on optional parameters.

Constant Parameters

Constant parameters require that a value of specific type should be specified for the function to work properly.

There are several types of constant parameters, each represented with a corresponding widget in the GUI. They include but are not limited to plain text strings, numerals, options, lists and C1 CMS entities such as pages, media files or data types as well as XML or XHTML formatted texts.

Figure 27: A constant parameter (a media file)

(For information about widgets in general, please refer to Widgets in “A Guide to Creating Data Types”.)

Function Calls

Not only can default or user-defined constants be values of the parameters. In some cases, the value of a parameter must be calculated based on the current context at the moment the function renders content.

That is why you can use other functions to set values of the parameters. The function calculates the value and returns it to the parameter.

It is not uncommon that the function used to set a value can in turn has its parameters set by other functions.

Figure 28: A function call as a parameter value

To use a function call on a parameter:

  1. Select the parameter in the Function Properties window.
  2. Click Function to change the value type of the parameter.
  3. In the “Value for Parameter...” window select the proper function (as you do when selecting a function to insert).
  4. Click OK. The function appears as a child element to the parameter element.
  5. If required, select the parameters of the function that set the value, and sets their values, too.
  6. Click OK.