[Sommaire] [Imprimer]

   1  <?php
   2  //
   3  // Definition of eZTemplateLoop class
   4  //
   5  // Created on: <23-Feb-2005 17:46:42 vs>
   6  //
   7  // SOFTWARE NAME: eZ publish
   8  // SOFTWARE RELEASE: 3.9.0
   9  // BUILD VERSION: 17785
  10  // COPYRIGHT NOTICE: Copyright (C) 1999-2006 eZ systems AS
  11  // SOFTWARE LICENSE: GNU General Public License v2.0
  12  // NOTICE: >
  13  //   This program is free software; you can redistribute it and/or
  14  //   modify it under the terms of version 2.0  of the GNU General
  15  //   Public License as published by the Free Software Foundation.
  16  //
  17  //   This program is distributed in the hope that it will be useful,
  18  //   but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  //   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  //   GNU General Public License for more details.
  21  //
  22  //   You should have received a copy of version 2.0 of the GNU General
  23  //   Public License along with this program; if not, write to the Free
  24  //   Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  25  //   MA 02110-1301, USA.
  26  //
  27  //
  28  
  29  
  30  // private class, should not be used outside of this file
  31  class eZTemplateLoopSequence
  32  {
  33      function eZTemplateLoopSequence( &$array )
  34      {
  35          $this->ArrayRef =& $array;
  36          $this->CurVal   =  current( $this->ArrayRef );
  37      }
  38  
  39      function val()
  40      {
  41          return $this->CurVal;
  42      }
  43  
  44      function next()
  45      {
  46          if( ( $this->CurVal = next( $this->ArrayRef ) ) === false )
  47          {
  48              reset( $this->ArrayRef );
  49              $this->CurVal = current( $this->ArrayRef );
  50          }
  51      }
  52  
  53      var $ArrayRef;
  54      var $CurVal;
  55  }
  56  
  57  /*!
  58    \class eZTemplateLoop eztemplateloop.php
  59    \ingroup eZTemplateFunctions
  60    \brief Code common for the loop functions in processed mode.
  61  */
  62  class eZTemplateLoop
  63  {
  64      function eZTemplateLoop( $functionName, &$functionParameters, &$functionChildren, &$functionPlacement,
  65                               &$tpl, &$textElements, &$rootNamespace, &$currentNamespace )
  66      {
  67          $this->SkipDelimiter         = true;
  68          $this->SkipSequenceIncrement = false;
  69          $this->Delimiter             = null;
  70          $this->Initialized           = true;
  71          $this->SequenceVarName       = null;
  72          $this->Sequence              = null;
  73          $this->LoopVariablesNames    = array();
  74  
  75  
  76          $this->FunctionName       =  $functionName;
  77          $this->FunctionParameters =& $functionParameters;
  78          $this->FunctionChildren   =& $functionChildren;
  79  
  80          $this->Tpl                =& $tpl;
  81          $this->TextElements       =& $textElements;
  82          $this->RootNamespace      =& $rootNamespace;
  83          $this->CurrentNamespace   =& $currentNamespace;
  84          $this->FunctionPlacement  =& $functionPlacement;
  85  
  86          $this->Initialized = $this->processFunctionParameters();
  87      }
  88  
  89      /*!
  90      \return true on success, false otherwise.
  91      */
  92      function processFunctionParameters()
  93      {
  94          $params =& $this->FunctionParameters;
  95  
  96          if ( !isset( $params['sequence_array'] ) || !count( $params['sequence_array'] ) )
  97              return true;
  98  
  99          $this->parseParamVarName( 'sequence_var', $seqVarName );
 100  
 101          if ( !$seqVarName )
 102          {
 103              $this->Tpl->error( $this->FunctionName, "Empty sequence variable name." );
 104              return false;
 105          }
 106  
 107          $this->initLoopVariable( $seqVarName );
 108  
 109          $seqArray = $this->Tpl->elementValue( $params['sequence_array'],
 110                                                $this->RootNamespace, $this->CurrentNamespace, $this->FunctionPlacement );
 111  
 112          $this->Sequence        = new eZTemplateLoopSequence( $seqArray );
 113          $this->SequenceVarName = $seqVarName;
 114  
 115          return true;
 116      }
 117  
 118      /*!
 119       * \return true if the object has been correctly initialized, false otherwise
 120       */
 121      function initialized()
 122      {
 123          return $this->Initialized;
 124      }
 125  
 126      /*! Export current loop sequence value to the template variable
 127       *  specified in loop parameters.
 128       */
 129      function setSequenceVar()
 130      {
 131          if ( !$this->hasSequence() )
 132              return;
 133  
 134          $this->Tpl->setVariable( $this->SequenceVarName,  $this->Sequence->val(), $this->RootNamespace );
 135      }
 136  
 137      /*!
 138       * Should be called each time a new iteration is started.
 139       *  Resets some internal variables.
 140       */
 141      function resetIteration()
 142      {
 143          $this->SkipDelimiter         = false;
 144          $this->SkipSequenceIncrement = false;
 145      }
 146  
 147      /*!
 148       * Increment current sequence value.
 149       */
 150      function incrementSequence()
 151      {
 152          if ( $this->hasSequence() && !$this->SkipSequenceIncrement )
 153              $this->Sequence->next();
 154      }
 155  
 156      /*!
 157       * Returns true if sequence has been specified for the loop in its parameters.
 158       */
 159      function hasSequence()
 160      {
 161          return !is_null( $this->Sequence );
 162      }
 163  
 164  
 165      /*!
 166       * Destroys template variables defined by the loop.
 167       */
 168      function cleanup()
 169      {
 170          // destroy loop variable(s)
 171          foreach ( $this->LoopVariablesNames as $varName )
 172              $this->Tpl->unsetVariable( $varName, $this->RootNamespace );
 173      }
 174  
 175      /*
 176       * Processes loop children, i.e. all tags and text that is
 177       * between start and end tags of the loop.
 178       * Besides, does special handling of {break}, {skip}, {continue} and {delimiter} tags.
 179       *
 180       * \return true if the caller loop should break, false otherwise
 181       */
 182      function processChildren()
 183      {
 184          if ( !is_array( $this->FunctionChildren ) )
 185          {
 186              return false;
 187          }
 188          foreach ( array_keys( $this->FunctionChildren ) as $childKey )
 189          {
 190              $child =& $this->FunctionChildren[$childKey];
 191  
 192              if ( $child[0] == EZ_TEMPLATE_NODE_FUNCTION ) // check child type
 193              {
 194                  $childFunctionName  =& $child[2];
 195  
 196                  if ( $childFunctionName == 'break' )
 197                      return true;
 198                  elseif ( $childFunctionName == 'continue' )
 199                  {
 200                      $this->SkipSequenceIncrement = true;
 201                      break;
 202                  }
 203                  elseif ( $childFunctionName == 'skip' )
 204                  {
 205                      $this->SkipSequenceIncrement = true;
 206                      $this->SkipDelimiter = true;
 207                      break;
 208                  }
 209                  elseif ( $childFunctionName == 'delimiter' )
 210                  {
 211                      if ( is_null( $this->Delimiter ) )
 212                          $this->Delimiter =& $child;
 213                      continue;
 214                  }
 215              }
 216  
 217              $rslt = $this->Tpl->processNode( $child, $this->TextElements, $this->RootNamespace, $this->CurrentNamespace );
 218  
 219              // break/continue/skip might be found in a child function's (usually {if}) children
 220              if ( is_array( $rslt ) )
 221              {
 222                  if ( array_key_exists( 'breakFunctionFound', $rslt ) )
 223                      return true;
 224                  elseif ( array_key_exists( 'continueFunctionFound', $rslt ) )
 225                  {
 226                      $this->SkipSequenceIncrement = true;
 227                      break;
 228                  }
 229                  elseif ( array_key_exists( 'skipFunctionFound', $rslt ) )
 230                  {
 231                      $this->SkipSequenceIncrement = true;
 232                      $this->SkipDelimiter = true;
 233                      break;
 234                  }
 235              }
 236  
 237          } // foreach
 238  
 239          return false;
 240      }
 241  
 242      /*!
 243       * If \c $loopCondition is true, shows delimiter (if one has been specified).
 244       * \param $index is needed for processing delimiter parameters such as modulo.
 245       *        Is current iteration index.
 246       * \return true if the caller loop should break, false otherwise
 247       */
 248      function processDelimiter( $index = false )
 249      {
 250          if ( is_null( $this->Delimiter ) || $this->SkipDelimiter )
 251              return false;
 252  
 253          $delimiterChildren =& $this->Delimiter[1];
 254          $delimiterParameters =& $this->Delimiter[3]; // Get parameters
 255          $delimiterMatch = true;
 256          // Check for "modulo"
 257          if ( isset( $delimiterParameters["modulo"] ) and $index !== false )
 258          {
 259              $delimiterModulo = $delimiterParameters["modulo"];
 260              $modulo = $this->Tpl->elementValue( $delimiterModulo, $this->RootNamespace, $this->FunctionName, $this->FunctionPlacement );
 261              $modulo = trim( $modulo );
 262              if ( is_numeric( $modulo ) )
 263                  $delimiterMatch = ( $index % $modulo ) == 0;
 264          }
 265          if ( $delimiterMatch )
 266          {
 267              foreach ( array_keys( $delimiterChildren ) as $key )
 268                  $this->Tpl->processNode( $delimiterChildren[$key], $this->TextElements, $this->RootNamespace, $this->CurrentNamespace );
 269          }
 270  
 271          return false;
 272      }
 273  
 274      /*!
 275       * Parses the given function parameter that is supposed to contain a variable name.
 276       * Extracted variable name is stored to $dst.
 277       *
 278       * @param $paramName Parameter name.
 279       * @param $dst       Where to store parameter value.
 280       * @return           false if specified parameter is not found or it is wrong, otherwise true is returned.
 281       */
 282      function parseParamVarName( $paramName, &$dst )
 283      {
 284          $dst = null;
 285  
 286          if ( !isset( $this->FunctionParameters[$paramName] ) ||
 287               !count( $this->FunctionParameters[$paramName] ) )
 288              return false;
 289  
 290          list( $varNsName, $varNsType, $varName ) = $this->FunctionParameters[$paramName][0][1];
 291  
 292          if ( $varNsType != EZ_TEMPLATE_NAMESPACE_SCOPE_LOCAL || $varNsName )
 293          {
 294              $this->Tpl->error( $this->FunctionName,
 295                                 'Loop variables can be defined in root namespace only (e.g. $foo, but not $#foo or $:foo.)' );
 296              return false;
 297          }
 298  
 299          $dst = $varName;
 300          return true;
 301      }
 302  
 303      /*!
 304       * Parses given function parameter and makes sure that it is not a proxy object ({section} loop iterator).
 305       *
 306       * @param  $paramName      Parameter name.
 307       * @param  $dst            Where to store parameter value.
 308       * @param  $isProxyObject  boolean true is stored here if value of the parameter is a proxy object.
 309       * @return                 false if specified parameter is not found or it is wrong, otherwise true is returned.
 310       */
 311      function parseScalarParamValue( $paramName, &$dst, &$isProxyObject )
 312      {
 313          $dst = null;
 314  
 315          if ( !isset( $this->FunctionParameters[$paramName] ) || !count( $this->FunctionParameters[$paramName] ) )
 316              return false;
 317  
 318          // get parameter value
 319          $dst = $this->Tpl->elementValue( $this->FunctionParameters[$paramName], $this->RootNamespace,
 320                                           $this->CurrentNamespace, $this->FunctionPlacement, false, true );
 321  
 322          // check if a proxy object ({section} loop iterator) was involved in the parameter value
 323          if ( isset( $this->FunctionParameters[$paramName]['proxy-object-found'] ) )
 324          {
 325              $isProxyObject = true;
 326              unset( $this->FunctionParameters[$paramName]['proxy-object-found'] ); // just not to leave garbage
 327          }
 328          else
 329              $isProxyObject = false;
 330  
 331          return true;
 332      }
 333  
 334      /*!
 335       * Parses value the given function parameter and stores it to $dst.
 336       *
 337       * @param  $paramName      Parameter name.
 338       * @param  $dst            Where to store parameter value.
 339       * @return                 false if specified parameter is not found or it is wrong, otherwise true is returned.
 340       */
 341      function parseParamValue( $paramName, &$dst )
 342      {
 343          $dst = null;
 344  
 345          if ( !isset( $this->FunctionParameters[$paramName] ) || !count( $this->FunctionParameters[$paramName] ) )
 346              return false;
 347  
 348          $dst = $this->Tpl->elementValue( $this->FunctionParameters[$paramName], $this->RootNamespace,
 349                                           $this->CurrentNamespace, $this->FunctionPlacement );
 350          return true;
 351      }
 352  
 353      /*!
 354       * Checks if the given loop variable already exists. If it doesn't, store its name for later cleanup.
 355       * Otherwise shows a warning message.
 356       *
 357       * @see eZTemplateLoop::$loopVariablesNames
 358       */
 359      function initLoopVariable( $varName )
 360      {
 361          if ( $this->Tpl->hasVariable( $varName, $this->RootNamespace ) )
 362              $this->Tpl->warning( $this->FunctionName, "Variable '$varName' already exists." );
 363          else
 364              $this->LoopVariablesNames[] = $varName;
 365      }
 366  
 367      ///
 368      /// \privatesection
 369      ///
 370  
 371      var $FunctionName;
 372      var $FunctionParameters;
 373      var $FunctionChildren;
 374      var $FunctionPlacement;
 375  
 376      var $SkipDelimiter;
 377      var $SkipSequenceIncrement;
 378      var $delimiter;
 379  
 380      var $Tpl;
 381      var $TextElements;
 382      var $RootNamespace;
 383      var $CurrentNamespace;
 384  
 385      var $Initialized;
 386      var $Sequence;
 387      var $SequenceVarName;
 388      /*!
 389       * Before we create a new loop variable, we check if it already exists.
 390       * If it doesn't, we store its name in this array, so that we know
 391       * which variables to destroy after the loop execution finishes.
 392       */
 393      var $LoopVariablesNames;
 394  }
 395  
 396  ?>