Merge branch 'filtervaluesurl' into 'master'

Allow to specify defaults for filters via URL params

See merge request !46

CHANGELOG.md

 # Version 1.12.0 (not yet released)
 
-
+* Add support for filter defaults to be set using the URL.
 
 # Version 1.11.0
 

CRM/Dataprocessor/Form/Output/AbstractUIOutputForm.php

@@ -162,7 +162,7 @@ abstract class CRM_Dataprocessor_Form_Output_AbstractUIOutputForm extends CRM_Co
         if ($filter->isExposed()) {
           $filterValues = $filter->processSubmittedValues($submittedValues);
           if (empty($filterValues)) {
-            $filterValues = $filter->getDefaultFilterValues();
+            $filterValues = self::getDefaultFilterValues($filter);
           }
           $filter->applyFilterFromSubmittedFilterParams($filterValues);
         }
@@ -170,6 +170,30 @@ abstract class CRM_Dataprocessor_Form_Output_AbstractUIOutputForm extends CRM_Co
     }
   }
 
+  /**
+   * Get the default filter values for a filter. If there is no default value we allow the value to be set by a URL parameter of the same name as the filter.
+   *
+   * @param \Civi\DataProcessor\FilterHandler\AbstractFilterHandler $filterHandler
+   *
+   * @return array
+   * @throws \CRM_Core_Exception
+   */
+  public static function getDefaultFilterValues(\Civi\DataProcessor\FilterHandler\AbstractFilterHandler $filterHandler) {
+    $filterValues = $filterHandler->getDefaultFilterValues();
+    if (empty($filterValues)) {
+      $type = ($filterHandler->getFieldSpecification()->type === 'Int') ? 'CommaSeparatedIntegers' : $filterHandler->getFieldSpecification()->type;
+
+      $valueFromURL = \CRM_Utils_Request::retrieveValue($filterHandler->getFieldSpecification()->alias, $type, NULL, FALSE, 'GET');
+      if ($valueFromURL) {
+        $filterValues = [
+          'op' => 'IN',
+          'value' => $valueFromURL,
+        ];
+      }
+    }
+    return $filterValues;
+  }
+
   /**
    * Build the criteria form
    */
@@ -181,7 +205,7 @@ abstract class CRM_Dataprocessor_Form_Output_AbstractUIOutputForm extends CRM_Co
         if (!$fieldSpec || !$filterHandler->isExposed()) {
           continue;
         }
-        $filterElements[$fieldSpec->alias]['filter'] = $filterHandler->addToFilterForm($this, $filterHandler->getDefaultFilterValues(), $this->getCriteriaElementSize());
+        $filterElements[$fieldSpec->alias]['filter'] = $filterHandler->addToFilterForm($this, self::getDefaultFilterValues($filterHandler), $this->getCriteriaElementSize());
         $filterElements[$fieldSpec->alias]['template'] = $filterHandler->getTemplateFileName();
       }
       $this->assign('filters', $filterElements);

Civi/DataProcessor/FilterHandler/AbstractFilterHandler.php

