beforeAddRelatedRecord Delegate Class Method

Synopsis

The beforeAddRelatedRecord delegate class method can be implemented in any table’s delegate class. It will be executed before any related record is added to that table’s relationships. Since it will be fired for all relationships on the table, you will have to include logic to only execute if the relationship that you are targeting is being added to.

Method Signature

function beforeAddRelatedRecord( Dataface_RelatedRecord $record );

Parameters

$record - The Dataface_RelatedRecord object encapsulating the record that is being added to the relationship.

Returns

void - If all is well
Dataface_Error object if something went wrong.

It is quite common to return a permission denied error from this method after doing some checks. e.g.

function beforeAddRelatedRecord($record){
    if ( /* some checks here */ ){
        return Dataface_Error::permissionDenied('Sorry you don\'t have permission to do this.');
    }
}

Examples

Example 1: Permission Check

function beforeAddRelatedRecord($record){
    if ( $record->_relationshipName == 'program_roles' ){
        // check to make sure that we are allowed to add roles to this program
        $program = df_get_record('programs', array('program_id'=>'='.$record->val('program_id')));
        if ( !$program ){
            return Dataface_Error::permissionDenied("Program could not be found");
        }
        if ( !$program->checkPermission('add new related record', array(
                'relationship' => 'program_roles'
                )
             )
           ){
            return Dataface_Error::permissionDenied("You don't have permission to add roles to this program");
        }
    }
}

The above example requires a little bit of context to understand. This method is defined in the ‘users’ table. There is a relationship between the users table and the programs table called ‘program_roles’. It keeps track of the roles that users have with respect to programs. There is a mirror relationshp in the programs table that goes to the users table, also named program_roles. Both the users table and the programs table contain rel_program_roles__roles() methods to define who can and cannot add to this relationship. However these don’t discern on the content that is being added to the relationship, so it is still possible that an ineligible program could be added to the relationship via the users table (or vice versa).

So, in the users table we defined the beforeAddRelatedRecord above which checks the permissions of the programs table to see if that particular program can be added to this relationship by this user.