Mentioned here, delegates offer a way to perform additional actions on any Symphony page, such as adding another Stylesheet, or manipulating form data. This includes the front end as well. This section will give you a good overview of what delegates exist in Symphony, the syntax of calling them and how to go about getting your CS to subscribe to various Symphony delegates. We will be using example_campfire_service.zip as our example code.

Technically, delegates have a fairly low level use. You can read about them here on wikipedia, but in the context of Symphony they are not that tricky to understand.

When code functions it goes from A → B → C. Consider the following code:

 
    ## Step A
    $number = 5;
 
    ## Step B - Square the number
    $number = $number * $number;
 
    ## Step C - Display the number, 25
    print "The number is: $number";
 

What happens if you need to manipulate the number before it is displayed, but after its been squared all without hardcoding a new step? The key is delegation. You allow custom code to run between Step B and C.

 
    ## Step A
    $number = 5;
 
    ## Step B - Square the number
    $number = $number * $number;
 
    ## Step B2 - Delegation
    delegate('PreDisplay', array(&$number));
 
    ## Step C - Display the number, 25 (or is it?)
    print "The number is: $number";
 

Of course delegate(’PreDisplay’, array(&$number)); is just pseudo code, but it gives you an idea of what we’re talking about. There is a delegate called ‘PreDisplay’ and anything subscribed to this delegate will get provided with a pointer to the $number variable, allowing them to manipulate it. Lets say we have something subscribing to this delegate called ‘F’ that divides the number by 2, so now our code flow is A → B → F → C. There is an additional step that was never there before and we didnt need to modify the code. The $number value would be 12.5 instead of 25

Delegates act as a way to branch code and perform custom actions.

There are currently 66 delegates in Symphony’s code base. This number grows with each release as the community requests more. The most common, and arguably the more useful, are PreRender and PostRender. These 2 exist for every page in Symphony’s Admin and Frontend. But there are, of course, many more.

The basic form of a Delegate is as follows

 
	####
	# Delegate: DelegateName
	# Description: Short Description that describes the delegate
	$CampfireManager->notifyMembers('DelegateName', PAGE, array());
 

The first parameter, in the example above its DelegateName, is the name of the delegate in the context of the page. PAGE is the name of the page we are on. Typically this will be either the name of the Admin page, E.G. /blueprint/pages/, or /frontend/ for your website front-end. And lastly, the array() are context variables. For example, the form field values or the page handle.

There is no list of available Delegates just yet. You will need to think about where you want your code to execute, and look for a delegate either by opening each file manually, or performing a search for notifyMembers or similar. Once you have found the Delegate you’re after, it’s a matter of making a note of its name, the page you’re on and subscribing to it.

As we saw in the overview, there is a function called getSubscribedDelegates(). When a Campfire Service is enabled by the user, this function is queried and delegate information stored in the database for easy lookup. Lets look at the example code.

 
	function getSubscribedDelegates(){
	  return array(
  
	      array(
	        'page' => '/frontend/',
	        'delegate' => 'PostRender',
	        'callback' => '__actionFrontend',
	      ),
 
	      array(
	        'page' => '/publish/section/',
	        'delegate' => 'PreRender',
	        'callback' => '__actionPublishSection',
	      ),
 
	      array(
	        'page' => '/publish/section/edit/',
	        'delegate' => 'Edit',
	        'callback' => '__actionPublishSectionEdit',
	      )          
    
	  );
	}
 

As you can see, this subscribes to 3 delegates. The PostRender for the Front-end, PreRender of the Publish → Section page in the Admin area, and the Edit delegate of the Publish → Section → Edit page.

Important: Any time you modify the getSubscribedDelegates() function you need to ‘disable’ then ‘enable’ the CS via your Campfire page.

Each delegate subscription requires 3 things. The page name, delegate name and a callback function name. The first two are self-explanatory. They correspond to the delegate details we discussed earlier. But callback is a new one. This specifies the class method to call should this delegate be triggered. It MUST correspond to a local class method. You cannot specify the method of a different class. Lets take a look at our example code for a better idea.

 
	## Handles the frontend delegate
	function __actionFrontend($context){
	  print '<h2>Looks like you have rendered the front end</h2>';
	  $this->__displayContext($context);
	}
 
	## Accessed the publish section entry page
	function __actionPublishSection($context){
	  print '<h2>Looks like you are trying to access the "PreRender" delegate</h2>'; 
	  $this->__displayContext($context);
	}    
 
	## Entry edited or deleted via edit page
	function __actionPublishSectionEdit($context){
	  print '<h2>Looks like you have edited a Section entry</h2>';
	  $this->__displayContext($context);
	}
 

As you can see, each of these functions correspond to the callback functions we specified earlier. Your callback functions can only accept one variable, $context, as it is called dynamically by the CampfireManager.