[Sommaire] [Imprimer]

   1  <?php
   2  //
   3  // Definition of eZCollaborationItemHandler class
   4  //
   5  // Created on: <22-Jan-2003 16:24:33 amos>
   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  /*! \file ezcollaborationitemhandler.php
  30  */
  31  
  32  /*!
  33    \class eZCollaborationItemHandler ezcollaborationitemhandler.php
  34    \brief The class eZCollaborationItemHandler does
  35  
  36  */
  37  
  38  include_once ( 'lib/ezutils/classes/ezini.php' );
  39  include_once ( "lib/ezfile/classes/ezdir.php" );
  40  
  41  /*
  42   Definitions for notification handling for collaboration handlers.
  43  */
  44  define( 'EZ_COLLABORATION_NOTIFICATION_COLLECTION_ONE_FOR_ALL', 1 );
  45  define( 'EZ_COLLABORATION_NOTIFICATION_COLLECTION_PER_USER', 2 );
  46  define( 'EZ_COLLABORATION_NOTIFICATION_COLLECTION_PER_PARTICIPATION_ROLE', 3 );
  47  
  48  class eZCollaborationItemHandler
  49  {
  50      /*!
  51       Initializes the handler with identifier and name.
  52       Optional parameters can be placed in \a $parameters.
  53      */
  54      function eZCollaborationItemHandler( $typeIdentifier, $typeName, $parameters = array() )
  55      {
  56          $parameters = array_merge( array( 'use-messages' => false,
  57                                            'type-class-list' => array(),
  58                                            'notification-collection-handling' => EZ_COLLABORATION_NOTIFICATION_COLLECTION_ONE_FOR_ALL,
  59                                            'notification-types' => false ),
  60                                     $parameters );
  61          $typeClassList = $parameters['type-class-list'];
  62          $this->Info['type-identifier'] = $typeIdentifier;
  63          $this->Info['type-class-list'] = $typeClassList;
  64          $this->Info['type-name'] = $typeName;
  65          $this->Info['use-messages'] = $parameters['use-messages'];
  66          $this->Info['notification-collection-handling'] = $parameters['notification-collection-handling'];
  67          $this->Info['notification-types'] = $parameters['notification-types'];
  68          $this->NotificationCollectionHandling = $parameters['notification-collection-handling'];
  69          $this->NotificationTypes = $parameters['notification-types'];
  70      }
  71  
  72      function attributes()
  73      {
  74          return array( 'info',
  75                        'notification_types' );
  76      }
  77  
  78      /*!
  79       \return true if the attribute \a $attribute exists.
  80      */
  81      function hasAttribute( $attr )
  82      {
  83          return in_array( $attr, $this->attributes() );
  84      }
  85  
  86      /*!
  87       \return the attribute \a $attribute if it exists or \c null.
  88      */
  89      function &attribute( $attribute )
  90      {
  91          if ( $attribute == 'info' )
  92              return $this->Info;
  93          else if ( $attribute == 'notification_types' )
  94              return $this->notificationTypes();
  95          else
  96          {
  97              eZDebug::writeError( "Attribute '$attribute' does not exist", 'eZCollaborationItemHandler::attribute' );
  98              $retValue = null;
  99              return $retValue;
 100          }
 101      }
 102  
 103      /*!
 104        \return what kind of notification types this handler supports. Can either return an array or a boolean.
 105        If it returns \c true the handler supports notification but does not have subnotifications.
 106        If it returns \c false the handler does not support notificiation.
 107        If it returns an array the array contains a list associative arrays each containing a \c name and \c value entry.
 108      */
 109      function &notificationTypes()
 110      {
 111          return $this->NotificationTypes;
 112      }
 113  
 114      /*!
 115       \return how the handler wants collections to be made.
 116       \note The default is to create one collection for all participants.
 117      */
 118      function notificationCollectionHandling()
 119      {
 120          return $this->NotificationCollectionHandling;
 121      }
 122  
 123      /*!
 124      */
 125      function notificationParticipantTemplate( $participantRole )
 126      {
 127          return 'participant.tpl';
 128      }
 129  
 130      /*!
 131       \static
 132       Handles a notification event for collaboration items.
 133       \note The default implementation sends out a generic email.
 134       \note Transaction unsafe. If you call several transaction unsafe methods you must enclose
 135       the calls within a db transaction; thus within db->begin and db->commit.
 136      */
 137      function handleCollaborationEvent( &$event, &$item, &$parameters )
 138      {
 139          include_once ( 'kernel/classes/ezcollaborationitemparticipantlink.php' );
 140          $participantList =& eZCollaborationItemParticipantLink::fetchParticipantList( array( 'item_id' => $item->attribute( 'id' ),
 141                                                                                               'participant_type' => EZ_COLLABORATION_PARTICIPANT_TYPE_USER,
 142                                                                                               'as_object' => false ) );
 143  
 144          $userIDList = array();
 145          $participantMap = array();
 146          foreach ( $participantList as $participant )
 147          {
 148              $userIDList[] = $participant['participant_id'];
 149              $participantMap[$participant['participant_id']] = $participant;
 150          }
 151  
 152  //         $collaborationIdentifier = $event->attribute( 'collaboration_identifier' );
 153          $collaborationIdentifier = $event->attribute( 'data_text1' );
 154          $ruleList =& eZCollaborationNotificationRule::fetchItemTypeList( $collaborationIdentifier, $userIDList, false );
 155          $userIDList = array();
 156          foreach ( $ruleList as $rule )
 157          {
 158              $userIDList[] = $rule['user_id'];
 159          }
 160          $userList = array();
 161          if ( count( $userIDList ) > 0 )
 162          {
 163              $db =& eZDB::instance();
 164              $userIDListText = implode( "', '", $userIDList );
 165              $userIDListText = "'$userIDListText'";
 166              $userList = $db->arrayQuery( "SELECT contentobject_id, email FROM ezuser WHERE contentobject_id IN ( $userIDListText )" );
 167          }
 168          else
 169              return EZ_NOTIFICATIONEVENTHANDLER_EVENT_SKIPPED;
 170  
 171          $itemHandler =& $item->attribute( 'handler' );
 172          $collectionHandling = $itemHandler->notificationCollectionHandling();
 173  
 174          $db =& eZDB::instance();
 175          $db->begin();
 176          if ( $collectionHandling == EZ_COLLABORATION_NOTIFICATION_COLLECTION_ONE_FOR_ALL )
 177          {
 178              include_once ( 'kernel/classes/notification/eznotificationcollection.php' );
 179              include_once ( 'kernel/common/template.php' );
 180              $tpl =& templateInit();
 181              $tpl->resetVariables();
 182              $tpl->setVariable( 'collaboration_item', $item );
 183              $result = $tpl->fetch( 'design:notification/handler/ezcollaboration/view/plain.tpl' );
 184              $subject = $tpl->variable( 'subject' );
 185              if ( $tpl->hasVariable( 'message_id' ) )
 186                  $parameters['message_id'] = $tpl->variable( 'message_id' );
 187              if ( $tpl->hasVariable( 'references' ) )
 188                  $parameters['references'] = $tpl->variable( 'references' );
 189              if ( $tpl->hasVariable( 'reply_to' ) )
 190                  $parameters['reply_to'] = $tpl->variable( 'reply_to' );
 191              if ( $tpl->hasVariable( 'from' ) )
 192                  $parameters['from'] = $tpl->variable( 'from' );
 193  
 194              $collection = eZNotificationCollection::create( $event->attribute( 'id' ),
 195                                                              EZ_COLLABORATION_NOTIFICATION_HANDLER_ID,
 196                                                              EZ_COLLABORATION_NOTIFICATION_HANDLER_TRANSPORT );
 197  
 198              $collection->setAttribute( 'data_subject', $subject );
 199              $collection->setAttribute( 'data_text', $result );
 200              $collection->store();
 201  
 202              foreach( $userList as $subscriber )
 203              {
 204                  $collection->addItem( $subscriber['email'] );
 205              }
 206          }
 207          else if ( $collectionHandling == EZ_COLLABORATION_NOTIFICATION_COLLECTION_PER_PARTICIPATION_ROLE )
 208          {
 209              $userCollection = array();
 210              foreach( $userList as $subscriber )
 211              {
 212                  $contentObjectID = $subscriber['contentobject_id'];
 213                  $participant = $participantMap[$contentObjectID];
 214                  $participantRole = $participant['participant_role'];
 215                  $userItem = array( 'participant' => $participant,
 216                                     'email' => $subscriber['email'] );
 217                  if ( !isset( $userCollection[$participantRole] ) )
 218                      $userCollection[$participantRole] = array();
 219                  $userCollection[$participantRole][] = $userItem;
 220              }
 221  
 222              include_once ( 'kernel/common/template.php' );
 223              $tpl =& templateInit();
 224              $tpl->resetVariables();
 225              foreach( $userCollection as $participantRole => $collectionItems )
 226              {
 227                  $templateName = $itemHandler->notificationParticipantTemplate( $participantRole );
 228                  if ( !$templateName )
 229                      $templateName = eZCollaborationItemHandler::notificationParticipantTemplate( $participantRole );
 230  
 231                  $itemInfo = $itemHandler->attribute( 'info' );
 232                  $typeIdentifier = $itemInfo['type-identifier'];
 233                  include_once ( 'kernel/classes/notification/eznotificationcollection.php' );
 234                  $tpl->setVariable( 'collaboration_item', $item );
 235                  $tpl->setVariable( 'collaboration_participant_role', $participantRole );
 236                  $result = $tpl->fetch( 'design:notification/handler/ezcollaboration/view/' . $typeIdentifier . '/' . $templateName );
 237                  $subject = $tpl->variable( 'subject' );
 238                  if ( $tpl->hasVariable( 'message_id' ) )
 239                      $parameters['message_id'] = $tpl->variable( 'message_id' );
 240                  if ( $tpl->hasVariable( 'references' ) )
 241                      $parameters['references'] = $tpl->variable( 'references' );
 242                  if ( $tpl->hasVariable( 'reply_to' ) )
 243                      $parameters['reply_to'] = $tpl->variable( 'reply_to' );
 244                  if ( $tpl->hasVariable( 'from' ) )
 245                      $parameters['from'] = $tpl->variable( 'from' );
 246  
 247                  $collection = eZNotificationCollection::create( $event->attribute( 'id' ),
 248                                                                  EZ_COLLABORATION_NOTIFICATION_HANDLER_ID,
 249                                                                  EZ_COLLABORATION_NOTIFICATION_HANDLER_TRANSPORT );
 250  
 251                  $collection->setAttribute( 'data_subject', $subject );
 252                  $collection->setAttribute( 'data_text', $result );
 253                  $collection->store();
 254                  foreach ( $collectionItems as $collectionItem )
 255                  {
 256                      $collection->addItem( $collectionItem['email'] );
 257                  }
 258              }
 259          }
 260          else if ( $collectionHandling == EZ_COLLABORATION_NOTIFICATION_COLLECTION_PER_USER )
 261          {
 262          }
 263          else
 264          {
 265              eZDebug::writeError( "Unknown collaboration notification collection handling type '$collectionHandling', skipping notification",
 266                                   'eZCollaborationItemHandler::handleCollaborationEvent' );
 267          }
 268          $db->commit();
 269  
 270          return EZ_NOTIFICATIONEVENTHANDLER_EVENT_HANDLED;
 271      }
 272  
 273      /*!
 274       \return true if the attribute \a $attribute exists in the content data.
 275      */
 276      function hasContentAttribute( &$collaborationItem, $attribute )
 277      {
 278          $content =& $collaborationItem->content();
 279          if ( is_array( $content ) )
 280          {
 281              return array_key_exists( $attribute, $content );
 282          }
 283          return false;
 284      }
 285  
 286      /*!
 287       \return the attribute \a $attribute if it exists in the content data or \c null.
 288      */
 289      function &contentAttribute( &$collaborationItem, $attribute )
 290      {
 291          $content =& $collaborationItem->content();
 292          if ( is_array( $content ) )
 293          {
 294              if ( array_key_exists( $attribute, $content ) )
 295                  return $content[$attribute];
 296          }
 297          $content = null;
 298          return $content;
 299      }
 300  
 301      /*!
 302       \return a list of classes this handler supports.
 303      */
 304      function classes()
 305      {
 306          return $this->Info['type-class-list'];
 307      }
 308  
 309      /*!
 310       \return the template name for the viewmode \a $viewmode.
 311      */
 312      function template( $viewMode )
 313      {
 314          $templateName = $this->templateName();
 315          return "design:collaboration/handlers/view/$viewMode/$templateName";
 316      }
 317  
 318      /*!
 319       \return the name of the template file for this handler.
 320       Default is to append .tpl to the identifier.
 321      */
 322      function templateName()
 323      {
 324          return $this->Info['type-identifier'] . '.tpl';
 325      }
 326  
 327      /*!
 328       \return the title of the collaboration item.
 329      */
 330      function title( &$collaborationItem )
 331      {
 332          return $this->Info['type-name'];
 333      }
 334  
 335      /*!
 336       \return true if the collaboration item \a $collaborationItem supports messages.
 337       \note The handler can either determine this by passing \a $useMessages to the constructor
 338             or by reimplementing this function to do it per item.
 339      */
 340      function useMessages( &$collaborationItem )
 341      {
 342          return $this->Info['use-messages'];
 343      }
 344  
 345      /*!
 346       \return the number of messages for the collaboration item \a $collaborationItem.
 347       \note The default implementation returns 0, if you want real counts
 348             the handler must reimplement this function.
 349      */
 350      function messageCount( &$collaborationItem )
 351      {
 352          return 0;
 353      }
 354  
 355      /*!
 356       \return the number of unread messages for the collaboration item \a $collaborationItem.
 357       \note The default implementation returns 0, if you want real counts
 358             the handler must reimplement this function.
 359      */
 360      function unreadMessageCount( &$collaborationItem )
 361      {
 362          return 0;
 363      }
 364  
 365      /*!
 366       This is called whenever the item is considered to be read,
 367       it can be used by handlers to update when the item was last read.
 368       \note Default implementation does nothing.
 369      */
 370      function readItem( &$collaborationItem, $viewMode = false )
 371      {
 372      }
 373  
 374      /*!
 375       This is called whenever a collaboration item is to be removed.
 376       Reimplementing this function can be used to cleanup external tables
 377       or other resources.
 378      */
 379      function removeItem( &$collaborationItem )
 380      {
 381      }
 382  
 383      /*!
 384       \static
 385       \return the ini object which handles collaboration settings.
 386      */
 387      function &ini()
 388      {
 389          return eZINI::instance( 'collaboration.ini' );
 390      }
 391  
 392      /*!
 393       \return a textual representation of the participant type id \a $participantType
 394       \note It's up to the real handlers to implement this if they use custom participation types.
 395      */
 396      function participantTypeString( $participantType )
 397      {
 398          return null;
 399      }
 400  
 401      /*!
 402       \return a textual representation of the participant role id \a $participantRole
 403       \note It's up to the real handlers to implement this if they use custom participation roles.
 404      */
 405      function participantRoleString( $participantRole )
 406      {
 407          return null;
 408      }
 409  
 410      /*!
 411       \return a description of the role id \a $roleID in the current language.
 412       \note It's up to the real handlers to implement this if they use custom participation roles.
 413      */
 414      function roleName( $collaborationID, $roleID )
 415      {
 416          return null;
 417      }
 418  
 419      /*!
 420       \return the content of the collaborationitem.
 421       \note This is specific to the item type, some might return an array and others an object.
 422      */
 423      function content( &$collaborationItem )
 424      {
 425          return null;
 426      }
 427  
 428      /*!
 429       This function is called when a custom action is executed for a specific collaboration item.
 430       The module object is available in \a $module and the item in \a $collaborationItem.
 431       \note The default does nothing, the function must be reimplemented in real handlers.
 432       \sa isCustomAction
 433      */
 434      function handleCustomAction( &$module, &$collaborationItem )
 435      {
 436      }
 437  
 438      /*!
 439       \return true if the current custom action is \a $name.
 440      */
 441      function isCustomAction( $name )
 442      {
 443          $http =& eZHTTPTool::instance();
 444          $postVariable = 'CollaborationAction_' . $name;
 445          return $http->hasPostVariable( $postVariable );
 446      }
 447  
 448      /*!
 449       \return true if the custom input variable \a $name exists.
 450      */
 451      function hasCustomInput( $name )
 452      {
 453          $http =& eZHTTPTool::instance();
 454          $postVariable = 'Collaboration_' . $name;
 455          return $http->hasPostVariable( $postVariable );
 456      }
 457  
 458      /*!
 459       \return value of the custom input variable \a $name.
 460      */
 461      function customInput( $name )
 462      {
 463          $http =& eZHTTPTool::instance();
 464          $postVariable = 'Collaboration_' . $name;
 465          return $http->postVariable( $postVariable );
 466      }
 467  
 468      /*!
 469       \static
 470       \return an array with directories which acts as default collaboration repositories.
 471       \sa handlerRepositories
 472      */
 473      function defaultRepositories()
 474      {
 475          $collabINI =& eZCollaborationItemHandler::ini();
 476          return $collabINI->variable( 'HandlerSettings', 'Repositories' );
 477      }
 478  
 479      /*!
 480       \static
 481       \return an array with directories which acts as collaboration extension repositories.
 482       \sa handlerRepositories
 483      */
 484      function extensionRepositories()
 485      {
 486          $collabINI =& eZCollaborationItemHandler::ini();
 487          return $collabINI->variable( 'HandlerSettings', 'Extensions' );
 488      }
 489  
 490      /*!
 491       \static
 492       \return an array with directories which acts as collaboration repositories.
 493       \sa defaultRepositories, extensionRepositories
 494      */
 495      function handlerRepositories()
 496      {
 497          $extensions = eZCollaborationItemHandler::extensionRepositories();
 498          $repositories = eZCollaborationItemHandler::defaultRepositories();
 499          $extensionRoot = eZExtension::baseDirectory();
 500          foreach ( $extensions as $extension )
 501          {
 502              $handlerPath = eZDir::path( array( $extensionRoot, $extension, 'collaboration' ) );
 503              if ( file_exists( $handlerPath ) )
 504                  $repositories[] = $handlerPath;
 505          }
 506          return $repositories;
 507      }
 508  
 509      /*!
 510       \static
 511       \return an array with handler identifiers that are considered active.
 512      */
 513      function activeHandlers()
 514      {
 515          $collabINI =& eZCollaborationItemHandler::ini();
 516          return $collabINI->variable( 'HandlerSettings', 'Active' );
 517      }
 518  
 519      /*!
 520       \static
 521       \return a unique instance of the handler for the identifier \a $handler.
 522       If \a $repositories is left out it will use the handlerRepositories.
 523      */
 524      function &instantiate( $handler, $repositories = false )
 525      {
 526          $objectCache =& $GLOBALS["eZCollaborationHandlerObjectCache"];
 527          if ( !isset( $objectCache ) )
 528              $objectCache = array();
 529          if ( isset( $objectCache[$handler] ) )
 530              return $objectCache[$handler];
 531          if ( $repositories === false )
 532          {
 533              $repositories = eZCollaborationItemHandler::handlerRepositories();
 534          }
 535          $handlerInstance = null;
 536          $foundHandlerFile = false;
 537          $foundHandler = false;
 538          foreach ( $repositories as $repository )
 539          {
 540              $handlerFile = $handler . 'collaborationhandler.php';
 541              $handlerClass = $handler . 'collaborationhandler';
 542              $handlerPath = eZDir::path( array( $repository, $handler, $handlerFile ) );
 543              if ( file_exists( $handlerPath ) )
 544              {
 545                  $foundHandlerFile = true;
 546                  include_once( $handlerPath );
 547                  if ( class_exists( $handlerClass ) )
 548                  {
 549                      $foundHandler = true;
 550                      $handlerInstance = new $handlerClass();
 551                      $objectCache[$handler] =& $handlerInstance;
 552                      $handlerClasses = $handlerInstance->classes();
 553                      foreach ( $handlerClasses as $handlerClass )
 554                      {
 555                      }
 556                  }
 557              }
 558          }
 559          if ( !$foundHandlerFile )
 560              eZDebug::writeWarning( "Collaboration file '$handlerFile' could not be found in " . implode( ', ', $repositories ), 'eZCollaborationItemHandler::fetchList' );
 561          else if ( !$foundHandler )
 562              eZDebug::writeWarning( "Collaboration class '$handlerClass' does not exist", 'eZCollaborationItemHandler::fetchList' );
 563          return $handlerInstance;
 564      }
 565  
 566      /*!
 567       \static
 568       \return a list of collaboration handler objects.
 569       \sa instantiate, activeHandlers
 570      */
 571      function &fetchList()
 572      {
 573          $list =& $GLOBALS['eZCollaborationList'];
 574          if ( isset( $list ) )
 575              return $list;
 576          $list = array();
 577          $activeHandlers = eZCollaborationItemHandler::activeHandlers();
 578          $repositories = eZCollaborationItemHandler::handlerRepositories();
 579          foreach ( $activeHandlers as $handler )
 580          {
 581              $handlerInstance =& eZCollaborationItemHandler::instantiate( $handler, $repositories );
 582              if ( $handlerInstance !== null )
 583                  $list[] =& $handlerInstance;
 584          }
 585          return $list;
 586      }
 587  
 588      /// \privatesection
 589      var $Info;
 590  }
 591  
 592  ?>