Parameter Types

You can add parameters of various types to your CMS functions.

All CMS functions support simple parameter types. XSLT and C# inline functions also support data reference and other types of parameters.

^{Figure 5: Parameter types listed}

The values of many parameters can be set in the GUI as constant values via their associated widgets or as dynamic values via calls to related functions (e.g. String).

The values of some parameter types can only be set via calls to related functions (e.g. UserControl).

In some cases, you may need to use a parameter of specific type if you intentionally want to use the input parameter as a call to a certain function (e.g. Void).

Simple Parameters

When editing a CMS function, you can use these simple parameter types:

• Boolean

• DateTime
• Decimal
• Guid
• Int32
• String

They are all associated with one or more standard widgets by default and their use is straightforward.

You can also use some related functions to set the values of these parameters. For example, you can concatenate two strings with the Composite.Utils.String.JoinTwo functions for a parameter of the String type instead of using a constant value.

Please note that these are the parameter types SQL functions are limited to.

Data Reference Parameters

Parameters of the data reference type can reference both built-in and custom data types in C1 CMS. The built-in data types include:

• C1 Page
• C1 Image File
• C1 Media File
• C1 Media Folder

Custom data types are all those global data types, page data folders and page meta types created in C1 CMS.

Data reference parameters come in two flavors:

• DataReference <datatype>
• NullDataReference <datatype>

When used, a DataReference parameter contains a reference to a specific data type and is required.

A NullDataReference parameter can also contain a null reference (i.e. no reference to a specific data type) and thus serves as an optional parameter.

For the built-in data types, ad-hoc selectors are used as widgets:

• PageSelector
• Optional PageSelector
• ImageSelector
• MediaFileSelector
• MediaFileFolderSelector

For both built-in and custom data types, these two selectors are used as widgets:

• Selector
• OptionalSelector

When you specify a custom data type as a parameter type in a function, the selector widget will list all the items of this data type by using the field set as the “Title field” in the data type.

^{Figure 6: Setting a parameter of the data reference type}

Other Types of Parameters

In addition to the simple parameters, there are two more parameter types whose values can be set via associated widgets in the GUI:

• XhtmlDocument
• Type

And these are the parameters the values of which can be only set with related functions:

• CultureInfo
• Object
• UserControl
• XElement

There are also a few more parameter types used more to make calls to specific functions:

• Void
• XSLT Extension Definitions
• Expression Functions (Predicates)
• Enumerables
• Property Validator Builders

XhtmlDocument

The XhtmlDocument parameter accepts valid XHTML content as its value.

The widget used on this parameter is Composite.Widgets.XhtmlDocument.VisualXhtmlEditor that represents an XHTML editor in both Visual and Source modes.

^{Figure 7: The VisualXhtmlEditor widget}

You can use the MarkupParser extension function on the value of this parameter type when rendering input parameters in XSLT.

Type

The Type parameter accepts a data type as its value.

The widget used on this parameter is Composite.Widgets.Type.DataTypeSelector that lists all the data types available in C1 CMS - both built-in and custom. The custom data types include global data types, page data folders and page meta types.

^{Figure 8: Setting a parameter of the Type type}

In the markup, a custom data type must be referred to by its full name.

<f:param name="DataType" value="Composite.Community.Blog.Entries" xmlns:f="http://www.composite.net/ns/function/1.0"/>

^{Listing 1: Setting the value to a custom data type (dynamic)}

The static data types as well as the built-in data types have their own pattern for reference: the full name and the name of the assembly.

<f:param name="TestField" value="Composite.Data.Types.IImageFile,Composite"      xmlns:f="http://www.composite.net/ns/function/1.0" />
<f:param name="TestField" value="Composite.Data.Types.IMediaFile,Composite" xmlns:f="http://www.composite.net/ns/function/1.0" />
<f:param name="TestField" value="Composite.Data.Types.IMediaFileFolder,Composite" xmlns:f="http://www.composite.net/ns/function/1.0" />
<f:param name="TestField" value="Composite.Data.Types.IPage,Composite" xmlns:f="http://www.composite.net/ns/function/1.0" />

^{Listing 2: Setting the value to a built-in data type}

CultureInfo

The CultureInfo type expects a predefined CultureInfo name as its value (for example, “en-US” or “da-DK”).

To allow the user to specify the CultureInfo name as a string, the Composite.Utils.ParseStringToObject function should be used.

^{Figure 9: Parsing a string to a CultureInfo object}

If necessary, the parameter can be also set to the CultureInfo currently used in the system with the Composite.Utils.Globalization.CurrentCulture.

Object

The Object is a generic parameter type used for input parameters whose value cannot be defined at the design time, and thus, can basically be of any type. Since the Object type is the parent type in .NET, it makes sense to use it as the most common type.

UserControl

The UserControl type expects an ASP.NET User Control as its value. The value can be set by calling the Composite.AspNet.LoadUserControl function, which loads an ASP.NET User Control (.ascx file) from a specific path, for example, “~/Controls/MyControl.ascx”.

