| CallXML 3.0 Development Guide | Home | Frameset Home |
<if> tag is yet another container element that is identical in functionality to <block>, <do>, <with>, etc., that allows the developer to specify conditional logic using a more 'familiar' syntax. Specifying a 'test' attribute with a value will check to see if a particular condition is met; if so, the application will execute any statements enclosed within the <if> tag, then transition to the anchor specified in the 'next' attribute. If the condition is NOT met, the application will execute the next element it encounters from the top down.<block> aliases are listed as follows:<block><case><do><if><switch><with>| choices | Data Type: (grammar value) | Default: Optional |
The 'choices' attribute defines a list of comma delimited voice recognition utterances that will be active for the container element. Alternatively, the attribute can contain a choice followed parantheses containing different words which equate to that choice. Note that both dtmf grammars, and spoken word grammar utterances can be defined; digit values always indicate dtmf input, whereas spelled 'literals' for numbers imply that the grammar must be spoken:One can also define multiple matches to return the same value to the application by specifying the values in the following format: <ContainerElementName choices="ReturnValue (subchoice1, subchoice2)">As such, either of the 'subchoice' utterances will be interpreted as 'ReturnValue'. To illustrate in greater detail: <say choices="Beatles (john, paul, ringo, george), Lastly, developers can also make use of a builtin number grammar for capturing a string of digit values by specifying [x DIGITS], where 'x' is the length of the string that you wish to collect: <block choices="[5 DIGITS]"> This can also be modified to accept input of varying lengths by specifying [x-y DIGITS], where 'x' and 'y' are the minimum and maximum values for the length of the string being collected: <block choices="[5-8 DIGITS]"> | ||
| cleardigits | Data Type: (true|false) | Default: none - attribute is optional |
| This attribute's value is a Boolean, indicating whether the queued digits buffer should be cleared when this action starts. "true" clears the digits buffer; "false" leaves the contents of the digit buffer alone. | ||
| foreach | Data Type: (comma delimited list of array values) | Default: Optional |
| The 'foreach' attribute, usable on any CallXML3.0 container elements, should look familiar to many web developers. A developer can indicate a comma-delimited array of values to iterate through within 'foreach' attribute, and then use the 'var' attribute to specify the variable that will hold the current iteration value while in the enclosing container element. Alternatively, 'foreach' uses the "container.value" variable to store the current iteration if the 'var' is unspecified. and "container.value" will populate any unspecified 'value' attributes of child elements of the container in question. | ||
| id | Data Type: (element id) | Default: none - attribute is optional |
The new 'id' attribute in CallXML3.0 is applicable to all container and action elements. Specifying this attribute allows yet another level of control and event handling when events occur and are caught by the <on> element. When an event occurs, the handler will first check the event, and then verify that the handler has a handler specific to the 'id' attribute to execute. This allows the developer to plan a specific course of action for events based on where in the application that they occur. | ||
| label | Data Type: (navigation identifier) | Default: none - attribute is optional |
| This attribute designates the unique inter-document identifier of the parent element in question, and allows an easy way to navigate through applications as a destination 'anchor', as used in goto references | ||
| next | Data Type: (navigation identifier) | Default: none - attribute is optional |
| The 'next' attribute sets the URL the CallXML platform will go to when the container ends. | ||
| repeat | Data Type: (numeric value) | Default: 1 |
| The value for the repeat attribute indicates the number of times to execute the content contained by the parent element. If this attribute is explicitly specified, this must be a valid number, or an error will result. Also note that if the value is zero the content will be skipped. | ||
| test | Data Type: CDATA | Default: Optional |
| The 'test' attribute is a new supplement to the CallXML markup that permits the developer to execute the contents of a container element, or action element, based on whether or not the specified condition is met. If the defined condition is met, then the code contained within the element is then executed. If the condition is not met, then the application resumes execution with the next sequential container container element in the document. | ||
| test | Data Type: CDATA | Default: Optional |
| The 'test' attribute is a new supplement to the CallXML markup that permits the developer to execute the contents of a container element, or action element, based on whether or not the specified condition is met. If the defined condition is met, then the code contained within the element is then executed. If the condition is not met, then the application resumes execution with the next sequential container container element in the document. | ||
| value | Data Type: (string) | Default: none - attribute is optional |
The 'value' attribute is mappable to any of the container elements, (<block>, <with>, etc.), and specifies inheritance for attribute values that are enclosed within the container element. For instance, the below snippet will denote the values of 'test.wav' for the <playaudio>, <say>, and <log> elements : | ||
| value-is | Data Type: STRING | Default: none - attribute is optional |
| Another new attribute, 'value-is', grants the developer with the ability to perform conditional logic upon container elements, or action elements for the first time within the CallXML markup. The value specified in the 'value-is' attribute specifies a string to compare against any 'value' attributes. If the 'value' and 'value-is' equate to 'true', then the element specified will execute. If the value equates to 'false' then the element will be skipped during document execution. | ||
| value-is-not | Data Type: STRING | Default: none - attribute is optional |
| Another new attribute, 'value-is-not', grants the developer with the ability to perform conditional logic upon container elements, or action elements, for the first time within the CallXML markup. The value specified in the 'value-is-not' attribute specifies a string to compare against any 'value' attributes. If the 'value' and 'value-is-not' equate to 'false', then the element specified will execute. If the value equates to 'true' then the element will be skipped during document execution. | ||
| var | Data Type: (variable name) | Default: none - attribute is required |
| Variable name to use when assigning a value. Not specifying this attribute will result in a fatal error. | ||
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <if choices="Lenny, Squiggy"> <!-- both the 'say' and 'wait' elements have the same --> <!-- implied attribute values for choice as the 'if' element --> <say>you can choose Lenny, or you can choose Squiggy.</say> <wait value="5s"/> <on event="choice:Lenny"> <prompt> you chose lenny </prompt> </on> <on event="choice:Squiggy"> <prompt> you chose Squiggy </prompt> </on> </if> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <if label="B1" foreach="one.wav, two.wav, three.wav" var="cxmlVar"> <!-- the 'foreach' and 'var'attributes set up a loop --> <!-- construct that will iterate over the values defined in 'foreach' --> <playaudio value="$cxmlVar;"/> <say value="$cxmlVar;"/> <log value="$cxmlVar;"/> </if> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <if label="B1" repeat="1"> <say> here is the first if. </say> <goto value="#B2"/> </if> <if label="B2" repeat="2"> <prompt choices="*"> here is the second if. If you wait before pressing the star key, you will hear this text prompt play twice. </prompt> <on event="choice:*"> <prompt> you pressed the star key </prompt> </on> </if> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <if label="B_1" next="#B_3"> <prompt> once this container of TTS is executed, we will skip to if label B 3 via the next attribute </prompt> </if> <if label="B_2" next="Another_Document.xml"> <prompt> And finally, we enter if label B 2, which is executed last </prompt> </if> <if label="B_3" next="#B_2"> <prompt> And here we are in if label B 3 </prompt> </if> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <if test="1=1"> <prompt> this will execute, as 1 is equal to 1. </prompt> </if> <if test="'foo' = 'bar'"> <prompt> this will not execute, as foo is not equal to bar. </prompt> </if> <if test="string"> <prompt> this will execute, as the test element returns a non empty string. </prompt> </if> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <if value="feelgood.wav"> <!-- we do not need to define a 'value' attribute for the --> <!-- enclosed elements, as the container element will --> <!-- inherently populate these fields with it's own --> <!-- 'value' that is specified --> <playaudio/> <log/> <say/> </if> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <!-- illustrates value-is attribute --> <if label="B1" value="foo" value-is="foo"> <log/> <say> this will execute, as the value is equal to foo </say> </if> <if label="B2" value="foo" value-is="bar"> <log/> <say> this will not execute, as the value is not equal to bar </say> </if> <!-- illustrates value-is-not attribute --> <if label="B3" value="foo" value-is-not="foo"> <log/> <say> this will not execute, as the value is not equal to bar </say> </if> <if label="B4" value="foo" value-is-not="bar"> <log/> <say> this will execute, as the value is not equal to bar </say> </if> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <cfheader name="Cache-Control" value= "no-cache"> <cfheader name="Expires" value="#Now()#"> <callxml version="3.0"> <assign var="myVar" value="bar"/> <!-- THIS WILL BE SKIPPED --> <if test= "'$myVar;' = 'foo'"> <say> my var is foo. </say> </if> <!-- THIS WILL BE EXECUTED --> <if test= "'$myVar;' = 'bar'"> <say> my var is bar. </say> </if> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <if choices="[4 DIGITS]"> <say> Enter your 4 digit pin. </say> <wait value="5s"/> <on event="choice"> <say> The pin you entered, was </say> <playnumber format="digits" value="$session.lastchoice;"/> </on> </if> </callxml> |
| ANNOTATIONS: EXISTING POSTS |
jpw
|
|
| Your 'static' <if test> examples are not useful:
<if test="1=1"> <if test="'foo' = 'bar'"> <if test="string"> How about adding a real world example where you test a VARIABLE against a value? Here $loginresult is a 'true' or 'false' result code after authenticating a user's account number via a fetch (from an xml file in this example, could be dynamically generated xml from a server-side app). IF it's true, then you'll also return the url to the recorded audioname in the variable and say it: <fetch cache="no" value="http://www.mydomain.com/testresult.xml" var="myxml" type="xml" /> <with value="$myxml;"> <assign var="loginresult" expr="/var/myxml/loginresult/text()" /> <assign var="useraudioname" expr="/var/myxml/useraudioname/text()" /> <say>The login result code is $loginresult; </say> *** HERE'S WHAT YOU NEED TO SHOW: *** *** BTW if you have an extra space before or after the variable name it does NOT work *** because then you are comparing 'true ' = 'true' <if test="'$loginresult;' = 'true'"> <say> Your pre-recorded user name is </say> <playaudio value="$useraudioname;" /> </if> </with> *** sample data testresult.xml**** <?xml version="1.0" encoding="UTF-8"?> <userinfo> <loginresult>true</loginresult> <useraudioname>http://mydomain.com/audios/names/12345.wav</useraudioname> </userinfo> *** or to test false result *** <?xml version="1.0" encoding="UTF-8"?> <userinfo> <loginresult>false</loginresult> <useraudioname></useraudioname> </userinfo> |
|
jpw
|
|
| now, how would you do a "ISNOTEQUALTO" test? Eg, in the example I just provided above, what is the syntax to add:
<if test="'$loginresult;' ISNOTEQUALTO 'true'"> <say> Login was not successful. Sorry. </say> </if> Of course, in my simple true/false example I can of course compare <if test="'$loginresult;' = 'false'"> But, if you're testing on more complex data a "NOT EQUAL" operator is pretty useful... is there one? |
|
voxeojeff
|
|
| Hello,
In order to do 'is not equal to' you'll want to use '!=': <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <if test="'foo' != 'bar'"> <say> this will execute, as foo is not equal to bar. </say> </if> </callxml> Regards, Jeff |
| login |