beforeAddRelatedRecord 108 beforeAddRelatedRecord Delegate Class Method Return to [[Delegate class methods]] [[toc]] ==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== <code> function beforeAddRelatedRecord( Dataface_RelatedRecord $record ); </code> ==Parameters== * '''$record''' - The [http://dataface.weblite.ca/Dataface_RelatedRecord Dataface_RelatedRecord] object encapsulating the record that is being added to the relationship. ===Returns=== * void - If all is well * [http://dataface.weblite.ca/Dataface_Error 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. <code> function beforeAddRelatedRecord($record){ if ( /* some checks here */ ){ return Dataface_Error::permissionDenied('Sorry you don\'t have permission to do this.'); } } </code> ==Examples== ===Example 1: Permission Check=== <code> 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"); } } } </code> 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. ==See Also== * [http://dataface.weblite.ca/Dataface_RelatedRecord Dataface_RelatedRecord API Docs] * [[Delegate class methods]] * [http://xataface.com/documentation/tutorial/getting_started/relationships Introduction to Relationships] - from the Getting Started Tutorial * [[relationships.ini file]] reference beforeAddRelatedRecord, Delegate class methods, relationship triggers en