Template plugin: Update template to custom function definitions

plugins/template/YOUR_PLUGIN_NAME.php

@@ -21,15 +21,32 @@ if (!class_exists ('VmPlugin')) {
 	require(JPATH_VM_PLUGINS . DS . 'vmplugin.php');
 }
 
+// An example callback function to provide a custom function for shipping rules:
+function custom_test_function($args) {
+	return count($args);
+}
+
 /** Extension plugin for the "Shipping by Rules" shipping plugin for VirtueMart
  */
 class plgVmShipmentRulesYOUR_PLUGIN_NAME extends VmPlugin {
 	/**  Trigger to add variables to the cart values
 	  *  You can add new variables to the $cartvals array or modify existing ones. They will be directly 
 	  *  available in all rules.
-	  *  Please notice that this function might also be called for only a subset of products of the cart.
+	  *  This trigger will be first called right before any rule is evaluated. In that case, $products 
+	  *  will contain all products in the cart and $cart_prices will be an arrow containing the calculated
+	  *  prices of the order.
+	  *  Please notice that this function might also be called for only a subset of products of the cart
+	  *  when the plugin evaluates a scoping function like evaluate_for_categories(...).
+	  *  In that case, $cart_prices will be NULL and the $products array will hold only those products that 
+	  *  actually match the filter, and only those should be used to calculate your custom variables.
+	  *  So you can not in general rely on the cart_prices argument to hold the properly summed prices.
 	  */
 	function onVmShippingRulesGetCartValues(&$cartvals, $cart, $products, $method, $cart_prices) {
+		if ($cart_prices) {
+			// Called for the whole cart...
+		} else {
+			// Called when any of the scoping operators need the cart values for only a subset of products
+		}
 		$cartvals['template_example'] = 123456789;
 		
 	}
@@ -38,16 +55,23 @@ class plgVmShipmentRulesYOUR_PLUGIN_NAME extends VmPlugin {
 	 *   array ('functionname1' => 'function_to_be_called',
 	 *          'functionname2' => array($classobject, 'memberfunc')),
 	 *          ...);
-	 *  The functions referenced here are called with exactly one array argument, that holds 
+	 *  The callback functions referenced here are called with exactly one array argument that holds 
 	 *  all function arguments, i.e. the function signature should be
 	 *     function function_to_be_called($args) {....}
+	 *
+	 *  All arguments passed to the function will already be properly evaluated before the function is called.
 	 */
 	function onVmShippingRulesRegisterCustomFunctions() {
-		return array('customTestFunction' => array($this, 'custom_test_function'));
+		return array(
+			// An example of a custom function that calls a member of this plugin class:
+			'customTestFunctionMember' => array($this, 'custom_test_function_member'),
+			// An example of a custom function that calls an ordinary top-level php function:
+			'customTestFunction' => 'custom_test_function',
+		);
 	}
 	
-	function custom_test_function($args) {
-		return 'Test return value...';
+	function custom_test_function_member($args) {
+		return 'CustomTestFunction called with '.count($args).' arguments.';
 	}
 }
 

rules_shipping_base.php

@@ -276,7 +276,7 @@ class plgVmShipmentRules_Shipping_Base extends vmPSPlugin {
 			// Evaluate all rules and find the matching ones (including modifiers and definitions!)
 			$result = array("rule"=>Null, "rule_name"=>"", "modifiers_add"=>array(), "modifiers_multiply"=>array());
 			$cartvals = $this->getCartValues ($cart, $cart->products, $method, $cart_prices);
-			// Pass a callback function to matches to obtain the cartvals for a subset of the products
+			// Pass a callback function to the rules to obtain the cartvals for a subset of the products
 			$this_class = $this;
 			$cartvals_callback = function ($products) use ($this_class, $cart, $method, $cart_prices) {
 				return $this_class->getCartValues ($cart, $products, $method, NULL);