Author: Dave Smith
Posted on: 2015-12-01
Package: PHP dotGo Engine
Read this article to learn how to how to use the PHP DOTGo Engine package to handle more complex responses using DOTGO Web service's terminating nodes.
What Are Terminating Nodes?
Available Terminating Nodes
In the previous article, it was introduced to the Concise Message Routing Language (CMRL) - a XML format used by the DOTGO web service, the basic usage of the PHP dotGo engine package, and the message terminating node.
In this article we are going to explore all the available terminating nodes, how they work with our message service and how the PHP dotGo Engine can help us manage them.
I will be providing examples using the administration interface from the PHP dotGo Engine, so if you have already installed it I recommend starting it up to help you follow along.
What Are Terminating Nodes?
In CMRL, each match element must contain at least one terminating node. A terminating node is an element that completes a request by either returning a message, passing the request off to another node or starting special internal processing of content by the DOTGO web service.
Available Terminating Nodes
There are five types of terminating nodes which are the <message>, <query>, <block>, <rss/> and <engine/> elements.
We have already seen the <message> element at work in our previous article, so I will only provide a quick refresher here. The <message> element contains one <content> element that returns the message to be sent to the user. Ultimately we want to return content to the user, so most roads eventually end with this element.
We have also seen the <engine/> element at work and is how we point the DOTGO service to the PHP dotGo engine. Just to refresh our memories, the <engine/> element contains the href property which is the URL of the engine we want to use.
A separate engine can be developed to manage different request or they can be chained together. We will be discussing these features in greater detail in another article.
The <query> element terminates the current request with a new request that we specify in the element. In CMRL it looks like this...
Using this example, we would have matched the request 'yoursite howdy' and told the DOTGO service to actually process the request as if the user had sent 'yoursite hello'.
To set this up using the PHP dotGo Engine, we will start at the root keywords and add the new keyword 'howdy'.
We click on our keyword 'howdy' where we can then add the query content to it by selecting query from the radio button choices. We add the keywords we want DOTGO to process in the content section, in this case just the keyword 'hello' and submit it.
Notice that we did not enter the yoursite designator. The PHP dotGo engine does this for us with query content. If everything was done correctly, the response shown on the screen should look like the proper query in CMRL.
Consider anticipating other ways a user may say hello and adding those as keyword queries which send them to the correct place to interact with us through the 'hello' message.
The <rss/> element points to a Really Simple Syndication (RSS) news feed, which is internally processed by the DOTGO service. It will parse the RSS feed and prompt the user to select which article they want to view. In CMRL it looks like this...
Using this example, we would have matched the request 'yoursite news' and provided the URL to our RSS news feed. DOTGO would then process the feed and manage the rest of the interaction with our user.
To set this up using the PHP dotGo Engine, we will start at the root keywords and add the new keyword 'news'.
We click on our keyword 'news' where we can then add the rss content to it by selecting rss from the radio button choices. We add the full URL to our news feed in the content section.
If you do not have your own RSS feed to try this out with, use phpClasses latest packages feed by using the URL http://feeds.feedburner.com/phpclasses as your news feed content.
Consider adding the keyword 'rss' as a query that points to the correct keyword 'news'. Honestly, how much fun are you going to have with this?
The <block> element allows us to group elements together, well... in a block. DOTGO refers to these other elements as helper elements which are used to define <keywords> or <set> variables. In this article we will be looking at the <keywords> element used in conjunction with the <block> element.
So far our users have sent requests exactly as we expect to receive them and if they are not exact, they get our failed response message. Not very user friendly since we should expect our users to make a mistake once in awhile. What happens if a user sends the request 'yoursite helo', misspelling hello?
We could add the keyword 'helo' as a query to points to the correct keyword 'hello', however we would have to anticipate every possible misspelling... not the best solution. Instead, DOTGO provides a way for us to tell them what keywords we expect and they use this to correct the users input whenever possible. This is the purpose of the <keywords> element.
In CMRL it looks like this...
<content>Keywords have been set</content>
Here we have set up a block of keywords that terminate with a message. The request 'yoursite setkeywords' is actually something our users would not use, instead it is a request we would send to initialize DOTGO with our specific set of expected keywords.
This only needs to be done once since the keywords persist on the DOTGO service and only sent again if we have made changes to them.
<block> elements must contain a terminating node, in this case it is a <message> element and can contain helper elements, here it is the <keywords> element. Notice that the <keywords> (with an s) element contains multiple <keyword> elements, which are the actual keywords we expect.
To set this up using the PHP dotGo Engine, we will add a new root keyword 'setkeywords' and after selecting it we will add custom content. The custom content selection is use to add complete CMRL, so in this case we will be adding the complete <block> element including the <keywords> and <message>. We do not need to add the match pattern since that was done when we added the keyword 'setkeywords'.
Once the keywords have been initialized, whenever a user requests 'yoursite helo', DOTGO will correct the keyword to 'hello'.
In this article we have worked our way through all five of the terminating nodes and hopefully you have a better understanding on how they are used. At this point you should have enough information to put together a powerful request and response text message service.
Keep on the lookout for more articles about using the DOTGO service, like setting your system up to get information from your users... for starters.
You need to be a registered user or login to post a comment
Login Immediately with your account on:
No comments were submitted yet.