Update Tags

U-Tags are tags used to indicate an update processing operation. These tags set temporary parameters when a template or page renders.

Like the T-Tag, the sub-template is parsed and compiled at the same time as the parent template. At render time, the sub-template is evaluated, and the result is passed as the command string to the update operation, which then parses it and performs an update to the context.

Operation codes and their syntaxes are listed below. - see also constants at the top of Template.

Format

  • Bracket

[[Un:template]]

Where n is a code for the operation, 0-3, or 8.

  • XML

    <convio:update {op="session-blank | session-value | group-add | group-rm"} template="variable assignment or numeric value">

Operation Codes

U0 and U1

The U0 and U1 tags are used to set session parameters.

[[U0:String1=String2]] - Sets the value of String1 to String2 and returns a null string to the template. This essentially is an invisible set command.

[[U0:SESSION_VALUE_FOO=This is a session value.]] [[U1:String1=String2]] - Sets the value of String1 to String2 and returns String2 to the template. This allows you to simultaneously set and use a value.

Values are retrieved using the S80 session tag.

  • U0: ( session-blank) sub-template is rendered, and then parsed by being treated as a name = value pair. The Session Parameter name is updated or added to the current session, with the value given. The value may contain any ISO-8859-1 content, including template-sensitive characters and equals signs, and may be an empty string, but will be stripped for high-bit and binary characters, and non-ISO-8859-1 symbols. The name must be at least one character. Updates which would exceed the Session Parameter system limitations will fail silently. The U0 tag always returns the empty string into the parent rendering output. This is the default operation if none is supplied.

  • U1: ( session-value) this evaluates identically to U0, except that the value is returned into the rendered output.

U2 and U3

The U2 and U3 tags are used as hidden group updates for logged in constituents.

You can use a U2 or U3 tag to add or remove people from groups when they visit particular pages on the customer site.

This is done by using the following context:

U2:groupID to add someone to a group

U3:groupID to remove someone from a group

Because the tags produce either a SUCCEEDED or FAILED result if the person is added, you will need the comment tags in order for this to be a "hidden" update.

  • U2: ( group-add) sub-template is rendered and parsed as an integer. If the current session is a logged in user and the integer is a valid group id, the user will be added to the group. Will not work for "factory" groups (gid < 1000) nor admin users. If and only if the update results in a change, the group cache / perm cache will be invalidated so the effect is instantaneous, but overhead of repeat use is low. The rendered output result from U2 is a status message, which will be one of three things:

    • SUCCEEDED - The update was made

    • NO ACTION - The user was already a member of the group

    • FAILED_[: reason]_ - The update was not made. You can just test for FAILED and not consider reasons, though reasons include:

      • ADMINISTRATOR

      • NOT LOGGED IN

      • RESTRICTED GROUP

      • BAD GROUP ID

    The output from the [[U2:nnnn]] tag is not intended for display, so it should be suppressed by using it inside another tag such as a conditional.

    Since it has a side effect, the template macros should be arranged so it only executes once. If you want to test the output for multiple different outcomes, don't use multiple U2s because they can return different results (For example, SUCCEEDED followed by NO ACTION). Instead, place U2 inside a U0 or U1 and then use S80s to test it.

    Use U2 to personalize the UI in response to a user action by placing a U2 tag in a customized template which that action renders (For example, implementing membership by dropping U2 on the Donations thank-you template).

    The U2 tag generates text about the status of the group update when the page is loaded, so put the tag into an HTML comment to prevent that text from displaying to constituents on a page. For example: <!--[[U2:12461]]--> - where 12461 is the Group ID.

  • U3: ( group-rm) Removes the user to whom the current session belongs from a group. Syntax and behavior are exactly as U2.

U8: Sets the Content-Type on the HTTP Response. For example: [[U8:application/xml]]

Note: We do not recommend the use of U4 - U7.

Examples:

[[U0:foo=This is the value of the foo Session Parameter]] [[U2:1234]]

<!-- Set the Affiliate session variable -->

<convio:update op="session-blank" template="Affiliate=PM_" />