What it is
MemberFilter extensions allow your application to create filter form elements to be used when bulk emailing members, and when configuring group promotion steps. MemberFilter extensions may be used elsewhere by the Suite in future releases. If your application has a filterable status that may be useful for identifying members (e.g. to promote or send emails to the member based upon), a MemberFilter extension may be beneficial. For example, Blog has a MemberFilter extension that will allow the administrator to promote the member or email the member based upon whether the member has created a blog or not.
How to use
When you create a MemberFilter extension, the extension template has 6 methods you will want to define.
/**
* Determine if the filter is available in a given area
*
* @param string $area Area to check
* @return bool
*/
public function availableIn( $area )
{
return in_array( $area, array( 'bulkmail', 'group_promotions' ) );
}
Some MemberFilter extensions may be appropriate to promote based upon but not send emails, or vice-versa. If your extension may only be appropriate in one area you can perform that check in the availableIn() method, or you can return a blanket boolean TRUE or FALSE.
/**
* Get Setting Field
*
* @param mixed $criteria Value returned from the save() method
* @return array Array of form elements
*/
public function getSettingField( $criteria )
{
return array();
}
The getSettingField() method accepts an array of existing setting values and is expected to return an array of form helper elements which will be added to the respective forms being generated.
/**
* Save the filter data
*
* @param array $post Form values
* @return mixed False, or an array of data to use later when filtering the members
* @throws \LogicException
*/
public function save( $post )
{
return FALSE;
}
The save() method accepts the form values (from the form elements returned by getSettingField()) and is expected to return either FALSE, or an array of data that will be saved, and then later used for filtering (and for the default form values if the form is later edited).
/**
* Get where clause to add to the member retrieval database query
*
* @param mixed $data The array returned from the save() method
* @return string|array|NULL Where clause
*/
public function getQueryWhereClause( $data )
{
return NULL;
}
When searching for members that match the filter options, the getQueryWhereClause() will be called and is expected to return either a NULL value (indicating that this filter was not used, which can be verified by checking the $data array), a string value to be used in the where clause, or an array where clause.
/**
* Callback for member retrieval database query
* Can be used to set joins
*
* @param mixed $data The array returned from the save() method
* @param \IPS\Db\Query $query The query
* @return void
*/
public function queryCallback( $data, &$query )
{
return NULL;
}
The queryCallback() method can be used, if necessary, to adjust the database query before it is ran. This may be necessary, for instance, to join other database tables onto the query.
/**
* Determine if a member matches specified filters
*
* @note This is only necessary if availableIn() includes group_promotions
* @param \IPS\Member $member Member object to check
* @param array $filters Previously defined filters
* @return bool
*/
public function matches( \IPS\Member $member, $filters )
{
return TRUE;
}
If your member filter extension supports group_promotions (through the availableIn() method as outlined above), then you should define the matches() method which will accept an \IPS\Member object and the filters that have been defined for the extension, and will check if the member matches the filters and return a boolean TRUE or FALSE to indicate as such.
Report Document