@@ -395,6 +395,10 @@ abstract class AbstractFilterHandler {
     }
     if (isset($submittedValues[$alias.'_value'])) {
       $return['value'] = $submittedValues[$alias . '_value'];
+      if (empty($return['value'])) {
+        // Don't save an empty default criteria to the database or we can't override (eg. via URL)
+        $return = [];
+      }
     }
     if (isset($submittedValues[$alias.'_relative'])) {
       $return['relative'] = $submittedValues[$alias . '_relative'];

docs/how_to_create_search.md

@@ -15,7 +15,7 @@
 - [Start using the search](#start-using-the-search)
 
 In this tutorial we are going to create a search action. We search all people who have an active relationship with a household.
-We will show the name, e-mailaddress of the person and we will show the name and address of the household. 
+We will show the name, e-mailaddress of the person and we will show the name and address of the household.
 
 We will also add an additional filter to the search so the user can search on gender and/or birth date.
 
@@ -25,7 +25,7 @@ Our search will look like as follows:
 
 ## Create the data processor
 
-Go to Administer --> Data Processor --> Add data processor. 
+Go to Administer --> Data Processor --> Add data processor.
 Give your data processor an title. You can also add a description, the description is only shown in the *manage data processors* screen.
 
 
@@ -35,7 +35,7 @@ Press *Next*.
 
 ## Add the data sources
 
-In the next step we will add the data sources. A data processor has at least one data source. 
+In the next step we will add the data sources. A data processor has at least one data source.
 A data source could be CiviCRM entity, such as Individual, Household, Activity, Relationship etc. Or it could be something else, e.g. a CSV file.
 
 ### Add a data source for the household member
@@ -54,13 +54,13 @@ This is how our data source should look like:
 ### Add a data source for the e-mail address of the household member
 
 Now it is time to add a data source to retrieve the e-mail address of the household member.
-Press *Add data source* 
+Press *Add data source*
 
 Select as type *E-mail* and give it a title such as *E-mail*.
-Leave the filter criteria to use the primary e-mail address. 
-At the join section we will link this E-mail data source the *Household Member* data source. 
+Leave the filter criteria to use the primary e-mail address.
+At the join section we will link this E-mail data source the *Household Member* data source.
 
-Select at the *Select fields to join on (not required)* as Join Type. And select 
+Select at the *Select fields to join on (not required)* as Join Type. And select
 *Email Contact* = *Household Member :: Contact ID* as join fields.
 
 Press *Save*.
@@ -75,9 +75,9 @@ A  join connects two data sources to each other. In the example above we link th
 with the field *Email Contact* -  which is a field on the CiviCRM E-mail entity which holds the contact id - and we link it the Contact ID
 of the *Household Member*.
 
-**What does 'Select fields to join on (not required)' mean?** 
+**What does 'Select fields to join on (not required)' mean?**
 
-This means that the data processor tries to link an e-mail address to the household member, but what if the household member 
+This means that the data processor tries to link an e-mail address to the household member, but what if the household member
 does not have an e-mail address? The not required means in this case the household member still appears in our data set but with an
 empty e-mail address.
 
@@ -88,8 +88,8 @@ the household data source.
 
 Press *Add data source*
 
-At type select *Relationship*. Give it the title *Relationship*. At Filter criteria select by relationship type *Household Member* and *Head of household* 
-and set is active to yes. This means we only want to show activity relationship with a household. 
+At type select *Relationship*. Give it the title *Relationship*. At Filter criteria select by relationship type *Household Member* and *Head of household*
+and set is active to yes. This means we only want to show activity relationship with a household.
 
 At the join configuration select *Select fields to join on* and set fields to *Contact A* = *Household member :: Contact ID*.
 
@@ -102,8 +102,8 @@ This is how the relationship data source should look like:
 
 **Why do we use 'Select fields to join on'?**
 
-This join type means that only records who are present in both data sources are retrieved. Meaning that as an Individual does 
-not have an active relationship it will not be present in the data processor. 
+This join type means that only records who are present in both data sources are retrieved. Meaning that as an Individual does
+not have an active relationship it will not be present in the data processor.
 
 ### Add the Household data source
 
@@ -129,7 +129,7 @@ Press *Add data source*
 
 Select as type *Address* and give the data source the title *Address*
 
-Select at the *Select fields to join on (not required)* as Join Type. And select 
+Select at the *Select fields to join on (not required)* as Join Type. And select
 *Contact ID* = *Household :: Contact ID* as join fields.
 
 Press *Save*
@@ -142,7 +142,7 @@ The address data source should look like:
 
 We want to add the following fields:
 
-* Contact ID of the household member; we need this field so that the user can select the contact to perform actions on it e.g. Send an e-mail or add to an group. 
+* Contact ID of the household member; we need this field so that the user can select the contact to perform actions on it e.g. Send an e-mail or add to an group.
 * Name of the household member
 * Household name
 * E-mail address of the household member
@@ -162,52 +162,52 @@ Press *Add Field* and select *Household :: Display name* and give it the title *
 
 Press *Add Field* and select *E-mail :: Email* and give it the tThe filters which thitle *E-mail address*.
 
-Press *Add Field* and select *Household Member :: Gender (Option)* and give it the title *Gender*. 
+Press *Add Field* and select *Household Member :: Gender (Option)* and give it the title *Gender*.
 
 > There are two fields for gender one with the addition '(option)' and one without. The first one shows the label of the option
 > the latter the value. E.g. in CiviCRM the value 1 for gender has the value of Female.
 
 Press *Add Field* and select *Household Member :: Birth Date* and give it the title *Birth Date*.
 
-Press *Add Field* and select *Address :: Street Address* and give it the title *Address*. 
+Press *Add Field* and select *Address :: Street Address* and give it the title *Address*.
 
 > Street address is the CiviCRM field which holds the full address, e.g. street name plus housenumber.
-    
+
 Press *Add Field* and select *Address :: Postal code* and give it the title *Postal code*.
 
 Press *Add Field* and select *Address :: City* and give it the title *City*.
 
-Now we are finished with defining which fields we want to present to the user. 
+Now we are finished with defining which fields we want to present to the user.
 
 ## Add the exposed filters
 
-In this step we add the exposed filters. A filter is something the user can use to refine the search the results. 
+In this step we add the exposed filters. A filter is something the user can use to refine the search the results.
 We will add a filter for Gender and for Birth Date. An exposed filter could be required which means that the user
-first needs to enter a value for the filter before performing the search. 
+first needs to enter a value for the filter before performing the search.
 
-Press *Add Filter* and select *Field FIlter* as filter type. Give the filter the title *Gender* and 
+Press *Add Filter* and select *Field Filter* as filter type. Give the filter the title *Gender* and
 select *Household Member :: Gender* as field. Press *Save*
 
 ![screenshot 8](images/howto_create_search_8.png)
 
-Press again *Add Filter* and select *Field Filter*  as filter type. Give the filter the title *Birth date* 
+Press again *Add Filter* and select *Field Filter*  as filter type. Give the filter the title *Birth date*
 and select *Household Member :: Birth Date* as Field. Press *Save*
 
 ![screenshot 9](images/howto_create_search_9.png)
 
-## Add the Contact Search Output.
+## Add the Contact Search Output
 
 Each data processor have one or more outputs. An output defines how the data processor is accessible. At the moment
 you can chose between Contact Search, Activity Search, API or CSV Export. In this example we will both use the Contact Search and the CSV Export.
-The latter will present a button on the search screen to download the search results as a CSV file. 
+The latter will present a button on the search screen to download the search results as a CSV file.
 
-### Add the contact search output
+### Add the Contact Search form output
 
 Press *Add output* and select *Contact Search*. At parent menu, select *Search*. This option defines where the user can
 go to the search. Optional you can define what permission a user needs to have.
 At *Contact ID field* select the field *Contact ID*.
 
-Optional write some instructions for your user. 
+Optional write some instructions for your user.
 
 Press *Save*
 
@@ -215,11 +215,19 @@ The configuration of the Search output looks like:
 
 ![screenshot 10](images/howto_create_search_10.png)
 
+#### Search using URL parameters
+
+Default values for some filters can be specified using URL params:
+- The parameter in the URL must match the name given to the filter (eg. Add a *Contact is in group* filter and name it `group_id`).
+- The format must be `group_id=X` or `group_id=X,Y`.
+- The data type must match that of the filter (eg. group_id is an integer so it will accept `2` or `2,3` but not `Friends`).
+- There must be no default value for the filter set in the data processor settings.
+
 ### Add the CSV Export output
 
 Press *Add output*  and select *CSV Export*. The CSV Export does not have any additional configuration options.
 
-If you don't want that the user can download the search result as a CSV file you omit this step.  
+If you don't want that the user can download the search result as a CSV file you omit this step.
 
 ## Start using the search
 
@@ -229,14 +237,14 @@ The search looks like:
 
 ![screenshot 11](images/howto_create_search_11.png)
 
-You see all the people who have an active relationship with an household. 
+You see all the people who have an active relationship with an household.
 
-You also see a button to download the results as CSV File. 
+You also see a button to download the results as CSV File.
 
-And if you select one or more contacts you can perform the same actions as you can with a normal contact search. 
+And if you select one or more contacts you can perform the same actions as you can with a normal contact search.
 
 > If you want to create your own actions you can use the [Search Action Designer](https://lab.civicrm.org/extensions/searchactiondesigner) extension.
-    
+
 To refine the search results press *Edit Search Criteria* and you will see the screen below:
 
 ![screenshot 12](images/howto_create_search_12.png)