3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.7 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2015 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
10 | CiviCRM is free software; you can copy, modify, and distribute it |
11 | under the terms of the GNU Affero General Public License |
12 | Version 3, 19 November 2007 and the CiviCRM Licensing Exception. |
14 | CiviCRM is distributed in the hope that it will be useful, but |
15 | WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
17 | See the GNU Affero General Public License for more details. |
19 | You should have received a copy of the GNU Affero General Public |
20 | License and the CiviCRM Licensing Exception along |
21 | with this program; if not, contact CiviCRM LLC |
22 | at info[AT]civicrm[DOT]org. If you have questions about the |
23 | GNU Affero General Public License or the licensing of CiviCRM, |
24 | see the CiviCRM license FAQ at http://civicrm.org/licensing |
25 +--------------------------------------------------------------------+
30 use Civi\ActionSchedule\Event\MailingQueryEvent
;
31 use Civi\Token\Event\TokenRegisterEvent
;
32 use Civi\Token\Event\TokenValueEvent
;
33 use Symfony\Component\EventDispatcher\EventSubscriberInterface
;
36 * Class AbstractTokenSubscriber
39 * AbstractTokenSubscriber is a base class which may be extended to
40 * implement tokens in a somewhat more concise fashion.
42 * To implement a new token handler based on this:
43 * 1. Create a subclass.
44 * 2. Override the constructor and set values for $entity and $tokenNames.
45 * 3. Implement the evaluateToken() method.
46 * 4. Optionally, override others:
49 * + alterActionScheduleMailing()
50 * 5. Register the new class with the event-dispatcher.
52 * Note: There's no obligation to use this base class. You could implement
53 * your own class anew -- just subscribe the proper events.
55 abstract class AbstractTokenSubscriber
implements EventSubscriberInterface
{
57 public static function getSubscribedEvents() {
59 Events
::TOKEN_REGISTER
=> 'registerTokens',
60 Events
::TOKEN_EVALUATE
=> 'evaluateTokens',
61 \Civi\ActionSchedule\Events
::MAILING_QUERY
=> 'alterActionScheduleQuery',
67 * Ex: 'contact' or profile' or 'employer'
73 * Ex: array('viewUrl', 'editUrl').
79 * @param array $tokenNames
80 * Array(string $fieldName => string $label).
82 public function __construct($entity, $tokenNames = array()) {
83 $this->entity
= $entity;
84 $this->tokenNames
= $tokenNames;
88 * Determine whether this token-handler should be used with
89 * the given processor.
91 * To short-circuit token-processing in irrelevant contexts,
94 * @param \Civi\Token\TokenProcessor $processor
97 public function checkActive(\Civi\Token\TokenProcessor
$processor) {
102 * Register the declared tokens.
104 * @param TokenRegisterEvent $e
105 * The registration event. Add new tokens using register().
107 public function registerTokens(TokenRegisterEvent
$e) {
108 if (!$this->checkActive($e->getTokenProcessor())) {
111 foreach ($this->tokenNames
as $name => $label) {
113 'entity' => $this->entity
,
121 * Alter the query which prepopulates mailing data
122 * for scheduled reminders.
124 * This is method is not always appropriate, but if you're specifically
125 * focused on scheduled reminders, it can be convenient.
127 * @param MailingQueryEvent $e
128 * The pending query which may be modified. See discussion on
129 * MailingQueryEvent::$query.
131 public function alterActionScheduleQuery(MailingQueryEvent
$e) {
135 * Populate the token data.
137 * @param TokenValueEvent $e
138 * The event, which includes a list of rows and tokens.
140 public function evaluateTokens(TokenValueEvent
$e) {
141 if (!$this->checkActive($e->getTokenProcessor())) {
144 // TODO: check if any tokens for $entity are actually used; short-circuit.
145 $prefetch = $this->prefetch($e);
146 foreach ($e->getRows() as $row) {
147 foreach ($this->tokenNames
as $field => $label) {
148 $this->evaluateToken($row, $this->entity
, $field, $prefetch);
154 * To perform a bulk lookup before rendering tokens, override this
155 * function and return the prefetched data.
157 * @param \Civi\Token\Event\TokenValueEvent $e
161 public function prefetch(TokenValueEvent
$e) {
166 * Evaluate the content of a single token.
168 * @param TokenRow $row
169 * The record for which we want token values.
170 * @param string $entity
171 * The name of the token entity.
172 * @param string $field
173 * The name of the token field.
174 * @param mixed $prefetch
175 * Any data that was returned by the prefetch().
178 public abstract function evaluateToken(TokenRow
$row, $entity, $field, $prefetch = NULL);