Download CIVICRM DEVELOPER GUIDE

14. DEVELOPING CUSTOM SEARCHES
A custom search is a method of providing new functionality within the standard CiviCRM
navigation structure. T his chapter looks at how to develop a Custom Search.
Custom searches produce a screen showing a set of contacts, from where you can execute
actions such as sending email, printing mailing labels, and all the other actions that are available
for contact search results within CiviCRM. T he results page displays the same as any other
search results page, such as results delivered from an Advanced Search, however, a predefined
set of functions controls which information is delivered to the result page.
Custom Searches follow the Hollywood principle, "Don't call me, I'll call you." In this case
CiviCRM calls your functions at the appropriate time.
CustomSearches_AggregateT otals
CustomSearches_Results
WHEN TO USE CUSTOM SEARCHES
A custom search is the right choice when ...
you need to access the Actions list after running your search, to send email, add the
contacts to a group or other actions (since the list of actions and list of tokens can be
extended with developer-created hooks, the combination of a custom search + custom
action + custom token is a powerful tool for implementing a special requirement. If you
are interested in creating new actions or tokens, read the section on CiviCRM hooks in
the chapter Extending CiviCRM.)
you want to create a Smart Group based on the parameters of the custom search
you want to use the search results to drive a mass mailing in CiviMail
you want results that can be sorted by clicking any column heading in the results page.
A custom search is the wrong choice when ...
you can use the Advanced Search or the Search Builder to create the same results
the information you need is not primarily accessible from the CiviCRM database tables
(for example, the information needs to be retrieved from a third-party system or a
different database)
the information you need does not include the CiviCRM contact ID (for example,
information related to summarised event income).
CiviReport is a better choice if ...
you need to schedule and send the entire result as an email to one or more people
you need a summary/detail drill-down style of results page where the detail is not just
the contact summary screen
you want to use the results as a dashlet on your CiviCRM dashboard
you need multiple report break areas within the results page, such as subtotals after
every 5 records as well as grand totals
you need to include information not related to contacts.
GETTING STARTED CREATING A NEW CUSTOM SEARCH
In this section we will create a new custom search called "BirthdaySearch" that will find all
contacts whose birthdays fall in June.
Custom searches are written using PHP and SQL. Very little knowledge of PHP is needed, as
you start with a template file and only make minor changes. In many cases the only changes
are the SQL Select statement and which columns to display in the results.
Plan and test
Before writing the code, it is important to plan and test the SQL query and verify the results. It
is valuable at this stage to review the database tables and test the SQL select statements
within the database using an SQL tool such as PHPMyAdmin.
It may be helpful for you to review the information at:
35