For many applications, the configuration files provide sufficient to make them fit the requirements.  However, in some cases you may feel the need to "extend" or "bend" your application even more.  For these situations, there are delegate classes.

What is a delegate class?

A delegate class is a PHP class that defines custom behavior, functions, and fields for a table in a Xataface application.  A table may have only 1 delegate class.

What kinds of things can a delegate class do?

• Define permission rules for tables, records, and relationships.
• Define calculated fields.
• Define custom serialization/deserialization of fields (useful for XML storage)
• Define custom event handlers (actions to be performed when certain events take place)
• Define import / export filters.
• Define custom titles for records
• more ...

How to create a delegate class

I will describe the creation process with an example. 

Referring back to our FacultyOfWidgetry application, let's add a delegate class for the 'Program' table.  This is done as follows:

1. Create a file named 'Program.php' in the Program table configuration directory (i.e., 'tables/Program/Program.php).  Your application directory structure should now look like:
   
2. Add the following contents to your newly created 'Program.php' file:
   

   <?php
   class tables_Program {}
   ?>
   

   In other words, you are creating a class named 'tables_Program'.  The above delegate class doesn't do anything yet, but it is a start.

The fun part doesn't start until you start defining methods in your delegate class.  There are prescribed interfaces that you will need to implement to make this work.

Example 1: Creating a custom title for records

The "Title" of a record is a string that represents the record.  It is used by Xataface in the navigation controller (forward and back buttons) and in the "Jump" menu as well as various places around the interface for referring to that record.  As an example, take a look at this partial screen shot of the 'details' tab in a Xataface application.

I have circled the parts of the interface that use a record's title in some way.  (1), (2), and (4) show the title of the current record and (3) shows the title of the next record in the found set.  You will notice that the title is just the value of the first field in the Program record.  In fact, the way that Xataface generates titles is by selecting the first VARCHAR or CHAR field in the table to be the Title for records of that table.  In the above example this seems like a good choice, but it may not always be what you want.

We can use our delegate class to customize the way that these titles are generated.  By defining a method named getTitle(), we can customize the way that titles are generated.   Let's add such a method to our delegate class as follows:

<?php
class tables_Program {

	function getTitle(&$record){
		return $record->val('ProgramName').' Program';
	}
}

?>

OK, you are probably wondering what this $record object is.  The $record object is a Dataface_Record object that represents a record of the 'Program' table (if you want to take a look at the source code for this class it can be found in the 'Dataface/Record.php' file).  This object allows you to access all of the information about the record so that you can generate a title for the record.  The 'val' method simply returns the value of a field in the record.

In the above example, we are telling Xataface that the title of all records of the 'Program' table is the value of the ProgramName field with the string 'Program' appended to it.  For example, if the ProgramName of a record was 'Foo', then its title woud be 'Foo Program'.

Lets take a look at our application now to see the changes that we have made.

Notice that the (1) now has 'Program' appended to the end of the title, but (2) and (3) do not.  This is because (2) and (3) are part of the result controller (for navigating through results in the table) and it needs to be able to load hundreds of record titles at a time, but the getTitle() method requires that the entire record be loaded into memory for it to work which would be unfeasible when we need the title of hundreds of records.  The result controller titles can also be customized, however, using the titleColumn() method, which simply returns the name of the column that should be used as the title.  It can also return MySQL clauses that are equivalent to a column name (e.g., CONCAT('FirstName', ' ', 'LastName') would be valid).

Okay, let's add a titleColumn() method to our delegate class so that we can customize the way our records are represented in the result controller:

<?php
class tables_Program {

	function getTitle(&$record){
		return $record->val('ProgramName').' Program';
	}
	
	function titleColumn(){
		return 'AdmissionDeadline';
	}
}

?>

All that the titleColumn method does is return the name of a column to be used as the title for records of the 'Program' table.  In this case, we making the 'AdmissionDeadline' field the title column which results in the result controller looking like this:

This was a simple example, but it is possible to do more with the titleColumn() method than just specify the name of a column.  Any valid MySQL calculation that can be placed in a SELECT list can be returned here.  For example, we can make use of the MySQL 'CONCAT' function to append the string 'Program' to the 'ProgramName' field and achieve the same results as our previous getTitle() method:

<?php
class tables_Program {

	function getTitle(&$record){
		return $record->val('ProgramName').' Program';
	}
	
	function titleColumn(){
		return "CONCAT(ProgramName, ' Program')";
	}
}

?>

And now we can see the changes in our application:

It may seem a little bit inconvenient to have to define 2 methods to effectively customize the title of a record.  Future versions may attempt to address this issue so that one or the other can be implemented, but for now, both methods must be implemented to effectively customize the title.  In addition, future versions will likely add the 'titleColumn' functionality to an INI file since it is more or less static.

Summary

In this section we learned how to add a delegate class to our tables to customize the behavior of our applications.  Delegate class become more important when you need very fine-grained customizations to your application, as you will see in later sections.  One important feature of delegate classes is the ability to add security permissions to tables and records to limit who can view, edit, and delete certain records.  This will be covered in the next section.