CRM/Core/BAO/LabelFormat.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.6                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright (C) 2011 Marty Wright                                    |
   7  | Licensed to CiviCRM under the Academic Free License version 3.0.   |
   8  +--------------------------------------------------------------------+
   9  | This file is a part of CiviCRM.                                    |
  10  |                                                                    |
  11  | CiviCRM is free software; you can copy, modify, and distribute it  |
  12  | under the terms of the GNU Affero General Public License           |
  13  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  14  |                                                                    |
  15  | CiviCRM is distributed in the hope that it will be useful, but     |
  16  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  17  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  18  | See the GNU Affero General Public License for more details.        |
  19  |                                                                    |
  20  | You should have received a copy of the GNU Affero General Public   |
  21  | License and the CiviCRM Licensing Exception along                  |
  22  | with this program; if not, contact CiviCRM LLC                     |
  23  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  24  | GNU Affero General Public License or the licensing of CiviCRM,     |
  25  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  26  +--------------------------------------------------------------------+
  27 */
  28
  29 /**
  30  *
  31  * @package CRM
  32  * @copyright CiviCRM LLC (c) 2004-2014
  33  * $Id$
  34  *
  35  */
  36
  37 /**
  38  * This class contains functions for managing Label Formats
  39  */
  40 class CRM_Core_BAO_LabelFormat extends CRM_Core_DAO_OptionValue {
  41
  42   /**
  43    * Static holder for the Label Formats Option Group ID
  44    */
  45   private static $_gid = NULL;
  46
  47   /**
  48    * Label Format fields stored in the 'value' field of the Option Value table.
  49    */
  50   private static $optionValueFields = array(
  51     'paper-size' => array(
  52       // Paper size: names defined in option_value table (option_group = 'paper_size')
  53       'name' => 'paper-size',
  54       'type' => CRM_Utils_Type::T_STRING,
  55       'default' => 'letter',
  56     ),
  57     'orientation' => array(
  58       // Paper orientation: 'portrait' or 'landscape'
  59       'name' => 'orientation',
  60       'type' => CRM_Utils_Type::T_STRING,
  61       'default' => 'portrait',
  62     ),
  63     'font-name' => array(
  64       // Font name: 'courier', 'helvetica', 'times'
  65       'name' => 'font-name',
  66       'type' => CRM_Utils_Type::T_STRING,
  67       'default' => 'helvetica',
  68     ),
  69     'font-size' => array(
  70       // Font size: always in points
  71       'name' => 'font-size',
  72       'type' => CRM_Utils_Type::T_INT,
  73       'default' => 8,
  74     ),
  75     'font-style' => array(
  76       // Font style: 'B' bold, 'I' italic, 'BI' bold+italic
  77       'name' => 'font-style',
  78       'type' => CRM_Utils_Type::T_STRING,
  79       'default' => '',
  80     ),
  81     'NX' => array(
  82       // Number of labels horizontally
  83       'name' => 'NX',
  84       'type' => CRM_Utils_Type::T_INT,
  85       'default' => 3,
  86     ),
  87     'NY' => array(
  88       // Number of labels vertically
  89       'name' => 'NY',
  90       'type' => CRM_Utils_Type::T_INT,
  91       'default' => 10,
  92     ),
  93     'metric' => array(
  94       // Unit of measurement for all of the following fields
  95       'name' => 'metric',
  96       'type' => CRM_Utils_Type::T_STRING,
  97       'default' => 'mm',
  98     ),
  99     'lMargin' => array(
 100       // Left margin
 101       'name' => 'lMargin',
 102       'type' => CRM_Utils_Type::T_FLOAT,
 103       'metric' => TRUE,
 104       'default' => 4.7625,
 105     ),
 106     'tMargin' => array(
 107       // Right margin
 108       'name' => 'tMargin',
 109       'type' => CRM_Utils_Type::T_FLOAT,
 110       'metric' => TRUE,
 111       'default' => 12.7,
 112     ),
 113     'SpaceX' => array(
 114       // Horizontal space between two labels
 115       'name' => 'SpaceX',
 116       'type' => CRM_Utils_Type::T_FLOAT,
 117       'metric' => TRUE,
 118       'default' => 3.96875,
 119     ),
 120     'SpaceY' => array(
 121       // Vertical space between two labels
 122       'name' => 'SpaceY',
 123       'type' => CRM_Utils_Type::T_FLOAT,
 124       'metric' => TRUE,
 125       'default' => 0,
 126     ),
 127     'width' => array(
 128       // Width of label
 129       'name' => 'width',
 130       'type' => CRM_Utils_Type::T_FLOAT,
 131       'metric' => TRUE,
 132       'default' => 65.875,
 133     ),
 134     'height' => array(
 135       // Height of label
 136       'name' => 'height',
 137       'type' => CRM_Utils_Type::T_FLOAT,
 138       'metric' => TRUE,
 139       'default' => 25.4,
 140     ),
 141     'lPadding' => array(
 142       // Space between text and left edge of label
 143       'name' => 'lPadding',
 144       'type' => CRM_Utils_Type::T_FLOAT,
 145       'metric' => TRUE,
 146       'default' => 5.08,
 147     ),
 148     'tPadding' => array(
 149       // Space between text and top edge of label
 150       'name' => 'tPadding',
 151       'type' => CRM_Utils_Type::T_FLOAT,
 152       'metric' => TRUE,
 153       'default' => 5.08,
 154     ),
 155   );
 156
 157   /**
 158    * Get page orientations recognized by the DOMPDF package used to create PDF letters.
 159    *
 160    * @param void
 161    *
 162    * @return array
 163    *   array of page orientations
 164    * @static
 165    */
 166   public static function getPageOrientations() {
 167     return array(
 168       'portrait' => ts('Portrait'),
 169       'landscape' => ts('Landscape'),
 170     );
 171   }
 172
 173   /**
 174    * Get font names supported by the TCPDF package used to create PDF labels.
 175    *
 176    * @param string $name
 177    *   Group name.
 178    *
 179    * @return array
 180    *   array of font names
 181    * @static
 182    */
 183   public static function getFontNames($name = 'label_format') {
 184     $label = new CRM_Utils_PDF_Label(self::getDefaultValues($name));
 185     return $label->getFontNames();
 186   }
 187
 188   /**
 189    * Get font sizes supported by the TCPDF package used to create PDF labels.
 190    *
 191    * @param void
 192    *
 193    * @return array
 194    *   array of font sizes
 195    * @static
 196    */
 197   public static function getFontSizes() {
 198     $fontSizes = array();
 199     for ($i = 6; $i <= 60; $i++) {
 200       $fontSizes[$i] = ts('%1 pt', array(1 => $i));
 201     }
 202
 203     return $fontSizes;
 204   }
 205
 206   /**
 207    * Get measurement units recognized by the TCPDF package used to create PDF labels.
 208    *
 209    * @param void
 210    *
 211    * @return array
 212    *   array of measurement units
 213    * @static
 214    */
 215   public static function getUnits() {
 216     return array(
 217       'in' => ts('Inches'),
 218       'cm' => ts('Centimeters'),
 219       'mm' => ts('Millimeters'),
 220       'pt' => ts('Points'),
 221     );
 222   }
 223
 224   /**
 225    * Get text alignment recognized by the TCPDF package used to create PDF labels.
 226    *
 227    * @param void
 228    *
 229    * @return array
 230    *   array of alignments
 231    * @static
 232    */
 233   public static function getTextAlignments() {
 234     return array(
 235       'R' => ts('Right'),
 236       'L' => ts('Left'),
 237       'C' => ts('Center'),
 238     );
 239   }
 240
 241   /**
 242    * Get text alignment recognized by the TCPDF package used to create PDF labels.
 243    *
 244    * @param void
 245    *
 246    * @return array
 247    *   array of alignments
 248    * @static
 249    */
 250   public static function getFontStyles() {
 251     return array(
 252       '' => ts('Normal'),
 253       'B' => ts('Bold'),
 254       'I' => ts('Italic'),
 255     );
 256   }
 257
 258   /**
 259    * Get Option Group ID for Label Formats
 260    *
 261    * @param string $name
 262    *
 263    * @return int
 264    *   Group ID (null if Group ID doesn't exist)
 265    */
 266   private static function _getGid($name = 'label_format') {
 267     if (!isset(self::$_gid[$name]) || !self::$_gid[$name]) {
 268       self::$_gid[$name] = CRM_Core_DAO::getFieldValue('CRM_Core_DAO_OptionGroup', $name, 'id', 'name');
 269       if (!self::$_gid[$name]) {
 270         CRM_Core_Error::fatal(ts('Label Format Option Group not found in database.'));
 271       }
 272     }
 273     return self::$_gid[$name];
 274   }
 275
 276   /**
 277    * Add ordering fields to Label Format list
 278    *
 279    * @param array (reference) $list List of Label Formats
 280    * @param string $returnURL
 281    *   URL of page calling this function.
 282    *
 283    * @return array
 284    *   (reference)   List of Label Formats
 285    * @static
 286    */
 287   public static function addOrder(&$list, $returnURL) {
 288     $filter = "option_group_id = " . self::_getGid();
 289     CRM_Utils_Weight::addOrder($list, 'CRM_Core_DAO_OptionValue', 'id', $returnURL, $filter);
 290   }
 291
 292   /**
 293    * Retrieve list of Label Formats.
 294    *
 295    * @param bool $namesOnly
 296    *   Return simple list of names.
 297    * @param string $groupName
 298    *   Group name of the label format option group.
 299    *
 300    * @return array
 301    *   (reference)   label format list
 302    * @static
 303    */
 304   public static function &getList($namesOnly = FALSE, $groupName = 'label_format') {
 305     static $list = array();
 306     if (self::_getGid($groupName)) {
 307       // get saved label formats from Option Value table
 308       $dao = new CRM_Core_DAO_OptionValue();
 309       $dao->option_group_id = self::_getGid($groupName);
 310       $dao->is_active = 1;
 311       $dao->orderBy('weight');
 312       $dao->find();
 313       while ($dao->fetch()) {
 314         if ($namesOnly) {
 315           $list[$groupName][$dao->name] = $dao->label;
 316         }
 317         else {
 318           CRM_Core_DAO::storeValues($dao, $list[$groupName][$dao->id]);
 319         }
 320       }
 321     }
 322     return $list[$groupName];
 323   }
 324
 325   /**
 326    * Retrieve the default Label Format values
 327    *
 328    * @param string $groupName
 329    *   Label format group name.
 330    *
 331    * @return array
 332    *   Name/value pairs containing the default Label Format values.
 333    * @static
 334    */
 335   public static function &getDefaultValues($groupName = 'label_format') {
 336     $params = array('is_active' => 1, 'is_default' => 1);
 337     $defaults = array();
 338     if (!self::retrieve($params, $defaults, $groupName)) {
 339       foreach (self::$optionValueFields as $name => $field) {
 340         $defaults[$name] = $field['default'];
 341       }
 342       $filter = array('option_group_id' => self::_getGid($groupName));
 343       $defaults['weight'] = CRM_Utils_Weight::getDefaultWeight('CRM_Core_DAO_OptionValue', $filter);
 344     }
 345     return $defaults;
 346   }
 347
 348   /**
 349    * Get Label Format from the DB
 350    *
 351    * @param string $field
 352    *   Field name to search by.
 353    * @param int $val
 354    *   Field value to search for.
 355    *
 356    * @param string $groupName
 357    *
 358    * @return array
 359    *   (reference) associative array of name/value pairs
 360    */
 361   public static function &getLabelFormat($field, $val, $groupName = 'label_format') {
 362     $params = array('is_active' => 1, $field => $val);
 363     $labelFormat = array();
 364     if (self::retrieve($params, $labelFormat, $groupName)) {
 365       return $labelFormat;
 366     }
 367     else {
 368       return self::getDefaultValues($groupName);
 369     }
 370   }
 371
 372   /**
 373    * Get Label Format by Name
 374    *
 375    * @param int $name
 376    *   Label format name. Empty = get default label format.
 377    *
 378    * @return array
 379    *   (reference) associative array of name/value pairs
 380    */
 381   public static function &getByName($name) {
 382     return self::getLabelFormat('name', $name);
 383   }
 384
 385   /**
 386    * Get Label Format by ID
 387    *
 388    * @param int $id
 389    *   Label format id. 0 = get default label format.
 390    * @param string $groupName
 391    *   Group name.
 392    *
 393    * @return array
 394    *   (reference) associative array of name/value pairs
 395    */
 396   public static function &getById($id, $groupName = 'label_format') {
 397     return self::getLabelFormat('id', $id, $groupName);
 398   }
 399
 400   /**
 401    * Get Label Format field from associative array
 402    *
 403    * @param string $field
 404    *   Name of a label format field.
 405    * @param array (reference) $values associative array of name/value pairs containing
 406    *                                           label format field selections
 407    *
 408    * @param null $default
 409    *
 410    * @return value
 411    * @static
 412    */
 413   public static function getValue($field, &$values, $default = NULL) {
 414     if (array_key_exists($field, self::$optionValueFields)) {
 415       switch (self::$optionValueFields[$field]['type']) {
 416         case CRM_Utils_Type::T_INT:
 417           return (int)CRM_Utils_Array::value($field, $values, $default);
 418
 419         case CRM_Utils_Type::T_FLOAT:
 420           // Round float values to three decimal places and trim trailing zeros.
 421           // Add a leading zero to values less than 1.
 422           $f = sprintf('%05.3f', $values[$field]);
 423           $f = rtrim($f, '0');
 424           $f = rtrim($f, '.');
 425           return (float)(empty($f) ? '0' : $f);
 426       }
 427       return CRM_Utils_Array::value($field, $values, $default);
 428     }
 429     return $default;
 430   }
 431
 432   /**
 433    * Takes a bunch of params that are needed to match certain criteria and
 434    * retrieves the relevant objects. Typically the valid params are only
 435    * label id. It also stores all the retrieved values in the default array.
 436    *
 437    * @param array $params
 438    *   (reference ) an assoc array of name/value pairs.
 439    * @param array $values
 440    *   (reference ) an assoc array to hold the flattened values.
 441    *
 442    * @param string $groupName
 443    *
 444    * @return CRM_Core_DAO_OptionValue object
 445    * @static
 446    */
 447   public static function retrieve(&$params, &$values, $groupName = 'label_format') {
 448     $optionValue = new CRM_Core_DAO_OptionValue();
 449     $optionValue->copyValues($params);
 450     $optionValue->option_group_id = self::_getGid($groupName);
 451     if ($optionValue->find(TRUE)) {
 452       // Extract fields that have been serialized in the 'value' column of the Option Value table.
 453       $values = json_decode($optionValue->value, TRUE);
 454       // Add any new fields that don't yet exist in the saved values.
 455       foreach (self::$optionValueFields as $name => $field) {
 456         if (!isset($values[$name])) {
 457           $values[$name] = $field['default'];
 458           if ($field['metric']) {
 459             $values[$name] = CRM_Utils_PDF_Utils::convertMetric($field['default'],
 460               self::$optionValueFields['metric']['default'],
 461               $values['metric'], 3
 462             );
 463           }
 464         }
 465       }
 466       // Add fields from the OptionValue base class
 467       CRM_Core_DAO::storeValues($optionValue, $values);
 468       return $optionValue;
 469     }
 470     return NULL;
 471   }
 472
 473   /**
 474    * Return the name of the group for customized labels
 475    *
 476    * @param void
 477    *
 478    * @return void
 479    */
 480   public static function customGroupName() {
 481     return ts('Custom');
 482   }
 483
 484   /**
 485    * Save the Label Format in the DB
 486    *
 487    * @param array (reference) $values associative array of name/value pairs
 488    * @param int $id
 489    *   Id of the database record (null = new record).
 490    * @param string $groupName
 491    *   Group name of the label format.
 492    *
 493    * @return void
 494    */
 495   public function saveLabelFormat(&$values, $id = NULL, $groupName = 'label_format') {
 496     // get the Option Group ID for Label Formats (create one if it doesn't exist)
 497     $group_id = self::_getGid($groupName);
 498
 499     // clear other default if this is the new default label format
 500     if ($values['is_default']) {
 501       $query = "UPDATE civicrm_option_value SET is_default = 0 WHERE option_group_id = $group_id";
 502       CRM_Core_DAO::executeQuery($query, CRM_Core_DAO::$_nullArray);
 503     }
 504     if ($id) {
 505       // fetch existing record
 506       $this->id = $id;
 507       if ($this->find()) {
 508         $this->fetch();
 509       }
 510     }
 511     else {
 512       // new record
 513       $list = self::getList(TRUE,$groupName);
 514       $cnt = 1;
 515       while (array_key_exists("custom_$cnt", $list)) $cnt++;
 516       $values['name'] = "custom_$cnt";
 517       $values['grouping'] = self::customGroupName();
 518     }
 519     // copy the supplied form values to the corresponding Option Value fields in the base class
 520     foreach ($this->fields() as $name => $field) {
 521       $this->$name = trim(CRM_Utils_Array::value($name, $values, $this->$name));
 522       if (empty($this->$name)) {
 523         $this->$name = 'null';
 524       }
 525     }
 526     $this->id = $id;
 527     $this->option_group_id = $group_id;
 528     $this->is_active = 1;
 529
 530     // serialize label format fields into a single string to store in the 'value' column of the Option Value table
 531     $v = json_decode($this->value, TRUE);
 532     foreach (self::$optionValueFields as $name => $field) {
 533       if (!isset($v[$name])) {
 534         $v[$name] = NULL;
 535       }
 536       $v[$name] = self::getValue($name, $values, $v[$name]);
 537     }
 538     $this->value = json_encode($v);
 539
 540     // make sure serialized array will fit in the 'value' column
 541     $attribute = CRM_Core_DAO::getAttribute('CRM_Core_BAO_LabelFormat', 'value');
 542     if (strlen($this->value) > $attribute['maxlength']) {
 543       CRM_Core_Error::fatal(ts('Label Format does not fit in database.'));
 544     }
 545     $this->save();
 546
 547     // fix duplicate weights
 548     $filter = array('option_group_id' => self::_getGid());
 549     CRM_Utils_Weight::correctDuplicateWeights('CRM_Core_DAO_OptionValue', $filter);
 550   }
 551
 552   /**
 553    * Delete a Label Format
 554    *
 555    * @param int $id
 556    *   ID of the label format to be deleted.
 557    * @param string $groupName
 558    *   Group name.
 559    * @static
 560    */
 561   public static function del($id, $groupName) {
 562     if ($id) {
 563       $dao = new CRM_Core_DAO_OptionValue();
 564       $dao->id = $id;
 565       if ($dao->find(TRUE)) {
 566         if ($dao->option_group_id == self::_getGid($groupName)) {
 567           $filter = array('option_group_id' => self::_getGid($groupName));
 568           CRM_Utils_Weight::delWeight('CRM_Core_DAO_OptionValue', $id, $filter);
 569           $dao->delete();
 570           return;
 571         }
 572       }
 573     }
 574     CRM_Core_Error::fatal(ts('Invalid value passed to delete function.'));
 575   }
 576 }