XElement

The XML type expects an XML element, the fundamental XML construct, as its value. The XML element can have no, one or more attributes and include content made up by other XML element. In general, the parameter of this type expects valid XML.

To set its value, you can use of these CMS functions:

• Composite.Core.Xml.LoadFile: Loads a local XML file at a specific relative path
• Composite.Core.Xml.LoadUrl: Loads a remote XML file by a specific URL

Custom functions that return a value as an XElement can be also used.

Void

You can use a function to provide a value for the input parameter. The function must return a value of the same type as selected for the input parameter. For example, if you set the input parameter type to “string”, the functions that return a string will be available in the Select Function window. Others will be filtered out.

^{Figure 10: Functions filtered based on the parameter type (String)}

Some CMS functions return no value. In fact, what they return is “void” (“null” as a matter of fact). This ensures that they are never suggested as functions for any specific type you can set the input parameter to.

If you need to use one of these functions in the input parameter (for example, Web.Response.Redirect), you should set the input parameter to the Void type.

XSLT Extension Definition

A parameter of the XSLT extension definition type expects an XSLT extension definition as its value.

The value (the extension itself) is not added to the input XML document, but rather hooked into the list of extensions that can be called from XSLT. You can “inject” these extensions into the CMS function system, and then call the injected classes from XSLT.

If any XSLT extensions are available in C1 CMS, you can specifically select them as an input parameter:

XsltExtensionDefinition<extension>

For example, XsltExtensionDefinition<MailingListXsltExtensions>

The IXsltExtensionDefinition type as an input parameter has no XSLT extension definition associated with it at the design time and must be defined when the function with this parameter is actually used. All the XSLT extension definitions will be thus available. For example, Composite.Xslt.Extensions.DateFormatting.

For information about making custom XSLT extension definitions, please refer to “Adding an XSLT Extension”.

Function Expressions (Predicates)

A parameter of the function expression type expects a function expression (expression tree) as its value.

As parameters in CMS functions, the function expressions can be called with the following simple types: Boolean, DateTime, Decimal, Guid, Int32, String as well as all the data types available in C1 CMS - both built-in and custom. (They can be also called with nullable counterparts of Boolean, DateTime, Decimal, Guid, Int32.)

• Expression <Func <[type], Boolean>>
• Expression <Func <[datatype], Boolean>>
• Expression <Func <Nullable<[type]>, Boolean> >

They always return a Boolean.

Based on the type the expression is called with, specific expression-building functions are available for it (Composite.Utils.Predicates).

For example, with Expression <Func <String, bool>>, you can use the following functions:

• StringContains
• StringEndsWith
• StringEquals
• StringInCommaSeparatedList
• StringInList
• StringNoValue
• StringStartsWith

For data types, a corresponding FieldPredicatesFilter is used to give access to expression-building functions on each field according to the type of the latter.

The function expressions are a convenient tool to filter data provided by data-centric functions (Get<Type>Xml).

For example, it can be used to retrieve, render and present only one data item based on its ID as a query parameter in the URL.

Enumerables

For an input parameter that holds a list of read-only values, you should use an enumerable type - IEnumerable. IEnumerable implements an enumerable list of strings, XML elements (XElement) or CultureInfo objects:

• IEnumerable<string>
• IEnumerable<XElement>
• IEnumerable <CultureInfo>

Its value can be set with a function call.

For example, the Composite.Utils.String.Split function returns an enumerable list of strings and Composite.Utils.Globalization.AllCultures returns an enumerable list of CultureInfo objects.

Functions that return XML can provide enumerable lists of XElements. The data-centric functions (Get<Type>Xml) can be their example.

In the function markup, when the parameter type is IEnumerable, you should use one or more “paramelement” elements to list the fields to include the values of in the output.

<f:function xmlns:f="http://www.composite.net/ns/function/1.0" name="Composite.Data.Types.IPage.GetIPageXml">
  <f:param name="PropertyNames">
    <f:paramelement value="Id" />
    <f:paramelement value="Title" />
  </f:param>
</f:function>

^{Listing 3: Using paramelement elements with the IEnumerable parameter}

Property Validators Builders

As its value, the property validator builder type expects an object capable of validating a value of a simple type such as DateTime, Decimal, Guid, Int32 and String. Hence, there are five property validator builder types available in C1 CMS:

• PropertyValidatorBuilder <DateTime>
• PropertyValidatorBuilder <Decimal>
• PropertyValidatorBuilder <Guid>
• PropertyValidatorBuilder <Int32>
• PropertyValidatorBuilder <String>

Their value should be set by invoking one of the Composite.Utils.Validation functions.

For each validated simple type, there is at least one validation function, which ensures that the value is not null (*NotNullValidation), for example, StringNotNullValidation.

Besides, there are a few validation functions specific to the Decimal, Integer and String types:

• DecimalPrecisionValidation
• IntegerRangeValidation
• RegularExpressionValidation
• StringLengthValidation