CMRL Reference

The a is a shortcut for an anchor which refers to a query . The query attribute specifies the query to execute if the link is followed.

For example:

<match pattern="">
  <message>
    <content>Get help on <a query="example.com help">Example</a>.</content>
  </message>
</match>

In this example, the message will be displayed as e.g. "Get help on Example(1)." If the user responds to the number corresponding to the link (1 in this example) then the query "example.com help" is executed as if the user had texted it directly.

The anchor element defines an SMS link. When the message is sent to the user, the anchor element is replaced with the text contained in the link, if any, followed by a number in parenthesis corresponding to the reply the user should send to follow the link. When the user replies with this link text, the terminating node in the anchor is evaluated.

For example:

<match pattern=""> 
    <message>
      <content>Read <anchor>our blog<rss href="http://www.example.com/rss.xml"/></anchor></content>
    </message>
  </match>

This example will send the message "Read our blog(1)" to the user. If the user replies with the message "1", then they will be sent the result of the RSS tag (i.e. a listing of the stories in the RSS feed).

The block element is a terminating node. A block must contain exactly one terminating node, but can contain additional CMRL nodes as well. A block allows a terminating match to execute more than one statement.

For example, the following match:

<match pattern="vote">
  <block>
    <keywords>
      <keyword>red</keyword>
      <keyword>blue</keyword>
    </keywords>
    <set name="voted">1</set>
    <engine ref="http://www.example.com/cgi-bin/vote" />
  </block>
</match>

Results in an engine being called, after the set and keywords have been evaluated.

The br element specifies a linebreak.

The cmrl tag is the root tag for CMRL documents.

The content node is contained in a message and specifies the content of a message.

The engine element is used to call an external program (i.e. CGI script). The only requirement of an external enging program is that it print out exactly one terminating node. See http://dotgo.com/support/documentation/ for more information.

The get element is used to insert the contents of a session variable (which are set either with set or an input ).

For example:

<match pattern="welcome">
  <message>
    <content>Welcome <get name="first_name"/> <get name="last_name"/>!</content>
  </message>
</match>

If e.g. set had been used to set the variable first_name to "Eduardo" and the variable last_name to "Gaminga", then this message might be sent to the user as "Welcome Eduardo Gaminga!"

The input element provides a way for obtaining an arbitrary response from the user and optionally storing it in a session variable. The name attribute specifies the name of the variable to be set, and the terminating node inside the input specifies where the result of the input should be sent. For example, the match

<match pattern="login"
  <message>
    <content>Reply with your first name.</content>
    <input name="full_name">
      <engine href="http://example.com/cgi-bin/login.cgi" />
    </input>
  </message>
</match>

sends the message "Reply with your first name." to the user. The next message the user sends is interpreted as input and will be used to set the variable "full_name". Finally, in this example, the engine will be called, and the result will be sent to the user.

The keyword tag defines an allowable keyword for a block. keyword s are enclosed in a keywords tag.

The keywords tag is a container for keyword tags.

The match tag provides the fundamental structure of CMRL. A match tag defines a pattern which is to be matched to an incoming query. For example, the following CMRL fragment:

<match pattern="john smith">
  <message><content>My name is John Smith.</content></message>
</match>

specifies that a token matching "john smith" in the incoming query will result in the response "My name is John Smith." A match tag can only contain either additional match tags or exactly one terminating node. For example,

<match pattern="john smith">
  <match pattern="">
    <message><content>My name is John Smith.</content></message>
  </match>

  <match pattern="office">
    <message><content>My office is located in room 233.</content></message>
  </match>
</match>

This CMRL fragment specifies that the query "john smith" will still return "My name is John Smith", but the query "john smith office" will now return the response "My office is located in room 233."

Special allowable match patterns are "" (the null match, corresponding to no additional tokens in the query), and "*" (the default match, corresponding to a match if no other suitable match is found.

If the loose attribute is not set to "0" (or if it is omitted), then the CMRL parser will use a loose parsing algorithm to match queries in a very flexible way. For example, if the match pattern is "john smith", then the interpreter might match "john", "jsmith", "js", or "jon", if these can be unambiguously identified with the pattern. N.B.: match patterns which are to be used for e.g. passwords should have loose set to 0 so that they must be matched exactly.

See http://dotgo.com/support/documentation/ for more about how queries are matched to CMRL documents.

The message element is used to define a message which is sent to the user. A message must have exactly one content , and optionally may include an input element to read a response from the user. The message element is a terminating match.

The query element is a terminating match. It can be used to return the result of another query, or can be placed in an anchor or input to specify the destination query for the user input.

The rss tag is a terminating match used to return an RSS feed as a formatted message. The href attribute specifies the http destination of the RSS feed. If neither story nor link are specified, rss returns a menu of the stories in an RSS feed as a message. The story attribute is an 1-based index corresponding to the item tags in the feed. If story is specified then the corresponding item is returned as a message. If link is specified, then the links for the RSS stories are displayed. If both link and story are specified, then the link corresponding to the story is pushed to the phone. Depending on the phone, this may result in the story automatically opening in the phone's web browser, if supported.

The set element sets a session variable. The attribute name specifies which session variable is to be set. A session variable can be unset by using a set with no value.

The url tag is used in to replace a url with a shortened SMS-safe version. For example, the following message:

<message><content>For more information visit <url>http://www.example.com/sdflj/~lksdfd?bsdf=123032-123322-123132&prod=39482342&output=2342341234</url></content></message>

would result in a message such as

For more information visit http://dotgo.com/2vrb3f

When the end user accesses the resulting url they will be automatically redirected to the url specified in the url tag. It is recommended that all urls be encoded in this way, for several reasons: (1) some urls contain characters (such as ~) that are not present in the default GSM 7-bit alphabet (and are hence stripped); and (2) this tag produces urls that are preferentially not split between messages.