materio-base-d7/sites/all/modules/contrib/dev/ctools/help/export.html

<p>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.</p>

<p>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.</p>

<p>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.</p>

<p>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.</p>

<h2>Making your objects exportable</h2>

<p>To make your objects exportable, you do have to do a medium amount of work.</p>

<ol>
  <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>
  <li>Create a load function for your object that utilizes ctools_export_load_object().</li>
  <li>Create a save function for your object that utilizes drupal_write_record() or any method you desire.</li>
  <li>Create an import and export mechanism from the UI.</li>
</ol>

<h2>The export section of the schema file</h2>

<p>Exportable objects are created by adding definition to the schema in an 'export' section. For example:</p>

<pre>
function mymodule_schema() {
  $schema['mymodule_myobj'] = array(
    'description' => t('Table storing myobj definitions.'),
    'export' => array(
      'key' => 'name',
      'key name' => 'Name',
      'primary key' => 'oid',
      'identifier' => 'myobj', // Exports will be as $myobj
      'default hook' => 'default_mymodule_myobj',  // Function hook name.
      'api' => array(
        'owner' => 'mymodule',
        'api' => 'default_mymodule_myobjs',  // Base name for api include files.
        'minimum_version' => 1,
        'current_version' => 1,
      ),
      // If the key is stored in a table that is joined in, specify it:
      'key in table' => 'my_join_table',

    ),

    // If your object's data is split up across multiple tables, you can
    // specify additional tables to join. This is very useful when working
    // with modules like exportables.module that has a special table for
    // translating keys to local database IDs.
    //
    // The joined table must have its own schema definition.
    //
    // If using joins, you should implement a 'delete callback' (see below)
    // to ensure that deletes happen properly. export.inc does not do this
    // automatically!
    'join' => array(
      'exportables' => array(
        // The following parameters will be used in this way:
        // SELECT ... FROM {mymodule_myobj} t__0 INNER JOIN {my_join_table} t__1 ON t__0.id = t__1.id AND extras
        'table' => 'my_join_table',
        'left_key' => 'format',
        'right_key' => 'id',
        // Optionally you can define a callback to add custom conditions or
        // alter the query as necessary. The callback function takes 3 args:
        //
        //   myjoincallback(&$query, $schema, $join_schema);
        //
        // where $query is the database query object, $schema is the schema for
        // the export base table and $join_schema is the schema for the current
        // join table.
        'callback' => 'myjoincallback',

        // You must specify which fields will be loaded. These fields must
        // exist in the schema definition of the joined table.
        'load' => array(
          'machine',
        ),

        // And finally you can define other tables to perform INNER JOINS
        //'other_joins' => array(
        //   'table' => ...
        //),
      ),
    )
    'fields' => array(
      'name' => array(
        'type' => 'varchar',
        'length' => '255',
        'description' => 'Unique ID for this object. Used to identify it programmatically.',
      ),
      'oid' => array(
        'type' => 'serial',
        'unsigned' => TRUE,
        'not null' => TRUE,
        'description' => 'Primary ID field for the table. Not used for anything except internal lookups.',
        'no export' => TRUE, // Do not export database-only keys.
      ),
    // ......
    'primary key' => array('oid'),
    'unique keys' => array(
      'name' => array('name'),
    ),
  );
  return $schema;
}
</pre>

<dl>
<dt>key</dt>
<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>

<dt>key name</dt>
<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>

<dt>primary key</dt>
<dd>A single field within the table that is to be used as the main identifier to discern whether or not the object has been written. As the schema definition's primary key value will be used by default, it is not usually necessary to define this.</dd>

<dt>object</dt>
<dd>The class the object should be created as, if 'object factory' is not set. If this is not set either, defaults as stdClass.</dd>

<dt>object factory</dt>
<dd>Function used to create the object. The function receives the schema and the loaded data as a parameters: your_factory_function($schema, $data). If this is set,  'object' has no effect since you can use your function to create whatever class you wish.</dd>

<dt>admin_title</dt>
<dd>A convenience field that may contain the field which represents the human readable administrative title for use in export UI. If a field "admin_title" exists, it will automatically be used.</dd>

<dt>admin_description</dt>
<dd>A convenience field that may contain the field which represents the human readable administrative title for use in export UI. If a field "admin_title" exists, it will automatically be used.</dd>

<dt>can disable</dt>
<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>

<dt>status</dt>
<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>

<dt>default hook</dt>
<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>

<dt>cache defaults</dt>
<dd>If true, default objects will be cached so that the processing of the hook does not need to be called often. Defaults to FALSE. Recommended if you will potentially have a lot of objects in code. Not recommended if code will be the exception.</dd>

<dt>default cache bin</dt>
<dd>If default object caching is enabled, what cache bin to use. This defaults to the basic "cache". It is highly recommended that you use a different cache bin if possible.</dd>

<dt>identifier</dt>
<dd>When exporting the object, the identifier is the variable that the exported object will be placed in. Defaults to $table.</dd>

<dt>bulk export</dt>
<dd>Declares whether or not the exportable will be available for bulk exporting.</dd>

<dt>export type string</dt>
<dd>The export type string (Local, Overridden, Database) is normally stored as $item-&gt;type. Since type is a very common keyword, it's possible to specify what key to actually use. </dd>

<dt>list callback</dt>
<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>

<dt>to hook code callback</dt>
<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'.</dd>

<dt>boolean</dt>
<dd>Explicitly indicate if a table field contains a boolean or not. The Schema API does not model the
difference between a tinyint and a boolean type. Boolean values are stored in tinyint fields. This may cause mismatch errors when exporting a non-boolean value from a tinyint field. Add this to a tinyint field if it contains boolean data and can be exported. Defaults to TRUE.

<dt>create callback</dt>
<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>

<dt>load callback</dt>
<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>

<dt>load multiple callback</dt>
<dd>CRUD callback to use to load multiple items. If not provided, the default multiple load function will be used. The callback will accept an array which should be the identifiers of the export key.</dd>

<dt>load all callback</dt>
<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>

<dt>save callback</dt>
<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>

<dt>delete callback</dt>
<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>

<dt>export callback</dt>
<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>

<dt>import callback</dt>
<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>

<dt>status callback</dt>
<dd>CRUD callback to use for updating the status of an object. If the status is TRUE the object will be disabled. If the status is FALSE the object will be enabled.</dd>

<dt>api</dt>
<dd>The 'api' key can optionally contain some information for the plugin API definition. This means that the imports can be tied to an API name which is used to have automatic inclusion of files, and can be used to prevent dangerous objects from older versions from being loaded, causing a loss of functionality rather than site crashes or security loopholes.

<p>If not present, no additional files will be loaded and the default hook will always be a simple hook that must be either part of the .module file or loaded during normal operations.</p>

<p>api supports these subkeys:</p>

<dl>
<dt>owner</dt>
<dd>The module that owns the API. Typically this is the name of the module that owns the schema. This will be one of the two keys used by hook_ctools_plugin_api() to determine version compatibility. Note that the name of this hook can be tailored via the use of hook_ctools_plugin_api_hook_name(). See ctools_plugin_api_get_hook() for details.</dd>
<dt>api</dt>
<dd>This is the name of the API, and will be the second parameter to the above mentioned hook. It will also be used as part of the name of the file that the hook containing default objects will be in, which comes in the form of MODULENAME.API.inc.</dd>
<dt>minimum_version</dt>
<dd>The minimum version supported. Any module reporting an API less than this will not have its default objects used. This should be updated only when API changes can cause older objects to crash or otherwise break badly.</dd>
<dt>current_version</dt>
<dd>The current version of the API. Any module reporting a required API higher than this will not have its default objects used.</dd>
</dl>
</dd>

</dl>
<p>In addition, each field can contain the following:</p>
<dl>
<dt>no export</dt>
<dd>Set to TRUE to prevent that field from being exported.</dd>

<dt>export callback</dt>
<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>
</dl>

<h2>Reserved keys on exportable objects</h2>

<p>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.</p>
<dl>
<dt>api_version</dt>
<dd>The API version that this object implements.</dd>

<dt>disabled</dt>
<dd>A boolean for whether the object is disabled.</dd>

<dt>export_module</dt>
<dd>For objects that live in code, the module which provides the default object.</dd>

<dt>export_type</dt>
<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.
</dd>

<dt>in_code_only</dt>
<dd>A boolean for whether the object lives only in code.</dd>

<dt>table</dt>
<dd>The schema API table that this object belongs to.</dd>

<dt>type</dt>
<dd>A string representing the storage type of this object. Can be one of the following:
<ul>
<li><em>Normal</em> is an object that lives only in the database.</li>
<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>
<li><em>Default</em> is an object that lives only in code.</li>
</ul>
<i>Note: This key can be changed by setting 'export type string' to something else, to try and prevent "type" from conflicting.</i>
</dd>
</dl>

<h2>The load callback</h2>
<p>Calling ctools_export_crud_load($table, $name) will invoke your load callback, calling ctools_export_crud_load_multiple($table, $names) will invoke your load multiple 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.</p>

<p>Typically, there will be three load functions. A 'single' load, to load just one object, a 'multiple' load to load multiple objects, 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.</p>

<pre>
/**
 * Implements 'load callback' for myobj exportables.
 */
function mymodule_myobj_load($name) {
  ctools_include('export');
  $result = ctools_export_load_object('mymodule_myobjs', 'names', array($name));
  if (isset($result[$name])) {
    return $result[$name];
  }
}

/**
 * Implements 'load multiple callback' for myobj exportables.
 */
function mymodule_myobj_load_multiple(array $names) {
  ctools_include('export')
  $results = ctools_export_load_object('mymodule_myobjs', 'names', $names);
  return array_filter($results);
}
</pre>

<h2>The save callback</h2>
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.

<pre>
/**
* Save a single myobj.
*/
function mymodule_myobj_save(&$myobj) {
  $update = (isset($myobj->oid) && is_numeric($myobj->oid)) ? array('oid') : array();
  return drupal_write_record('myobj', $myobj, $update);
}
</pre>

<h2>Default hooks for your exports</h2>
<p>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.</p>