[Summary view] [Print] [Text view]

   1  <!-- $Id: export.html,v 1.1.2.7 2010/07/22 22:41:44 merlinofchaos Exp $ -->
   2  Exportable objects are objects that can live either in the database or in code, or in both. If they live in both, then the object in code is considered to be "overridden", meaning that the version in code is ignored in favor of the version in the database.
   3  
   4  The main benefit to this is that you can move objects that are intended to be structure or feature-related into code, thus removing them entirely from the database. This is a very important part of the deployment path, since in an ideal world, the database is primarily user generated content, whereas site structure and site features should be in code. However, many many features in Drupal rely on objects being in the database and provide UIs to create them.
   5  
   6  Using this system, you can give your objects dual life. They can be created in the UI, exported into code and put in revision control. Views and Panels both use this system heavily. Plus, any object that properly implements this system can be utilized by the Features module to be used as part of a bundle of objects that can be turned into feature modules.
   7  
   8  Typically, exportable objects have two identifiers. One identifier is a simple serial used for database identification. It is a primary key in the database and can be used locally. It also has a name which is an easy way to uniquely identify it. This makes it much less likely that importing and exporting these objects across systems will have collisions. They still can, of course, but with good name selection, these problems can be worked around.
   9  
  10  <h3>Making your objects exportable</h3>
  11  To make your objects exportable, you do have to do a medium amount of work.
  12  <ol>
  13  <li>Create a chunk of code in your object's schema definition in the .install file to introduce the object to CTools' export system.</li>
  14  <li>Create a load function for your object that utilizes ctools_export_load_object().</li>
  15  <li>Create a save function for your object that utilizes drupal_write_record() or any method you desire.</li>
  16  <li>Create an import and export mechanism from the UI.</li>
  17  </ol>
  18  <h3>The export section of the schema file</h3>
  19  
  20  Exportable objects are created by adding definition to the schema in an 'export' section. For example:
  21  
  22  <pre>
  23  function mymodule_schema() {
  24    $schema['mymodule_myobj'] = array(
  25      'description' => t('Table storing myobj definitions.'),
  26      'export' => array(
  27        'key' => 'name',
  28        'key name' => 'Name',
  29        'primary key' => 'oid',
  30        'identifier' => 'myobj', // Exports will be as $myobj
  31        'default hook' => 'default_mymodule_myobj',  // Function hook name.
  32        'api' => array(
  33          'owner' => 'mymodule',
  34          'api' => 'default_mymodule_myobjs',  // Base name for api include files.
  35          'minimum_version' => 1,
  36          'current_version' => 1,
  37        ),
  38        // If the key is stored in a table that is joined in, specify it:
  39        'key in table' => 'my_join_table',
  40  
  41      ),
  42  
  43      // If your object's data is split up across multiple tables, you can
  44      // specify additional tables to join. This is very useful when working
  45      // with modules like exportables.module that has a special table for
  46      // translating keys to local database IDs.
  47      //
  48      // The joined table must have its own schema definition.
  49      //
  50      // If using joins, you should implement a 'delete callback' (see below)
  51      // to ensure that deletes happen properly. export.inc does not do this
  52      // automatically!
  53      'join' => array(
  54        'exportables' => array(
  55          // The following parameters will be used in this way:
  56          // SELECT ... FROM {mymodule_myobj} t__0 INNER JOIN {my_join_table} t__1 ON t__0.id = t__1.id AND extras
  57          'table' => 'my_join_table',
  58          'left_key' => 'format',
  59          'right_key' => 'id',
  60          // Optionally you can define extra clauses to add to the INNER JOIN
  61          'extras' => "AND extra_clauses",
  62  
  63          // You must specify which fields will be loaded. These fields must
  64          // exist in the schema definition of the joined table.
  65          'load' => array(
  66            'machine',
  67          ),
  68  
  69          // And finally you can define other tables to perform INNER JOINS
  70          //'other_joins' => array(
  71          //   'table' => ...
  72          //),
  73        ),
  74      )
  75      'fields' => array(
  76        'name' => array(
  77          'type' => 'varchar',
  78          'length' => '255',
  79          'description' => 'Unique ID for this object. Used to identify it programmatically.',
  80        ),
  81        'oid' => array(
  82          'type' => 'serial',
  83          'unsigned' => TRUE,
  84          'not null' => TRUE,
  85          'description' => 'Primary ID field for the table. Not used for anything except internal lookups.',
  86          'no export' => TRUE, // Do not export database-only keys.
  87        ),
  88      // ......
  89      'primary key' => array('oid'),
  90      'unique keys' => array(
  91        'name' => array('name'),
  92      ),
  93    );
  94    return $schema;
  95  }
  96  </pre>
  97  
  98  <dl>
  99  <dt>key</dt>
 100  <dd>This is the primary key of the exportable object and should be a string as names are more portable across systems. It is possible to use numbers here, but be aware that export collisions are very likely. Defaults to 'name'.</dd>
 101  
 102  <dt>key name</dt>
 103  <dd>Human readable title of the export key. Defaults to 'Name'. Because the schema is cached, do not translate this. It must instead be translated when used.</dd>
 104  
 105  <dt>primary key</dt>
 106  <dd>Objects should contain a primary key which is a database identifier primarily used to determine if an object has been written or not. This is required for the default CRUD save callback to work.</dd>
 107  
 108  <dt>object</dt>
 109  <dd>The class the object should be created as. Defaults as stdClass.</dd>
 110  
 111  <dt>can disable</dt>
 112  <dd>Control whether or not the exportable objects can be disabled. All this does is cause the 'disabled' field on the object to always be set appropriately, and a variable is kept to record the state. Changes made to this state must be handled by the owner of the object. Defaults to TRUE.</dd>
 113  
 114  <dt>status</dt>
 115  <dd>Exportable objects can be enabled or disabled, and this status is stored in a variable. This defines what variable that is. Defaults to: 'default_' . $table.</dd>
 116  
 117  <dt>default hook</dt>
 118  <dd>What hook to invoke to find exportable objects that are currently defined. These will all be gathered into a giant array. Defaults to 'default_' . $table.</dd>
 119  
 120  <dt>identifier</dt>
 121  <dd>When exporting the object, the identifier is the variable that the exported object will be placed in. Defaults to $table.</dd>
 122  
 123  <dt>bulk export</dt>
 124  <dd>Declares whether or not the exportable will be available for bulk exporting.</dd>
 125  
 126  <dt>list callback</dt>
 127  <dd>Bulk export callback to provide a list of exportable objects to be chosen for bulk exporting. Defaults to $module . '_' . $table . '_list' if the function exists. If it is not, a default listing function will be provided that will make a best effort to list the titles. See ctools_export_default_list().</dd>
 128  
 129  <dt>to hook code callback</dt>
 130  <dd>Function used to generate an export for the bulk export process. This is only necessary if the export is more complicated than simply listing the fields. Defaults to $module . '_' . $table . '_to_hook_code'.</dt>
 131  </dl>
 132  
 133  <dt>create callback</dt>
 134  <dd>CRUD callback to use to create a new exportable item in memory. If not provided, the default function will be used. The single argument is a boolean used to determine if defaults should be set on the object. This object will not be written to the database by this callback.</dd>
 135  
 136  <dt>load callback</dt>
 137  <dd>CRUD callback to use to load a single item. If not provided, the default load function will be used. The callback will accept a single argument which should be an identifier of the export key.</dd>
 138  
 139  <dt>load all callback</dt>
 140  <dd>CRUD callback to use to load all items, usually for administrative purposes. If not provided, the default load function will be used. The callback will accept a single argument to determine if the load cache should be reset or not.</dd>
 141  
 142  <dt>save callback</dt>
 143  <dd>CRUD callback to use to save a single item. If not provided, the default save function will be used. The callback will accept a single argument which should be the complete exportable object to save.</dd>
 144  
 145  <dt>delete callback</dt>
 146  <dd>CRUD callback to use to delete a single item. If not provided, the default delete function will be used. The callback will accept a single argument which can be *either* the object or just the export key to delete. The callback MUST be able to accept either.</dd>
 147  
 148  <dt>export callback</dt>
 149  <dd>CRUD callback to use for exporting. If not provided, the default export function will be used. The callback will accept two arguments, the first is the item to export, the second is the indent to place on the export, if any.</dd>
 150  
 151  <dt>import callback</dt>
 152  <dd>CRUD callback to use for importing. If not provided, the default export function will be used. This function will accept the code as a single argument and, if the code evaluates, return an object represented by that code. In the case of failure, this will return a string with human readable errors.</dd>
 153  
 154  In addition, each field can contain the following:
 155  <dl>
 156  <dt>no export</dt>
 157  <dd>Set to TRUE to prevent that field from being exported.</dd>
 158  
 159  <dt>export callback</dt>
 160  <dd>A function to override the export behavior. It will receive ($myobject, $field, $value, $indent) as arguments. By default, fields are exported through ctools_var_export().</dd>
 161  </dl>
 162  
 163  <h3>Reserved keys on exportable objects</h3>
 164  
 165  Exportable objects have several reserved keys that are used by the CTools export API. Each key can be found at <code>$myobj-&gt;{$key}</code> on an object loaded through <code>ctools_export_load_object()</code>. Implementing modules should not use these keys as they will be overwritten by the CTools export API.
 166  <dl>
 167  <dt>api_version</dt>
 168  <dd>The API version that this object implements.</dd>
 169  
 170  <dt>disabled</dt>
 171  <dd>A boolean for whether the object is disabled.</dd>
 172  
 173  <dt>export_module</dt>
 174  <dd>For objects that live in code, the module which provides the default object.</dd>
 175  
 176  <dt>export_type</dt>
 177  <dd>A bitmask representation of an object current storage. You can use this bitmask in combination with the <code>EXPORT_IN_CODE</code> and <code>EXPORT_IN_DATABASE</code> constants to test for an object's storage in your code.
 178  </dd>
 179  
 180  <dt>in_code_only</dt>
 181  <dd>A boolean for whether the object lives only in code.</dd>
 182  
 183  <dt>table</dt>
 184  <dd>The schema API table that this object belongs to.</dd>
 185  
 186  <dt>type</dt>
 187  <dd>A string representing the storage type of this object. Can be one of the following:
 188  <ul>
 189  <li><em>Normal</em> is an object that lives only in the database.</li>
 190  <li><em>Overridden</em> is an object that lives in the database and is overriding the exported configuration of a corresponding object in code.</li>
 191  <li><em>Default</em> is an object that lives only in code.</li>
 192  </ul>
 193  </dd>
 194  </dl>
 195  
 196  <h3>The load callback</h3>
 197  Calling ctools_export_crud_load($table, $name) will invoke your load callback, and calling ctools_export_crud_load_all($table, $reset) will invoke your load all callback. The default handlers should be sufficient for most uses.
 198  
 199  Typically, there will be two load functions. A 'single' load, to load just one object, and an 'all' load, to load all of the objects for use in administrating the objects or utilizing the objects when you need all of them. Using ctools_export_load_object() you can easily do both, as well as quite a bit in between. This example duplicates the default functionality for loading one myobj.
 200  
 201  <pre>
 202  /**
 203  * Load a single myobj.
 204  */
 205  function mymodule_myobj_load($name) {
 206    ctools_include('export');
 207    $result = ctools_export_load_object('mymodule_myobjs', 'names', array($name));
 208    if (isset($result[$name])) {
 209      return $result[$name];
 210    }
 211  }
 212  </pre>
 213  
 214  <h3>The save callback</h3>
 215  Calling ctools_export_crud_save($table, $object) will invoke your save callback. The default handlers should be sufficient for most uses. For the default save mechanism to work, you <b>must</b> define a 'primary key' in the 'export' section of your schema. The following example duplicates the default functionality for the myobj.
 216  
 217  <pre>
 218  /**
 219  * Save a single myobj.
 220  */
 221  function mymodule_myobj_save(&$myobj) {
 222    $update = (isset($myobj->oid) && is_numeric($myobj->oid)) ? array('oid') : array();
 223    return drupal_write_record('myobj', $myobj, $update);
 224  }
 225  </pre>
 226  
 227  <h3>Default hooks for your exports</h3>
 228  All exportables come with a 'default' hook, which can be used to put your exportable into code. The easiest way to actually use this hook is to set up your exportable for bulk exporting, enable the bulk export module and export an object.