5.5.2. Your first instruction

5.5.2. Your first instruction
Prev	5.5. New instructions	Next

This is the time to write your first OPT instruction. It will be very simple and do nothing interesting, but it will give you a clue, what is going on here. First, an instruction processor is a class that extends optInstruction class and overwrites some of its methods. In configure() we return an array with the information about the tags we want to register, and instructionNodeProcess() is called by the parent-level processor to process the node. Here we will write our code.

Example 5.4. Your first instruction

<?php
	class optFirst extends optInstruction // 1
	{
		public function configure()
		{
			return array( // 2
				// processor name
				0 => 'first',
				// instructions
				'first' => OPT_MASTER,
				'/first' => OPT_ENDER
			);
		} // end configure();
		
		public function instructionNodeProcess(ioptNode $node)
		{
			foreach($node as $block) // 3
			{
				switch($block -> getName()) // 4
				{
				case 'first':
					$this -> firstBegin($block-> getAttributes());
					$this -> defaultTreeProcess($block); // 5
					break;						
				case '/first':
					$this -> firstEnd();
					break;
				}			
			}		
		} // end process();
		
		private function firstBegin($attributes)
		{
			$this -> compiler -> out('Beginning tag<br/>', true); // 6
		} // end firstBegin();
		
		private function firstEnd()
		{
			$this -> compiler -> out('Ending tag<br/>', true);
		} // end firstEnd();
	}
?>

The description of the main parts:

An instruction processor has to extend optInstruction class, which has some very important methods and all the logic of the tree processing.
The array returned by this method is very simple. In the element 0, we specify the processor's name, and the rest of items (assotiative) register the blocks that must be recognized as "ours" and redirected to this processor. We also specify their types (for example "OPT_MASTER" for opening tag and "OPT_ENDER" for the enclosing one).
The compilation tree is very easy to parse. The interface has some similarities to Document Object Model, and moreover - it supports natively PHP 5 iterators. Using a node object with a foreach loop will give us the blocks assigned to it.
Depending on the block name (for example "first" and "/first") we decide, what to do now. It's good to write the block processing code in a separate method, because the class is much clearer then.
If the block may contain some subnodes, we have to call defaultTreeProcess()link> method and pass the current block as a parameter in order to process them. Don't forget about it. On the other hand, if you want to handle some unknown blocks, you should write your own tree processing method. We will show it later.
This method allows to send something to the compiler output. The second parameter is optional. If it is not specified, the first value is treated as a dynamic PHP code, otherwise (true) - as a static text.

In order to install this instruction, copy it to your plugins directory, set the path (do not forget to remove plugins.php and compile.php files) and try to parse the following template:

Example 5.5. Using the instruction

A text
{first}
A text
{/first}
A text

Here is a small guide through the optInstruction class (Where To Find The Things I Need):

$this -> tpl - an optClass object. Refer to it in order to read the configuration.
$this -> compiler - an optCompiler object.
$this -> tpl -> data - an assotiative array of OPT blocks.
$this -> data - OPT blocks (inside the generated PHP code)
$this -> tpl -> vars - an assotiative array of OPT variables.
$this -> vars - OPT variables (inside the generated PHP code)
$this -> compiler -> processors - an assotiative array of current tag processors.
$this -> compiler -> genericBuffer - a buffer for the instuctions that may want to share some data with the others. In order to use them, create an item inside it with the processor name as an index.

Prev	Up	Next
5.5.1. Compiler overview	Home	5.5.3. Parameter parsing