Actions, described in the preceeding section, will often print or return some content. For this content to get placed into a properly-formatted HTML, XHTML, XML, etc document, it first needs to pass through an OutputHandler. When an action executes, Harmoni will capture the results and pass them off to its current OutputHandler. The OutputHandler will take the results from the action and usually place them in the <body> element of an XHTML document.
An abstract class, OutputHandler (located in harmoni/core/architechure/output/) provides several methods for controlling output from Harmoni. All OutputHandlers must extend OutputHandler.
The primary method that must be overridden by all decendent classes is OutputHandler::output($returnedContent, $printedContent). $returnedContent is the return-value from an action and may be of arbitrary type depending on the OutputHandler in use. $printedContent includes any content that was printed to the output buffer during action execution and is always a string.
When dealing with HTML/XHTML documents, most of the content gets placed in the <body> element of the document. You may wish to put other content such as <title>, <script>, or <style> elements in the <head> element of a document. Use the OutputHandler's setHead() and getHead() methods to store content for readering inside of the <head> element.
Calling the attachToHarmoni() method on an output Handler will attach that OutputHandler to Harmoni as the current OutputHandler.
When passing configuration Properties to an OutputHandler, the following properties are usually used:
- document_type - string - The mime type to specify the output as. Default: 'text/html'
- character_set - string - The character set that the output is in. Default: 'utf-8'
- document_type_definition - string - The DTD that the output corresponds to. Default: '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">'
...
// Create our context object
require_once(OKI2."osid/OsidContext.php");
$osidContext =& new OsidContext;
$osidContext->assignContext('harmoni', $harmoni);
// Set up our configuration
require_once(HARMONI."/architecture/output/BasicOutputHandlerConfigProperties.class.php");
$configuration =& new BasicOutputHandlerConfigProperties;
$configuration->setProperty('character_set', 'ISO-8859-1');
// Create our OutputHandler and attach it to Harmoni
$outputHandler =& new BasicOutputHandler;
$outputHandler->assignOsidContext($osidContext);
$outputHandler->assignConfiguration($configuration);
$outputHandler->attachToHarmoni();
...
// Later on we may wish to set the title of a page:
$outputHandler =& $harmoni->getOutputHander();
$outputHandler->setHead($outputHandler->getHead()."\n\t\t<title>My Page Title</title>");
...
A BasicOutputHandler is set up when the HarmoniObject is instantiated, and will be used to output the content if no other OutputHandler is specified. The BasicOutputHandler will print any strings printed or returned from an action.
The GUI Manager service is a more advanced OutputHandler than the BasicOutputHandler. As described in the chapter dedicated to it, the GUI Manager allows for the laying-out of complex object trees of visual components. An action that uses the GUI Manager's compositing system will return its root component at the end of its execution. The Harmoni object passes this returned result to the GUI Manager which will then render it.