Jump to content

Developer Documentation

core/MemberFilter

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


×
×
  • Create New...