Community Builder supports substitutions in many locations such as delimiter fields, field titles, cb content module, and more. There are substitutions for simple to advanced and complex capabilities for displaying fields or even tabs. The following will demonstrate how to use CB Substitutions properly and to their fullest extend as well as examples of these usage scenarios.
Note in many cases you may want to access the users unique id. This can be substituted using [user_id].
Simple Raw Field Value - display field with all HTML/formatting removed (typically as seen in database)
[FIELD_NAME]
The user [username] lives in [cb_citystate] and his name is: [name].
The user BobTBurns lives in Springfield, OH and his name is: Bob.
Raw Field Value - display field with all HTML/formatting removed (similar to above, but supports parameters)
[cb:userdata field="FIELD_NAME" /]
The user [cb:userdata field="username" /] lives in [cb:userdata field="cb_citystate" /] and his name is: [cb:userdata field="name" /].
The user BobTBurns lives in Springfield, OH and his name is: Bob.
Original Field Value - display a field with all HTML/formatting rendered
[cb:userfield field="FIELD_NAME" /]
The user [cb:userfield field="username" /] lives in [cb:userfield field="cb_citystate" /] and his name is: [cb:userfield field="name" /].
The user BobTBurns lives in Springfield, OH and his name is: Bob.
In addition to being able to display fields with the new substitutions method you have a multitude of parameters that can be added to extend the substitution requirements. These additionally parameters are required to provide usage of the IF substitution.
user - userid, #me, #displayed, #displayedOrMe
usertype
user_id - myid, ##
username
Parameters
user
default - fields only
output - fields and tabs only ('html', 'xml', 'json', 'php', 'csvheader', 'csv', 'rss', 'fieldslist', 'htmledit')
formatting - fields and tabs only ('tr', 'td', 'div' (fields only), 'divs' (tabs only), 'span', 'none', 'table')
reason - fields and tabs only ('profile', 'register', 'list', 'edit', 'search')
list - userlist URL only
date - date format only
[cb:userdata field="FIELD_NAME" user="REPLACEMENT" /]
The user [cb:userdata field="username" user="#me" /] lives in [cb:userdata field="cb_citystate" user="62" /] and his name is: [cb:userdata field="name" user="#me" /].
The user BobTBurns lives in Branson, MO and his name is: Bob.
Parameters are also affected by operators which can change the way the the data is displayed or if it's even displayed at all.
Note: All parameters must come after the field (e.g. [cb:userdata field="FIELD_NAME" user="REPLACEMENT" /]) as anything otherwise (e.g. [cb:userdata user="REPLACEMENT" field="FIELD_NAME" /]) will not work.
Nested Substitutions
[cb:userfield field="FIELD_NAME" user="[FIELD_NAME]" /]
Nested substitutions allow you to use a substitution within a substitutions parameters. The parameters that allow for this are limited and they only accept raw value substitutions (e.g. [FIELD_NAME], [user_id], [username]). See the below list of parameters that accept nested substitutions.
user
default
date
In addition to supporting the above parameters you can used nested substitutions in IF conditions when comparing one field against another. Example as follows.
[cb:if user="#displayed" cb_mentor="[user_id]"]I am this users mentor.[/cb:if]
This can be used in a number of ways. For example cb_mentor stores the user id of a users mentor. You can then substitute in that mentors username using [cb:userdata field="username" user="[cb_mentor]" /].
Tab - display a CB rendered tab
[cb:usertab tab="TAB_ID" user="REPLACEMENT" /]
[cb:usertab tab="17" user="#displayedOrMe" /] will display CBs Menu tab for example.
Position- display a CB rendered tab position and all its tabs
[cb:userposition position="POSITION" /]
[cb:userposition position="cb_tabmain" /] will display CB tabs in the Main position for example.
Positions
canvas_menu = Canvas Menu
canvas_background = Canvas Background
canvas_stats_top = Canvas Stats Top
canvas_stats_middle = Canvas Stats Middle
canvas_stats_bottom = Canvas Stats Bottom
canvas_photo = Canvas Photo
canvas_title_top = Canvas Title Top
canvas_title_middle = Canvas Title Middle
canvas_title_bottom = Canvas Title Bottom
canvas_main_left = Canvas Main Left
canvas_main_left_static = Canvas Main Left Static
canvas_main_middle = Canvas Main Middle
canvas_main_right = Canvas Main Right
canvas_main_right_static = Canvas Main Right Static
cb_head = Header (above left/middle/right)
cb_left = Left side (of middle area)
cb_middle = Middle area
cb_right = Right side (of middle area)
cb_tabmain = Main area (below left/middle/right)
cb_underall = Bottom area (below main area)
L1C1 = Line 1 Column 1
L1C2 = Line 1 Column 2
L1C3 = Line 1 Column 3
L1C4 = Line 1 Column 4
L1C5 = Line 1 Column 5
L1C6 = Line 1 Column 6
L1C7 = Line 1 Column 7
L1C8 = Line 1 Column 8
L1C9 = Line 1 Column 9
L2C1 = Line 2 Column 1
L2C2 = Line 2 Column 2
L2C3 = Line 2 Column 3
L2C4 = Line 2 Column 4
L2C5 = Line 2 Column 5
L2C6 = Line 2 Column 6
L2C7 = Line 2 Column 7
L2C8 = Line 2 Column 8
L2C9 = Line 2 Column 9
L3C1 = Line 3 Column 1
L3C2 = Line 3 Column 2
L3C3 = Line 3 Column 3
L3C4 = Line 3 Column 4
L3C5 = Line 3 Column 5
L3C6 = Line 3 Column 6
L3C7 = Line 3 Column 7
L3C8 = Line 3 Column 8
L3C9 = Line 3 Column 9
L4C1 = Line 4 Column 1
L4C2 = Line 4 Column 2
L4C3 = Line 4 Column 3
L4C4 = Line 4 Column 4
L4C5 = Line 4 Column 5
L4C6 = Line 4 Column 6
L4C7 = Line 4 Column 7
L4C8 = Line 4 Column 8
L4C9 = Line 4 Column 9
L5C1 = Line 5 Column 1
L5C2 = Line 5 Column 2
L5C3 = Line 5 Column 3
L5C4 = Line 5 Column 4
L5C5 = Line 5 Column 5
L5C6 = Line 5 Column 6
L5C7 = Line 5 Column 7
L5C8 = Line 5 Column 8
L5C9 = Line 5 Column 9
L6C1 = Line 6 Column 1
L6C2 = Line 6 Column 2
L6C3 = Line 6 Column 3
L6C4 = Line 6 Column 4
L6C5 = Line 6 Column 5
L6C6 = Line 6 Column 6
L6C7 = Line 6 Column 7
L6C8 = Line 6 Column 8
L6C9 = Line 6 Column 9
L7C1 = Line 7 Column 1
L7C2 = Line 7 Column 2
L7C3 = Line 7 Column 3
L7C4 = Line 7 Column 4
L7C5 = Line 7 Column 5
L7C6 = Line 7 Column 6
L7C7 = Line 7 Column 7
L7C8 = Line 7 Column 8
L7C9 = Line 7 Column 9
L8C1 = Line 8 Column 1
L8C2 = Line 8 Column 2
L8C3 = Line 8 Column 3
L8C4 = Line 8 Column 4
L8C5 = Line 8 Column 5
L8C6 = Line 8 Column 6
L8C7 = Line 8 Column 7
L8C8 = Line 8 Column 8
L8C9 = Line 8 Column 9
L9C1 = Line 9 Column 1
L9C2 = Line 9 Column 2
L9C3 = Line 9 Column 3
L9C4 = Line 9 Column 4
L9C5 = Line 9 Column 5
L9C6 = Line 9 Column 6
L9C7 = Line 9 Column 7
L9C8 = Line 9 Column 8
L9C9 = Line 9 Column 9
not_on_profile_1 = Not displayed on profile 1
not_on_profile_2 = Not displayed on profile 2
not_on_profile_3 = Not displayed on profile 3
not_on_profile_4 = Not displayed on profile 4
not_on_profile_5 = Not displayed on profile 5
not_on_profile_6 = Not displayed on profile 6
not_on_profile_7 = Not displayed on profile 7
not_on_profile_8 = Not displayed on profile 8
not_on_profile_9 = Not displayed on profile 9
Date - display a preformated date based off current date and time
[cb:date format="PHP_DATE()_FORMAT" date="DATETIME" /]
[cb:date format="Y-m-d" /] will display 2011-02-14 for example. The timestamp used is always the current date and time unless a datetime is supplied to the date parameter.
URL - display a CB constructed URL (pre-defined)
[cb:url location="DESTINATION" /]
Destinations include: current, login, logout, registers, lostpassword, manageconnections, profile_view, profile_edit, list, itemid
[cb:url location="login" /] will display the login raw URL that can be included with HTML for example. For list usage you must specify the parameter list="LIST_ID"; without it you'll be given the default userlist URL.
Config - display system and user configuration (pre-defined)
[cb:config param="PARAMETER" /]
Parameters include: live_site, sitename, lang, lang_name, lang_tag
[cb:config param="lang_tag" /] will display en-GB for example. Only the predifined parameters will return a result. Other configuration parameters are not provided for security reasons.
Translate - translate and display language strings with substitutions applied
[cb:translate key="LANGUAGE_KEY" default="LANGUAGE_STRING_FALLBACK" /]
The language key must match an existing Community Builder language key within the language plugin or a language override language key. The default parameter is optional and will apply if the language key is missing from the loaded language plugin.
[cb:translate key="REGISTER_TITLE" /] will display "Join us!" for example. Additionally substitutions will again be applied to the resulting language string.
Ifs
[cb:if PARAMETER="REPLACEMENT"]TEXT/CODE[/cb:if]
Operators
and
or
= (equal)
> (greater than)
< (less than)
>= (greater than or equal)
<= (less than or equal)
!= (not equal)
=~ (is regex)
!~ (is not regex)
&& (and)
|| (or)
includes (checks if a value exists in an array of values)
!includes (checks if a value does not exist in an array of values)
contains (checks if a string exists within another string)
!contains (checks if a string does not exist within another string)
[cb:if username="demo"]This is Demo being displayed.[/cb:if]
[cb:if user_id="myid"]This is Me being displayed.[/cb:if]
[cb:if user="#displayed" username="test"]This is Test being displayed.[/cb:if]
[cb:if user="#me" username="demo"]This is Demo watching.[/cb:if]
[cb:if user="#me" usertype="Super Administrator"]User of type: Super Administrator[/cb:if]
[cb:if user="#displayedOrMe" user_id<="0"]I am A GUEST.[/cb:if]
[cb:if user="#displayedOrMe" user_id>"0"]I am NOT A GUEST.[/cb:if]
[cb:if user="#me" username!="admin"]This is NOT Admin watching.[/cb:if]
[cb:if viewaccesslevel includes "1"]I am Public[/cb:if]
[cb:if viewaccesslevel !includes "1"]I am NOT Public[/cb:if]
[cb:if usergroup includes "2"]I have Registered Usergroup[/cb:if]
[cb:if usergroup !includes "2"]I do NOT have Registered Usergroup[/cb:if]
[cb:if username="demo" or username="admin"]This is Demo or Admin being displayed.[/cb:if]
[cb:if username="demo" and cb_country="USA"]This is Demo being displayed from the USA.[/cb:if]
[cb:if application_context="frontend"]Frontend Only[/cb:if]
[cb:if application_context="administrator"]Backend Only[/cb:if]
[cb:if language_code="en"]English Only[/cb:if]
[cb:if language_tag="en-GB"]English Only[/cb:if]
[cb:if url contains "&listid=45"]The current URL contains &list=45 in it[/cb:if]
[cb:if menu_id="12"]The current menu item is Itemid 12[/cb:if]
Additionally you can nest multiple IF statements inside of one another as follows.
[cb:if username="demo"]This is Demo being displayed.[cb:if language_code="en"]English Only[/cb:if][/cb:if]
Elseifs
[cb:if username="demo"]This is Demo being displayed.[cb:elseif PARAMETER="REPLACEMENT"]TEXT/CODE[/cb:elseif][/cb:if]
You can chain together as many ELSEIF usages as necessary. This is similar behavior to using elseif in PHP and will stop at the first match that it can.
Elses
[cb:if username="demo"]This is Demo being displayed.[cb:else]TEXT/CODE[/cb:else][/cb:if]
Only one ELSE statement can be supplied per IF usage. If the IF and all ELSEIF conditions fail the ELSE content will be output.
There are many more possibilities. It's just a matter of trial and error to see what works for you.