You can control display for form sections from Forms’s GUI. This will allow to create simple display logic, involving custom fields and taxonomy.
To produce an even more powerful display logic, you can enter custom display conditions. This page explains the different functions and operators that are available.
When you insert display conditions (Forms editor → Insert generic field → Conditional group), click on the Use my Custom Expression checkbox.
You will see the textual representation of the display condition that you have chosen in the GUI.
Suggestion: We recommend adding all fields that you need in the GUI and then customizing their relationship in the text field. Of course, if you know the exact names of fields, you can enter them directly into the text field.
[cred_show_group if="($(field_name) gt '1')" mode="fade-slide"] <!-- content to be shown only when this is true inside here --> [/cred_show_group]
These operators work on numeric values.
- ^ : Power (eg: 2^3=8)
- * : Multiply (eg: 2*3=6)
- / : Divide (eg: 4/2=2)
- % : Modulo (eg: 4 % 2=0)
- + : Add (eg: 4+2=6)
- – : Subtract (eg: 4-2=2)
These operators work on Boolean and numeric values.
- !,NOT : Negation (eg: NOT true=false)
- &,AND : Logic AND (eg: true AND false=false)
- |,OR : Logic OR (eg: true OR false=true)
You can use these operators with inputs of the same type. Result will depend on the type of inputs provided.
- >, gt : Greater Than (operate on numeric, string and date operands)
- >= , gte: Greater Than or Equal (operate on numeric, string and date operands)
- <, lt : Lesser Than (operate on numeric, string and date operands)
- <=, lte : Lesser Than or Equal (operate on numeric, string and date operands)
- <>, ne : Not Equal (operate on boolean, numeric, string and date operands)
- =, eq : Equal (operate on boolean, numeric, string and date operands)
Note: Forms can handle comparisons using any form of these operators, but since these are mostly used inside shortcodes, operators like >or < can cause problems with HTML markup, so it is recommended the usage of the alphanumeric form such as ie, eq and ne.
Note 2: Almost all fields (except Date fields) are considered as strings by the Forms parser (in reality all form fields represent strings), in order to transform a field value to numeric value, type-casting can be used using the NUM function eg. NUM($(my-numeric-field)) gt 1.
The STR function can be used to type-cast numeric values into strings (reverse operation), eg. STR(NUM($(my-numeric-field))) eq ‘1’
These operators convert between data types and provide general functionality.
- ARRAY(mixed1,mixed2,..) : Return an array of values
- AVG(mixed1,mixed2,..) : Average value of inputs (inputs can be numbers or arrays of numbers)
- ABS(number) : Absolute value
- ASC(string) : Ascii code of first char of string
- CHR(number) : Character having number as Ascii code
- COS(number) : Cosine
- CONTAINS(array,value_mixed) : Return true if value (value can be numeric or string) is contained in array (also “=”,”eq”,”<>”,”ne” operators function as a CONTAINS function when one operand is array, eg: ARRAY(1,2,3)=3 is same as CONTAINS(ARRAY(1,2,3),3) )
- COOKIE(string_name) : Return the COOKIE value with name [string_name] (eg: $(user_field)=COOKIE(‘user’))
- DATE(date_string,format_string) : Convert a string to Date according to given format (eg: DATE(’03/10/2012′,’d/m/Y’)>$(date_field)) dates can be compared using any comparison operator. Note a string alone cannot be used as a date, it has to be transformed into a date using the DATE function. Supported date formats are ‘d/m/Y’ and ‘m/d/Y’.
- FIX(number) : Integer part of number
- HEX(number) : Hexadecimal string of number
- IIF(boolean, mixed1, mixed2) : (inline if) if boolean is true return mixed1 else mixed2
- LCASE(string) : Convert to lower case
- LEFT(string, number) : Substring form start until pos number
- LEN(string) : Length of string
- LEN(array) : Length of array
- LOG(number) : Natural logarithm
- MAX(mixed1,mixed2,..) : Maximum of inputs (inputs can be numbers or arrays of numbers)
- MID(string,num1,num2) : Substring of string between pos num1 to pos num2
- MIN(mixed1, mixed2,..) : Minimum of inputs (inputs can be numbers or arrays of numbers)
- NUM(string) : Convert string to Number (if possible)
- RAND(min,max) : Random integer between min and max
- REGEX(string_pattern [, string_options]): Return a Regular expression for specified string_pattern with optional string_options. Strings can be compared to regular expressions for match,
'abC'=REGEX('^ab','i')will return true. Note: Regular expressions are intrinsic objects and since the parser is run on two different places (client-side and server-side) there are some differences in the flavors of regular expressions used in each platform, Forms tries to provide a uniform functionality between the different environments, however sometimes it may be necessary to check that the condition (involving Regular expressions) behaves the same both client-side and server-side and tweek it if is needed. Note 2: Square brackets can’t be used in the regular expression. These will cause problems with the WordPress shortcode parser.
- RIGHT(string,number) : Substring from end till number pos
- SIN(number) : Sine
- SQRT(number) : Square Root
- STR(mixed) : Convert to string
- STR(date,format) : Convert date to string using format (this is the reverse of the DATE function which convets a string to date using format)
- TAN(number) : Tangent
- TODAY() : Current (user) date (eg a date field can be compared to this function to check the relation with current date, $(date_field)>TODAY() means if date_field refers to a later date than current date) Note: TODAY() may behave differently between server and client on different time zones
- UCASE(string) : Convert to Uppercase
- USER(field_string): (in v. 0.9.4) get information about current user by selected field, fields can be (case insensitive): ‘role’: current user role, ‘login’: current user login name, ‘name’: current user display name. ‘id’: current user ID, eg show/hide certain form fields only if user is administrator can be done with an expression like (USER(‘role’) eq ‘administrator’)
Almost every expression compares between values of inputs and constants. These are the constants that Forms recognizes.
- Booleans: true,false
- Numbers: eg. 0.1, 34 etc..
- Strings: eg. ‘foo1’, “FOO3”
- Dates: eg.. TODAY(), DATE(’06/10/2012′,’d/m/Y’), etc..
- Arrays: eg ARRAY(1,2,3), ARRAY(‘a’,’b’,’c’), etc..
- Special case: EMPTY – checks if the value is empty. Also !EMPTY can be used in which case, logical operator (if) is not necessary.
Variables are the field inputs. You can use custom fields and taxonomy as variables.
- a field name is turned into a variable by the $() operator, eg a cred field is named “my-field”. In a conditional expression the value of this field could be referenced by $(my-field) (no quotes needed)
[cred_field field="my-checkbox" post="mypost" value=""] [cred_show_group if="($(my-checkbox) eq '1')" mode="fade-slide"] <!-- content to be shown only when "my-checkbox" field value is '1' inside here --> [/cred_show_group]
The parser will try to parse and evaluate the given expression. If the expression is not well formed, or there is any other parser error, the condition will be considered as false.
Checkbox and Select box type fields (and also taxonomy fields) are generally multi-valued fields, which means that the value of a field of this type (when used in an expression) is actually an ARRAY instead of a single value. As such only operators “eq” and “ne” can be used (corresponding to “=” equal and “<>” not-equal) meaning either this value is contained in the values array or not. Being an array of values, comparison operators like greater-than and lesser-than have no meaning.