This framework (and sample implementations) allows developers to define the fields and layout of a search form, define the queries used to return search results. As much as possible, the actions available from the built-in search forms (basic and advanced search) should be available from these "custom" searches. This includes creating Smart Groups, Mailing Labels, Add Contacts to Group..... etc.
Smart Groups created via custom search forms should be available for CiviMail Mailings - but this will requires two additional functions in the framwork to be defined by the developer.
We probably will not support the add/remove contacts from a "custom smart group", since that makes the query (and hence the custom code) more complex. Hence context=smog/amtg is not supported (or exposed). We might decide to expose this at a later date.
A default form template is provided - but the developer can over-ride this by providing a customized template if they want to "design" the form layout, add help text to the form, etc.
One or more sample implementations will be delivered in the codebase. Currently there is a very simple one in Contacts/Form/Search/Custom/Sample.php.
We need to create several more complex "examples" to exercise the code / determine if any changes are needed to the framework. We'll divide this work up as follows:
Input: Include Groups, Exclude Groups
Result: All contacts that are in Include Groups but not in Exclude Groups (this query can be stolen from civimail)
Input: Date Range
Result: All contacts who have contributed during that date range with their TOTAL contribution amount, along with the GRAND TOTAL amount contributed
"Filtered postal mailing list for individuals and households"
Result: Primary addresses for all contacts in the selected group, filtered so that Household rows are returned for any individuals in the selected Group who are part of a household (member of / head of), and Individual rows are returned for "unaffiliated" contacts. This means that if more than one Individual in the selected Group is in the same Household - only a single Household row is returned.