projects / civicrm-core.git / blame
| Commit | Line | Data |
|---|---|---|
| 6a488035 | 1 | +--------------------------------------------------------------------+ |
| 06b69b18 | 2 | | CiviCRM version 4.5 | |
| 6a488035 | 3 | +--------------------------------------------------------------------+ |
| 06b69b18 | 4 | | Copyright CiviCRM LLC (c) 2004-2014 | |
| 6a488035 TO |
5 | +--------------------------------------------------------------------+ |
| 6 | | This file is a part of CiviCRM. | | |
| 7 | | | | |
| 8 | | CiviCRM is free software; you can copy, modify, and distribute it | | |
| 9 | | under the terms of the GNU Affero General Public License | | |
| 10 | | Version 3, 19 November 2007 and the CiviCRM Licensing Exception. | | |
| 11 | | | | |
| 12 | | CiviCRM is distributed in the hope that it will be useful, but | | |
| 13 | | WITHOUT ANY WARRANTY; without even the implied warranty of | | |
| 14 | | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. | | |
| 15 | | See the GNU Affero General Public License for more details. | | |
| 16 | | | | |
| 17 | | You should have received a copy of the GNU Affero General Public | | |
| 18 | | License and the CiviCRM Licensing Exception along | | |
| 19 | | with this program; if not, contact CiviCRM LLC | | |
| 20 | | at info[AT]civicrm[DOT]org. If you have questions about the | | |
| 21 | | GNU Affero General Public License or the licensing of CiviCRM, | | |
| 22 | | see the CiviCRM license FAQ at http://civicrm.org/licensing | | |
| 23 | +--------------------------------------------------------------------+ | |
| 24 | ||
| 25 | This README file documents conventions used in Incremental Upgrade SQL statements. | |
| 26 | ||
| 27 | ==================== | |
| 28 | Specifying Domain ID | |
| 29 | ==================== | |
| 30 | SQL statements in CRM/Upgrade/Incremental/sql templates which include domain_id should use {$domainID} which is defined in CRM_Upgrade_Form::processLocales() | |
| 31 | and is therefore available to all incremental .tpl files. | |
| 32 | ||
| 33 | Correct usage: | |
| 34 | ---------------------------------------------------- | |
| 35 | INSERT INTO `civicrm_report_instance` | |
| 36 | ( `domain_id`, `title`, `report_id`, `description`, `permission`, `form_values`) | |
| 37 | VALUES | |
| 38 | ( {$domainID}, 'Mailing Detail Report', 'mailing/detail', 'Provides reporting on Intended and Successful Deliveries, Unsubscribes and Opt-outs, Replies and Forwards.', '', '{literal}a:30:{s:6:"fields";a:6:{s:9:"sort_name";s:1:"1";s:12:"mailing_name";s:1:"1";s:11:"delivery_id";s:1:"1";s:14:"unsubscribe_id";s:1:"1";s:9:"optout_id";s:1:"1";s:5:"email";s:1:"1";}s:12:"sort_name_op";s:3:"has";s:15:"sort_name_value";s:0:"";s:6:"id_min";s:0:"";s:6:"id_max";s:0:"";s:5:"id_op";s:3:"lte";s:8:"id_value";s:0:"";s:13:"mailing_id_op";s:2:"in";s:16:"mailing_id_value";a:0:{}s:18:"delivery_status_op";s:2:"eq";s:21:"delivery_status_value";s:0:"";s:18:"is_unsubscribed_op";s:2:"eq";s:21:"is_unsubscribed_value";s:0:"";s:12:"is_optout_op";s:2:"eq";s:15:"is_optout_value";s:0:"";s:13:"is_replied_op";s:2:"eq";s:16:"is_replied_value";s:0:"";s:15:"is_forwarded_op";s:2:"eq";s:18:"is_forwarded_value";s:0:"";s:6:"gid_op";s:2:"in";s:9:"gid_value";a:0:{}s:9:"order_bys";a:1:{i:1;a:2:{s:6:"column";s:9:"sort_name";s:5:"order";s:3:"ASC";}}s:11:"description";s:21:"Mailing Detail Report";s:13:"email_subject";s:0:"";s:8:"email_to";s:0:"";s:8:"email_cc";s:0:"";s:10:"permission";s:1:"0";s:9:"parent_id";s:0:"";s:6:"groups";s:0:"";s:9:"domain_id";i:1;}{/literal}'); | |
| 39 | ---------------------------------------------------- | |
| 40 | ||
| 41 | Previously, a SELECT INTO @domainID was used. This method is deprecated and should NOT be used: | |
| 42 | ||
| 43 | ---------------------------------------------------- | |
| 10824d34 | 44 | -- get domain id |
| 6a488035 TO |
45 | SELECT @domainID := min(id) FROM civicrm_domain; |
| 46 | ---------------------------------------------------- | |
| 47 | ||
| 48 | ||
| 49 | ========================== | |
| 50 | Translate or Localize Text | |
| 51 | ========================== | |
| 52 | Text which is visible to users needs to be translated or set to localizable (which encompasses translation). Localize is used for fields that support | |
| 53 | multiple language values in multi-language installs. Check the schema definition for a given field if you're not sure whether a string is localizable. | |
| 54 | ||
| 55 | For example, to check if civicrm_option_value.label is localizable look at the Label field in xml/schema/Core/OptionValue.xml | |
| 56 | <field> | |
| 57 | <name>label</name> | |
| 58 | <title>Option Label</title> | |
| 59 | <type>varchar</type> | |
| 60 | <required>true</required> | |
| 61 | <length>255</length> | |
| 62 | <localizable>true</localizable> | |
| 63 | <comment>Option string as displayed to users - e.g. the label in an HTML OPTION tag.</comment> | |
| 64 | <add>1.5</add> | |
| 65 | </field> | |
| 66 | ||
| 67 | Localizable is true so we need to do inserts using the {localize} tag around that column. Check the Option Value insert example in the next section. | |
| 68 | ||
| 69 | If a field is NOT localizable, but we just need to make sure it can be translated - use the {ts} tag with sql escape parameter as shown below. | |
| 70 | ||
| 71 | ---------------------------------------------------- | |
| 72 | INSERT INTO civicrm_navigation | |
| 73 | ( domain_id, url, label, name, permission, permission_operator, parent_id, is_active, has_separator, weight ) | |
| 10824d34 | 74 | VALUES |
| 6a488035 TO |
75 | ( {$domainID}, 'civicrm/admin&reset=1', '{ts escape="sql" skip="true"}Administration Console{/ts}', 'Administration Console', 'administer CiviCRM', '', @adminlastID, '1', NULL, 1 ); |
| 76 | ---------------------------------------------------- | |
| 77 | ||
| 78 | =========================== | |
| 79 | Inserting Option Value Rows | |
| 80 | =========================== | |
| 81 | When you insert an option value row during an upgrade, do NOT use hard-coded integers for the "value" and "weight" columns. Since in many cases additional | |
| 82 | option value rows can be defined by users, you can't determine the next available unique value by looking at a sample installation. Use SELECT max() into | |
| 83 | a variable and increment it. | |
| 84 | ||
| 85 | Here's an example which localizes the Label and grabs next available integer for value and weight columns | |
| 86 | ------------------------------------------------------------------------------ | |
| 87 | SELECT @caseCompId := id FROM `civicrm_component` where `name` like 'CiviCase'; | |
| 88 | ||
| 89 | SELECT @option_group_id_activity_type := max(id) from civicrm_option_group where name = 'activity_type'; | |
| 90 | SELECT @max_val := MAX(ROUND(op.value)) FROM civicrm_option_value op WHERE op.option_group_id = @option_group_id_activity_type; | |
| 91 | SELECT @max_wt := max(weight) from civicrm_option_value where option_group_id=@option_group_id_activity_type; | |
| 92 | ||
| 93 | INSERT INTO civicrm_option_value | |
| 94 | (option_group_id, {localize field='label'}label{/localize}, {localize field='description'}description{/localize}, value, name, weight, filter, component_id) | |
| 95 | VALUES | |
| 3d8c6ffe | 96 | (@option_group_id_activity_type, {localize}'{ts escape="sql"}Change Custom Data{/ts}'{/localize},{localize}''{/localize}, (SELECT @max_val := @max_val+1), 'Change Custom Data', (SELECT @max_wt := @max_wt+1), 0, @caseCompId); |
| 6a488035 TO |
97 | |
| 98 | ------------------------------------------------------------------------------ | |
| 3d8c6ffe | 99 | More details on the wiki: http://wiki.civicrm.org/confluence/display/CRMDOC/Internationalisation+for+Developers#InternationalisationforDevelopers-Localisedfieldsschemachanges |