PHP Function Support, Extended Documentation and UTF8 Settings

README.md

@@ -1,97 +1,94 @@
-OW Simple Operator
+OW Simple Operator README
 =====================
 
-Template operators of eZ Publish are really powerfull ! 
+Template operators of eZ Publish are really powerful!
 
 But sometimes you want to create some simples template operators, which don't need power.
 
 In this case, you can use OWSimpleOperator. You will save time and you will have more readable and maintainable operators.
 
 This extension was made by [Open Wide](http://openwide.fr)
 
+# Install
+   ------------
 
-Step 1 : Install
--------
-Add the OWSimpleOperator extension to your project.
+For installation instructions please read the doc/INSTALL.md
 
-This extension will provide to you the "OWSimpleOperator" class.
-So you have to regenerate the extension autoloads.
 
+# Features
+   ------------
 
-Step 2 : Template Operators Class 
--------
-In your own extension, create a template operators class in the following path :
+The OWSimpleOperator provides also a lot of utility methods for your PHP code :
 
-    /extension/myextension/autoloads/mytemplateoperator.php
+* Call any PHP Function as a template operator
 
-It must extends the OWSimpleOperator :
+* String manipulation
 
-    class ExampleOperator extends OWSimpleOperator
-    {
-    }
+* eZ Object Attribute Manipulation
 
+* Object type Control
 
-Step 3 : Code your operator
--------
-Add the implementation of your operator.
-For example for a sum operator :
+* Output manipulation
 
-    class ExampleOperator extends OWSimpleOperator
-    {
-        /*!
-         * Return the sum of two numbers
-         */
-        public function example_sum( $number1, $number2 )
-        {
-            return ( $number1 + $number2 );
-        }
-    }
 
+# Constraints
+   ------------
 
-Step 4 : Register your operator
--------
-Register your operator in the eztemplateautoload.php file :
+If an operator argument is optional, you have to set the default value to null.
 
-    /extension/myextension/autoloads/eztemplateautoload.php
+If you want more than 10 arguments for your operator, you have to override the $max_operator_parameter attribute.
 
-The content of this file have to look like that :
+If you want to use a PHP Function as a template operator it must be enabled within owsimpleoperator.ini.append.php:[PHPFunctions] PermittedFunctionList[]
 
-    $eZTemplateOperatorArray = array(
-         array(
-            'script' => 'extension/owsimpleoperator/autoloads/exampleoperator.php',
-            'class' => 'ExampleOperator',
-            'operator_names' => array(
-                'example_sum' ,
-            )
-         )
-    );
-
 
-Step 5 : Use it in your template
--------
-You already can use it in your template.
+# Copyright
+   ------------
 
-Like that :
+OW Simple Operator is copyright 1999-2012 OPEN WIDE and 1999-2012 Brookins Consulting
 
-    {example_sum(1, 2)}
-
-Or like that :
+See: doc/COPYRIGHT.md for more information on the terms of the copyright and license
 
-    {1|example_sum(2)}
-
-
-Bonus
--------
-The OWSimpleOperator provides also a lot of utils methods for your PHP code :
 
-* String manipulation
-* eZ Object Attribute Manipulation
-* Object type Control
-* Output manipulation 
+# License
+   ------------
 
+OW Simple Operator is licensed under the GNU General Public License.
 
-Contraints
--------
-If an operator argument is optional, you have to set the default value to null.
+The complete license agreement is included in the doc/LICENSE file.
+
+OW Simple Operator is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+OW Simple Operator is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+The GNU GPL gives you the right to use, modify and redistribute
+OW Simple Operator under certain conditions. The GNU GPL license
+is distributed with the software, see the file doc/LICENSE.
+
+It is also available at http://www.gnu.org/licenses/gpl.txt
+
+You should have received a copy of the GNU General Public License
+along with OW Simple Operator in doc/LICENSE.  If not, see http://www.gnu.org/licenses/.
+
+Using OW Simple Operator under the terms of the GNU GPL is free (as in freedom).
+
+
+# Troubleshooting
+   ------------
+
+## Remember template results are cached
+
+Warning! Remember to use cache-block tags to ensure operator and function results are not cached incorrectly.
+
+Please read doc/INSTALL.md for more detailed information and example solutions.
+
+## Read the doc/INSTALL.md
+
+   Some problems are more common than others.
 
-If you want more than 10 arguments for your operator, you have to override the $max_operator_parameter attribute.
+   The most common ones are listed in the the doc/INSTALL.md

autoloads/eztemplateautoload.php

@@ -5,9 +5,13 @@
         'script' => 'extension/owsimpleoperator/autoloads/exampleoperator.php',
         'class' => 'ExampleOperator',
         'operator_names' => array(
-            'example_sum' ,
+            'example_sum'
+        ) ),
+     array(
+        'script' => 'extension/owsimpleoperator/autoloads/phpfunctionoperator.php',
+        'class' => 'PHPFunctionOperator',
+        'operator_names' => eZINI::instance('owsimpleoperator.ini')->variable( 'PHPFunctions', 'PermittedFunctionList' )
         )
