DOCUMENTATION

================================
SWIFTRIVER PLUGIN DOCUMENTATION
================================

There are several ways developers can extend the Swiftriver platform to suit their needs. These extensions (or plugins) fall into two categories: Impulse plugins pre-process information (before it reaches the web app), while Reactor plugins post-process data.

==========
OVERVIEW
==========

The application core is responsible for doing all the heavy lifting involved with the operation of the product. It is the place where content is collected, where sources are aggregated and where communication with all of the SwiftRiver Web Services is managed. This core has been designed to allow developers to easily incorporate local code or cloud services, allowing applications to be 'remixed' to suit specific workflows or tasks.

Each app offers two places for users to extend the processing of the SwiftRiver core. In short, you can add value to the content that is collected by SwiftRiver (Impulse Turbines) and you can act on user interactions with the core (Reactor Turbines).


============
TERMINOLOGY
============

First, a bit of terminology to avoid confusion.

	SwiftWebServices (SWS) - cloud services that are hooked via API
	
	Swift Apps - applications built using SWS APIs and the Swift Plugin Architecture 
	
	Impulse Turbine - plugins that process data before the Swift App receives it
	
	Reactor Turbine - plugins that process data after the Swift App receives it


=================================
PRE-PROCESSOR TURBINES (Impulse)
=================================

Impulse Turbines offer developers the opportunity to interact with the content and sources that are being brought into Swiftriver before they reach the web applications and ultimately Swift App users. 


		--------------------------------------------------
		I. The Do's and Don'ts of Writing Impulse Turbines
		--------------------------------------------------

	1.	Your Turbine MUST be declared in the Swiftriver\Core\PreProcessing namespace. 
		This is to say that the first line (after the opening PHP tag) of the file that 
		contains your Turbine class must read  "namespace Swiftriver\Core\PreProcessing;"

	2.	Your Turbine MUST fully implement the IPreProcessingStep interface.
		See below for examples of how to implement this interface.

	3.	The file containing your Impulse Turbine MUST be called [SOMETHING]PreProcessingStep.php.
		Where [SOMETHING] is replaced by the name of your Turbine. NOTE: Case is important and 
		PreProcessingStep should be written as it appears here.

	4.	The file containing your Turbine and any other files that are required by your Turbine, 
		should be placed in a folder directly under the core/Modules folder. The folder can be 
		called anything you like but you must located it directly under the core/Modules directory 
		of your Swiftriver install.


		--------------------------------------------------		
		II. Implementing the IPreProcessingStep Interface
		--------------------------------------------------
		
In a little while, we'll look at where these Turbines fit into the wider platform, but first, let's look at some code:

/* Begin Code */

	namespace Swiftriver\Core\PreProcessing;
	interface IPreProcessingStep {
    	/**
     	* Interface method that all PrePorcessing Steps must implement
     	* 
     	* @param \Swiftriver\Core\ObjectModel\Content[] $contentItems
     	* @param \Swiftriver\Core\Configuration\ConfigurationHandlers\CoreConfigurationHandler $configuration
     	* @param \Log $logger
     	* @return \Swiftriver\Core\ObjectModel\Content[]
     	*/

    	public function Process($contentItems, $configuration, $logger);

    	/**
     	* The short name for this pre processing step, should be no longer
     	* than 50 chars
     	*
     	* @return string
     	*/
    	public function Name();

    	/**
     	* The description of this step
     	*
     	* @return string
     	*/
    	public function Description();

    	/**
     	* This method returns an array of the required paramters that
     	* are necessary to run this step.
     	*
     	* @return \Swiftriver\Core\ObjectModel\ConfigurationElement[]
     	*/
    	public function ReturnRequiredParameters();
		}
		
/* End Code */		

So, what are we looking at? This is the interface that must be implemented by all Impulse Turbines. You may have noticed that it's called IPreProcessingStep, this is the internal name for an Impulse Turbine.

If you are unfamiliar with Classes, Namespaces or Interfaces in PHP programming, you should spend a few moments going through the latest PHP5.3 documentation as these concepts are used extensively throughout the Swiftriver platform.

