We have moved!

You are currently looking at documentation for Umbraco 8 and older versions.
An automated guess is that docs.umbraco.com/umbraco-forms/developer/magic-strings/ could be the link to the new documentation for Umbraco 9 and newer versions.

    Magic strings

    Umbraco Forms has some magic strings that enable you to render values from various sources, such as session, cookies and Umbraco page fields.

    Where can I use magic strings?

    Magic strings can be used in form fields as a label, description or default value. As an example they can be used in default values in hidden fields - normally in the form of referral codes from a session, cookie or request item.

    These values can also be used for properties and settings in workflows. This means you can use name and email fields from a form to create a personal 'Thank you' email.

    Request

    [@SomeRequestItem] this allows you to display an item from the current HttpContext.Request with the key of 'SomeRequestItem'.

    Some examples of variables that are normally available in HttpContext.Request:

    • [@Url]: Insert the current URL
    • [@Http_Referer]: The previous visited URL (if available)
    • [@Remote_Addr]: The IP address of the visitor (stored by default by Umbraco)
    • [@Http_User_Agent]: The browser of the visitor

    The variables are not case-sensitive.

    Dictionary Items

    For multi-lingual websites, rather than hard-coding labels like form field captions, a dictionary key can be entered as #MyKey. When the form is rendered, the placeholder will be replaced by the value of the dictionary item identified by the key, according to the current language.

    Session & Cookies

    [%SomeSessionOrCookieItem] this allows you to display an item from the current HttpContext.Session with the key of 'SomeSessionOrCookieItem'. The session key can only contain alphanumeric chars and you cannot use dots for example. [%Member.Firstname] cannot be used, but [%MemberFirstname] can be used. You would have to fill these session keys yourself.

    If the item cannot be found in the collection of session keys, it will then try to find the item from the HttpContext.Cookies collection with the same key.

    Umbraco Page field

    [#myUmbracoField] this allows you to insert a property of that page and is based on the alias of the field. If your page has a property with the alias 'title', you can use [#title] in your form.

    Some extra variables are:

    • [#pageName]: The nodename of the current page
    • [#pageID]: The node ID of the current page

    Recursive Umbraco Page field

    [$myRecursiveItem] this allows you to parse the Umbraco document-type property myRecursiveItem. So if the current page does not contain a value for this then it will request it from the parent up until the root or until it finds a value.

    Parsing Umbraco Form field

    {myAliasForFormField} this allows you to display the entered value for that specific field from the form submission. Used in workflows to send an automated email back to the customer based on the email address submitted in the form. The value here needs to be the alias of the field, and not the name of the field.

    Some extra variables are:

    • {record.id}: The ID of the current record
    • {record.updated}: The updated date/time of the current record
    • {record.created}: The created date/time of the current record
    • {record.umbracopageid}: The Umbraco Page ID the form was submitted on
    • {record.uniqueid}: The unique ID of the current record
    • {record.ip}: The IP address that was used when the form was submitted
    • {record.memberkey}: The member key that was used when the form was submitted

    Parsing Member properties from a form submission

    {member.FOO} with the prefix of member. in the same syntax above will allow you to retrieve information about the submission if it was submitted by a logged in member.

    How can I parse these values elsewhere in my C# code or Razor Views?

    The Umbraco.Forms.Data.StringHelpers class contains a helper method ParsePlaceHolders that can be used for parsing magic strings. There are a few overloads available for use depending on the context. Some of these are obsoleted as of Forms 8.10.0, so the best options to use are listed below.

    If parameters for the Record or Form are omitted, magic strings relating to these objects will be removed.

    ParsePlaceHolders(string value, Record record = null, Form form = null, Hashtable pageElements = null) {} // will use HttpContext.Current

ParsePlaceHolders(string value, HttpContext context, Record record = null, Form form = null, Hashtable pageElements = null) {}

ParsePlaceHolders(string value, HttpContextBase context, Record record = null, Form form = null, Hashtable pageElements = null) {}

    There is also a public extension method ParsePlaceHolders() extending the string object in the Umbraco.Forms.Core.Extensions namespace, again available with some overloads allowing the provision of a Form or Record object if available.

    Prev: Configuration                 Next: Health Checks