| CallXML 3.0 Development Guide | Home | Frameset Home |
<block> element is used to logically group action and event elements together, as well as providing the ability to loop the actions in the block a specified number of times. Note that <block> elements may be nested within each other to foster more structured CallXML interface code. <block> element, which are identical in functionality, which allows you to pick a naming/programming scheme for container elements on a per-case basis that suits a developer's programming style. All of these identical <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. | ||
| 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 optional |
| The 'var' attribute is used to specify the variable that will hold the current iteration value while in a particular container, when a comma-delimited list of values is to be looped through. | ||
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <block label="B1" repeat="1"> <prompt> here is the first block. </prompt> <goto value="#B2"/> </block> <block label="B2" repeat="2"> <prompt choices="*"> here is the second block. 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> </block> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <block label="B_1" next="#B_3"> <prompt> once this block of TTS is executed, we will skip to block label B 3 via the next attribute </prompt> </block> <block label="B_2" next="Another_Document.xml"> <prompt> And finally, we enter block label B 2, which is executed last </prompt> </block> <block label="B_3" next="#B_2"> <prompt> And here we are in block label B 3 </prompt> </block> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <block choices="Laverne, Shirley"> <!-- both the 'say' and 'wait' elements have the same --> <!-- implied attribute values for choice as the 'block' element --> <prompt> You can choose Laverne, or you can choose Shirley. </prompt> <wait value="5s"/> <on event="choice:Laverne"> <prompt> you chose Laverne </prompt> </on> <on event="choice:Shirley"> <prompt> you chose Shirley </prompt> </on> </block> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <block 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;"/> </block> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <block test="1=1"> <prompt> this will execute, as 1 is equal to 1. </prompt> </block> <block test="'foo'='bar'"> <prompt> this will not execute, as foo is not equal to bar. </prompt> </block> <block test="string"> <prompt> this will execute, as the test element returns a non empty string. </prompt> </block> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <block value="feelgood.wav"> <!-- we do not need to define a 'value' attribute for --> <!-- the enclosed elements, as the container element --> <!-- will inherently populate these fileds with it's own --> <!-- 'value' that is specified --> <playaudio/> <log/> <say/> </block> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <!-- illustrates value-is attribute --> <block label="B1" value="foo" value-is="foo"> <log/> <say> this will execute, as the value is equal to foo </say> </block> <block label="B2" value="foo" value-is="bar"> <log/> <say> this will not execute, as the value is not equal to bar </say> </block> <!-- illustrates value-is-not attribute --> <block label="B3" value="foo" value-is-not="foo"> <log/> <say> this will not execute, as the value is not equal to bar </say> </block> <block label="B4" value="foo" value-is-not="bar"> <log/> <say> this will execute, as the value is not equal to bar </say> </block> </callxml> |
| <?xml version="1.0" encoding="UTF-8" ?> <callxml version="3.0"> <!-- caller can say 'Run DMC' at any point during the TTS --> <!-- playback, and the event handlers will detect which --> <!-- container element the user was in when the utterance was detected --> <block id="B1" choices="run D M C"> <prompt value="Its tricky to rock around."/> <wait value="2s"/> </block> <block id="B2" choices="run D M C"> <prompt value="Thats right."/> <wait value="2s"/> </block> <block id="B3" choices="run D M C"> <prompt value="On time."/> <wait value="2s"/> </block> <block id="B4" choices="run D M C"> <prompt value="It's tricky."/> <wait value="2s"/> </block> <on event="choice" target="B1"> <log>** a choice match occurred while in container element B1 **</log> </on> <on event="choice" target="B2"> <log>** a choice match occurred while in container element B2 **</log> </on> <on event="choice" target="B3"> <log>** a choice match occurred while in container element B3 **</log> </on> <on event="choice" target="B4"> <log>** a choice match occurred while in container element B4 **</log> </on> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <assign var="myVar" value="bar"/> <!-- THIS WILL BE SKIPPED --> <block test= "'$myVar;' = 'foo'"> <say> my var is foo. </say> </block> <!-- THIS WILL BE EXECUTED --> <block test= "'$myVar;' = 'bar'"> <say> my var is bar. </say> </block> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <block 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> </block> </callxml> |
| ANNOTATIONS: EXISTING POSTS |
awirtz
|
|
| Maybe I'm misunderstanding something, but the "test" attribute in CallXML 3 seems not to behave in the manner indicated by the examples and documentation.
I try to use the "block-test" example verbatim, and I receive the error: event: error "document" (Invalid XPATH parameters: test='string', value='') As far as I can tell, the ECMA Script support has been completely overridden by the XPath support, and this breaks the ability to do simple variable-based tests as shown in the example. In addition to the fatal error I mentioned above, the block-test example quietly fails to execute either of the other two blocks (1=1 and 'foo'='bar') -Aaron |
|
awirtz
|
|
| Okay, so I think I have it straightened out. First of all, the contents of the the "prompt" blocks do not get read at all. So I guess this partially answers my question elsewhere about "value" being magic. And second, the variable "string" is not defined.
So the corrected version would read: <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <block test="1=1"> <prompt value="this will execute, as 1 is equal to 1." /> </block> <block test="'foo'='bar'"> <prompt value="this will not execute, as foo is not equal to bar." /> </block> <assign var="string" value="baz" /> <block test="string"> <prompt value="this will execute, as the test element returns a non empty string." /> </block> </callxml> |
|
voxeojeff
|
|
| Hello Aaron,
It seems you've stumbled upon something quite peculiar here. I'll run this by our CallXML 3.0 gurus and see what they have to say about this. Per my testing, however, I came up with the same results as you did. Thanks for bringing this to our attention! :-) Regards, Jeff Menkel Voxeo Corporation |
|
awirtz
|
|
| It seems as though a block with a label can only be the target of a "goto" or "next" if it is a top level block (direct child of the callxml element). I could be mistaken, and I don't have a simple test case right now, but in a more complex application I was working on, I was getting errors trying to "goto" a non-top-level block, and as soon as I made it a top-level block, it started working.
[edit] ...okay, some more elaboration now that I had a few minutes to look at this in more detail. It seems that top-level blocks are valid targets, and so are siblings of the "goto" element, but anything else is invalid and generates the error "invalid target X in scope Y for goto or next attribute" Example code follows: <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <answer /> <block label="one"> <say>one</say> <block label="two"> <say>two</say> <goto value="#three" /> <block label="three"> <say>three</say> </block> <goto value="#four" /> </block> <block label="four"> <say>four</say> </block> </block> <exit /> </callxml> -Aaron |
|
voxeojeremy
|
|
| Aaron,
This is one of the rules of using <goto/>. From the docs: " The rule for goto is that you can go to: * any block in the same scope in the same document * any block in the root scope of any document " You will notice that the following code works fine, because the <goto/> elements never direct the session outside of the current scope. <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <answer /> <block label="one"> <say>one</say> <block label="two"> <say>two</say> <goto value="#three" /> <block label="three"> <say>three</say> </block> <goto value="#four" /> <block label="five"> <say>five</say> </block> <block label="six"> <say>six</say> </block> <goto value="#end"/> <block label="four"> <say>four</say> </block> <goto value="#five"/> <block label="end"> <exit/> </block> </block> <exit/> </block> </callxml> If you have other questions about block, feel free to post here. If you are trying to do something with your code that you cannot do with <goto/>, please create an account ticket, and we can help you solve the problem one-on-one. Thank you! :) Jeremy McCall Voxeo Extreme Support |
|
awirtz
|
|
| Thanks Jeremy,
I didn't see that restriction on "goto". I already have my code working around this limitation. The same-or-root-scope thing just confused me for a while because I had started with some code that performed a "goto" from inside a block to a root level target - that worked fine - and then as soon as I copied and pasted it wholesale into a more complex block structure so that the target was no longer root-level, it stopped working and it wasn't immediately obvious to me why. -Aaron |
|
zoop
|
|
| Am I right in thinking that <block>'s next= function has changed. in the past it would submit the relative variables and now when looking at the application debugger I see submit=""
Example block <block label="me" next="mypage.php"> <assign var="test" value="hello"/> </block> seems in callxml 2.0 this was submitting the variables. |
|
MattHenry
|
|
|
Hello Zoop, Correct you are; thank you for catching this bug for us! I have opened [b]internal bug ticket 637072[/b] so that we can address this in a future Build, but I did want to mention that you can work around this by specifying a <goto next="[target]" submit="*"/> within the container element. Note that the root cause of the bug appears to be such that this will manifest itself when a goto directive is issued and a 'submit' attribute is NOT defined. Regards, ~Matthew Henry |
|
MattHenry
|
|
|
Zoop, It appears as if this change in behavior is as intended in this case. We will make a point to note this in our next round of CallXML 3.0 documentation updates/edits. Regards, ~Matthew Henry |
| login |