So, back to the code: We have an Interface which lives in the 'Swiftriver\Core\PreProcessing' namespace. The interface describes four methods that must be implemented by any Impulse Turbine that you create. 

Lets look at each method in a bit more detail.

		public function Process($contentItems, $configuration, $logger);

This is where the magic happens in your turbine. This function is called by the core and an array of \Swiftriver\Core\ObjectModel\Content items are passed (along with variables giving you access to the configuration and logging systems). Whatever you plan to do in your turbine, your implementation of this method should also return an array of \Swiftriver\Core\ObjectModel\Content items.

		public function Name();

This function is where you give your turbine a name. All that is required in your implementation of this method is to return a string of less that 50 chars that can be used to identify your turbine.

		public function Description();

As with the Name function, here all you need to do is return a string that describes what it is that your turbine does.

		public function ReturnRequiredParameters();

Here you have the option to present configuration options that may be needed to run your turbine. 
This method should return an array of '\Swiftriver\Core\ObjectModel\ConfigurationElement' objects.

So, with this in mind, lets look at a (very) basic implementation of the IPreProcessingStep interface:

/* Begin Code */

01. namespace Swiftriver\PreProcessingSteps;
02. class ExamplePreProcessingStep implements \Swiftriver\Core\PreProcessing\IPreProcessingStep {
03. 
04.     public function Description() { 
05.         return "This is the description for this Example Turbine";
06.     }
07.
08.     public function Name() { 
09.         return "Example Impulse Turbine";
10.     }
11.
12.     public function ReturnRequiredParameters() { 
13.         return array();
14.     }
15.
16.     public function Process($contentItems, $configuration, $logger) {
17.         return $contentItems;
18.     }
19. }
	
/* End Code */	


Lets take a closer look at what is going on here...

	On line 01. we are declaring this class to be part of the Swiftriver\PreProcessingSteps namespace. 
	
	On line 02. we are naming this Turbine (in the programming sense of the word) and declaring that this Turbine will implement the IPreProcessingStep interface.
	
	Lines 04. to 06. contain an implementation of the Description function defined in the IPreProcessingStep 
	interface. In this basic implementation we are returning a string that describes this Turbine.

	Lines 08. to 10. contain an implementation of the Name function defined in the IPreProcessingStep interface. 
	In this basic implementation we are returning a string that is the name of this Turbine.

	Lines 12. to 14. contain an implementation of the ReturnRequiredParameters function defined in the 
	IPreProcessingStep interface. In this basic implementation we are simply returning an empty array.

	Lines 16. to 18. contain an implementation of the Process function defined in the IPreProcessingStep 
	interface. In this basic implementation we are just returning the array of contentItems that has been 
	passed into this function. Clearly this is not doing anything.

The above code sample will work within the SwiftRiver Impulse Turbines framework, but by just returning the array of ContentItems we are not really adding any value. Lets take a quick look at a very simple example of using the Process function to add value to the content that is passed in.

/* Begin Code */

   		public function Process($contentItems, $configuration, $logger) {

    		foreach($contentItems as $item) {
             	$item->tags[] = new Tag("Tagged by my first Impulse Turbine");
         		}

        	return $contentItems;
     			}

/* End Code */


So, clearly we are not adding much value to the content that is passed into the Process method but, we are doing something and this simple example gives you a good introduction it what is possible with the Impulse Turbine framework.

In the above example, on lines 03. to 05. we are looping through all the content items and adding a new Tag to each ones collection of tags. The net result of running a SwiftRiver instance with this kind of Impulse Turbine would be that each and every content item shown in the user interface would have a tag with the text "Tagged by my first Impulse Turbine".

Using this as a template, you can perform any kind of action you can think of on each content item. Inside this Process function, you have access to all the properties of the Swiftriver\ObjectModel\Content object.

Let's look at a real world example of how the IPreProcessingStep interface can be utilized.  See EXAMPLES document


=================================
POST-PROCESSOR TURBINES (Reactor)
=================================

* coming soon *