@INSTANCETABLE_FILTER

InstanceTable.php

@@ -39,6 +39,7 @@ class InstanceTable extends AbstractExternalModule
         const ACTION_TAG_REF = '@INSTANCETABLE_REF';
         const ACTION_TAG_SRC = '@INSTANCETABLE_SRC'; // deprecated
         const ACTION_TAG_DST = '@INSTANCETABLE_DST'; // deprecated
+        const ACTION_TAG_FILTER = '@INSTANCETABLE_FILTER';
         const ADD_NEW_BTN_YSHIFT = '0px';
         const MODULE_VARNAME = 'MCRI_InstanceTable';
         const ACTION_TAG_DESC = 'Use with descriptive text fields to display a table of data from instances of a repeating form, or forms in a repeating event, with (for users with edit permissions) links to add/edit instances in a popup window.<br>* @INSTANCETABLE=my_form_name<br>* @INSTANCETABLE=event_name:my_form_name<br>There are some additional tags that may be used to further tweak the table behaviour. Take a look at the documentation via the External Modulers page for more information.';
@@ -205,6 +206,18 @@ protected function setTaggedFields() {
                                         $repeatingFormDetails['page_size'] = 0;
                                 }
 
+                                // pick up option for additional filter expression
+                                $matches = array();
+                                $outerQuote = array('"',"'"); // work for both @INSTANCETABLE_FILTER='[v]="1"' and @INSTANCETABLE_FILTER="[v]='1'" quote patterns 
+                                foreach ($outerQuote as $quoteChar) {
+                                        if (preg_match("/".self::ACTION_TAG_FILTER."\s*=\s*$quoteChar(.+)$quoteChar/", $fieldDetails['field_annotation'], $matches)) {
+                                                $addnlFilter = trim($matches[1]);
+                                                $filter = (empty(trim($filter))) 
+                                                    ? $addnlFilter
+                                                    : "($filter) and ($addnlFilter)";
+                                        }
+                                }
+
                                 // make column list for table: all form vars or supplied list, remove any with @INSTANCETABLE_HIDE
                                 $repeatingFormFields = REDCap::getDataDictionary('array', false, null, $formName);
                                 $includeVars = $requestedVars = $matches = array();
@@ -339,7 +352,7 @@ protected function makeHtmlTable($repeatingFormDetails, $canEdit) {
 
                 $html.='</tr></thead>';
 
-                // if survey form get data now (as have no auth for an ajax call)
+                // if survey form get data on page load (as no add/edit and have no auth for an ajax call)
                 if ($this->isSurvey) {
                         $filter =  "[$linkField]='$linkValue'";
                         $instanceData = $this->getInstanceData($this->record, $eventId, $formName, $varList, $filter, false);

README.md

@@ -19,6 +19,7 @@ If project is longitudinal, use `@INSTANCETABLE=event_name:form_name` to specify
 * `@INSTANCETABLE_HIDEINSTANCECOL`: Hide the "#" column containing instance numbers.
 * `@INSTANCETABLE_VARLIST=rptfrmvar1,rptfrmvar2,rptfrm_complete`: Include only the variables from the repeating form that appear in the comma-separated list. (An alternative to using `@INSTANCETABLE_HIDE` for repeating form variables. `@INSTANCETABLE_HIDE` takes precedence where both used.)
 * `@INSTANCETABLE_REF=fieldname`: Where you have an instance table on a repeating form - i.e. is referencing another repeating form - you can have the instances filtered to show only those where the current instance number is saved in a field on the other form.<br>For example, an instance table in a repeating "Visit" form may be configured to show only instances of the repeating "Medication" form where the current Visit instance is selected in the `visitref` field on the Medication form: `@INSTANCETABLE @INSTANCETABLE_REF=visitref`.<br>Note that if you use `@INSTANCETABLE_REF` for an instance table on a non-repeating form the filter will default to `<ref field>=1`.<br>New instances created by clicking the "Add New" button below the instance table will have the current visit instance pre-selected.
+*  `@INSTANCETABLE_FILTER='[v]="1"'`: Specify a logic expression to show only instances that match the filter expression. 
 
 ### Tags Used for Fields on a Repeating Form 
 * `@INSTANCETABLE_HIDE`: Ignore this field in instance all tables.