EXAMPLES

==============================
IMPULSE PLUGIN EXAMPLE: SiLCC
==============================

The nature of the core architecture means that many of the key components of your SwiftRiver installation are, in fact, plugins themselves. For this example, we'll take a look at the SwiftRiver Language Computational Core (SiLCC).

The SiLCC is responsible for applying natural language processing to content that comes into your SwiftRiver instance. At the moment, we're less worried about 'what' it does and more interested in 'how' the core platform interfaces with this cloud based service.

Lets see a bit of code (lines have been removed to ensure that the example is readable):

01. namespace SwiftRiver\PreProcessingSteps;
02. include_once (dirname(__FILE__)."/ContentFromJSONParser.php");
03. include_once (dirname(__FILE__)."/ServiceInterface.php");
04. include_once (dirname(__FILE__)."/TextForUrlParser.php");
05.
06. class SiLCCPreProcessingStep implements \SwiftRiver\Core\PreProcessing\IPreProcessingStep {
07.
08.     public function Description(){
09.         return "This plugin sends all content to the Swift Web Service: " .
10.                "SwiftRiver Language Computational Core (SiLCC). It then attempts " .
11.                "to apply auto-tag content with relevant keywords.";
12.     }
14. 
15.     public function Name(){
16.         return "SiLCC";
17.     }
18. 
19.     public function Process($contentItems, $configuration, $logger) {
20. 
21.         //if the content is not valid, jsut return it
22.         if(!isset($contentItems) || !is_array($contentItems) || count($contentItems) < 1) {
23.             return $contentItems;
24.         }
25. 
56.         //set up the return array
27.         $taggedContentItems = array();
28. 
29.         foreach($contentItems as $item) {
30. 
31.             //construct a new Url parser
32.             $urlParser = new \SwiftRiver\SiLCCInterface\TextForUrlParser($item);
33. 
34.             //get the url formatted text
35.             $text = $urlParser->GetUrlText();
36. 
37.             try {
38.                 //construct a new service interface
39.                 $service = new \SwiftRiver\SiLCCInterface\ServiceInterface();
40. 
41.                 //call the service through the interface
42.                 $json = $service->InterafceWithService("http://opensilcc.com/api/tag", $text, $configuration);
43.             }
44.             catch (\Exception $e) {
45.                 continue;
46.             }
47. 
48.             //Construct a new result parser
49.             $jsonParser = new \SwiftRiver\SiLCCInterface\ContentFromJSONParser($item, $json);
50. 
51.             //get back the tagged content from the parser
52.             $taggedContent = $jsonParser->GetTaggedContent();
53. 
54.             //Add the content to the return array
55.             $taggedContentItems[] = $taggedContent;
56.         }
57. 
58.         return $taggedContentItems;
59.     }
60. 
61.     public function ReturnRequiredParameters() {
62.         return array();
63.     }
64. }

So, lots of the above code should be becoming familiar to you by now: 

Lines 01. and 06. contain the basic namespace and class decoration for an Impulse Turbine.

Lines 08. to 12, 15. to 17. and 61. to 63. contain simple implementation of the Name, Description and ReturnedRequiredParameters functions. Nothing new here really, the implementations above are very similar to the ones we looked at in previous examples.

The real differences in this implementation is the complexity of what this Turbine is trying to achieve: The first thing to note is that lines 02. to 04. contain the include statements for all the code files that this Turbine is dependent on. You will see that there is no need to include code files such as the one containing the definition of the Content object, these are automatically included by the SwiftRiver Core Framework. You do however, need to include any of your own code files that are required to run the Process method of your Turbine.

In the case of this Turbine, three class files are included: 

		ContentFromJSONParser.php
		Used to parse JSON returned from SiLCC Web Service and add the associated data to the original Content item.

		ServiceInterface.php
		Used to wrap the connectivity code required to interface with the SiLCC service.

		TextForURLParser.php
		Used to extract and format the text that should be sent to the SiLCC service from a given Content item.

Now lets take a look at the implementation of the IPreProcessingStep.Process function:

Lines 22. to 25. contain a simple null-or-empty check for the $contentItems array. This code insures that the shortest possible program path is used if the input of an array of Content Items is not what was expected.

With the basic null check in place, we move on to line 27. where we set up the array that will eventually be returned by this function.

Then on line 19. we move into the real meat of the function, here we begin looping around each Content item that was passed into the Process function. The first thing we do (on line 32.) is construct a new instance of the TextForUrlParser by passing the Content item into its constructor. Then on line 35. we instantiate a new variable ($text) and fill it with the text extracted from the Content item by calling the GetUrlText function of the TextForUrlParser.

With the text that we want to send to the SiLCC service extracted, we then move onto calling the service itself. On line 39. a new instance of the ServiceInterface class is instantiate and then on line 42. The InterfaceWithService function of the ServiceInterface class is called passing in the url of the SiLCC service, the text extracted from the Content item and the $configuration variable (giving access to the SwiftRiver Core Framework configuration) and storing the JSON returned from the SiLCC service in a new variable ($json).

Its worth noting that best practice defensive programming means that any call to code that you can not control (such as a remote web service in this case) should be wrapped in error handling programming constructs. In the above example, if an exception is throw while communicating with the SiLCC service, the exception is logged (code not shown in the above snippet) and the content item is skipped. 

Providing that no exceptions are throw, normal program flow continues and on line 49. a new instance of the ContentFromJSONParser class is instantiated by passing both the subject Content item and the JSON returned from the SiLCC service into its constructor. Then on line 52. the GetTaggedContent function of the ContentFromJSONParser class is called and the return value (the subject Content item with any tags extracted from the JSON applied to it) is stored in a new variable that is then (on line 55.) added to the return array ready to be passed back to the SwiftRiver Core. 

Finally on line 58. the array of tagged content is returned and this Turbine has done its job!