-     )
 );
 
 ?>

autoloads/owsimpleoperator.php

@@ -174,6 +174,26 @@ protected function output_debug_method_result( $method_name, $arguments, $result
         }
         ezDebug::writeDebug( $this->output_method_name( $method_name, $arguments ) . $result );
     }
+    /*!
+     * Log a debug method result
+     */
+    protected function output_debug_function_result( $method_name, $arguments, $result )
+    {
+        if ( is_array( $arguments ) )
+        {
+            $length = count( $arguments );
+            while ( $length > 0 && $arguments[ $length-1 ] == null )
+            {
+                $length--;
+            }
+            $arguments = array_slice( $arguments, 0, $length );
+        }
+        if ( $result !== null )
+        {
+            $result = ' => ' . $this->output_var( $result );
+        }
+        ezDebug::writeDebug( $this->output_function_name( $method_name, $arguments ) . $result );
+    }
     /*!
      * Log a debug variable
      */
@@ -196,6 +216,21 @@ protected function output_method_name( $method_name, $arguments = null )
         }
         return get_class( $this ) . '->' . $method_name . '(' . implode( ', ', $arguments ) . ')';
     }
+    /*!
+     * Get a readable version of a method name 
+     */
+    protected function output_function_name( $method_name, $arguments = null )
+    {
+        if ( is_array( $arguments ) )
+        {
+            $arguments = array_map( array( $this, 'output_var' ), $arguments );
+        }
+        else
+        {
+            $arguments = array( );
+        }
+        return 'PHP Function: ' . $method_name . '(' . implode( ', ', $arguments ) . ')';
+    }
     /*!
      * Get a readable version of a variable value  
      */
@@ -271,6 +306,34 @@ public function modify( $tpl, $operator_name, $operator_parameters, $root_namesp
                 $this->output_debug_method_result( $operator_name, $method_arguments, $operator_value );
             }
         }
+        elseif ( function_exists( $operator_name ) )
+        {
+	    $method_arguments = array();
+
+            foreach( $named_parameters as $index => $parameter )
+            {
+	       if( isset( $parameter ) )
+               {
+                   $method_arguments[$index] = $parameter;
+               }
+            }
+
+            // If there are an operator value, we switch it with our parameter
+            if ( $operator_value !== null )
+            {
+                array_pop( $method_arguments );
+                array_unshift( $method_arguments, $operator_value );
+            }
+
+            // We call directly the operator method with all parameter
+            $method_call = $operator_name;
+            $operator_value = call_user_func_array( $method_call, $method_arguments );
+
+            if ( $this->automatic_debug_output )
+            {
+                $this->output_debug_function_result( $operator_name, $method_arguments, $operator_value );
+            }
+        }
         else
         {
             $this->output_error( 'modify', 'The method "' . $operator_name . '" doesn\'t exists.' );

autoloads/phpfunctionoperator.php

@@ -0,0 +1,6 @@
+<?php
+
+class PHPFunctionOperator extends OWSimpleOperator
+{
+
+}

doc/COPYRIGHT.md

@@ -0,0 +1,18 @@
+Copyright © 2011 - 2012, OPEN WIDE
+Copyright © 1999 - 2012, Brookins Consulting
+
+    This file is part of OW Simple Operator.
+
+    OW Simple Operator is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License.
+
+    OW Simple Operator is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with OW Simple Operator in doc/LICENSE.
+
+    If not, see <http://www.gnu.org/licenses/>.