Merge pull request #161 from monishdeb/CRM-20037

CRM-20037: document added feature for searchColumns hook

docs/hooks/hook_civicrm_searchColumns.md

@@ -98,4 +98,43 @@ column values and therefore appear to be sorting incorrectly.
                 // override the values that we are not using
                 $values[$id]['contribution_type'] = $values[$id]['total'];
             }
-        }
\ No newline at end of file
+        }
+
+### **Example to add new column header at desired place**
+
+    function civitest_civicrm_searchColumns( $objectName, &$headers,  &$values, &$selector ) {
+
+      if ($objectName == 'contribution') {
+
+        // if you want to place your new column say 'Balance Due' after 'Total Amount'
+        foreach ($columnHeaders as $index => $column) {
+
+          // search for the machine name of 'Total Amount' column
+          if (!empty($column['field_name']) && $column['field_name'] == 'total_amount') {
+
+            // if you want to insert after 'total_amount' header then
+            //  increase the weight by N (here 4)
+            $weight = $column['weight'] + 4;
+            $columnHeaders[] = array(
+              'name' => ts('Balance Due'),
+              'field_name' => 'balance_due',
+              'weight' => $weight,
+              );
+
+              // set the values for 'Balance Due' column
+              foreach ($values as $key => $value) {
+                $balanceDue = CRM_Core_BAO_FinancialTrxn::getPartialPaymentWithType(
+                  $value['contribution_id'],
+                  'contribution',
+                  FALSE,
+                  $value['total_amount']
+                );
+                $values[$key]['balance_due'] = sprintf("<b>%s</b>", CRM_Utils_Money::format($balanceDue));
+              }
+              break;
+            }
+
+          } // end of foreach
+        }
+
+      }