source: sipes/modules_contrib/ctools/help/export.html @ 2efe680

stableversion-3.0
Last change on this file since 2efe680 was 2efe680, checked in by José Gregorio Puentes <jpuentes@…>, 8 años ago

se actualizo el modulo

  • Propiedad mode establecida a 100755
File size: 13.0 KB
Línea 
1Exportable 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.
2
3The 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.
4
5Using 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.
6
7Typically, 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.
8
9<h3>Making your objects exportable</h3>
10To make your objects exportable, you do have to do a medium amount of work.
11<ol>
12<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>
13<li>Create a load function for your object that utilizes ctools_export_load_object().</li>
14<li>Create a save function for your object that utilizes drupal_write_record() or any method you desire.</li>
15<li>Create an import and export mechanism from the UI.</li>
16</ol>
17<h3>The export section of the schema file</h3>
18
19Exportable objects are created by adding definition to the schema in an 'export' section. For example:
20
21<pre>
22function mymodule_schema() {
23  $schema['mymodule_myobj'] = array(
24    'description' => t('Table storing myobj definitions.'),
25    'export' => array(
26      'key' => 'name',
27      'key name' => 'Name',
28      'primary key' => 'oid',
29      'identifier' => 'myobj', // Exports will be as $myobj
30      'default hook' => 'default_mymodule_myobj',  // Function hook name.
31      'api' => array(
32        'owner' => 'mymodule',
33        'api' => 'default_mymodule_myobjs',  // Base name for api include files.
34        'minimum_version' => 1,
35        'current_version' => 1,
36      ),
37      // If the key is stored in a table that is joined in, specify it:
38      'key in table' => 'my_join_table',
39
40    ),
41
42    // If your object's data is split up across multiple tables, you can
43    // specify additional tables to join. This is very useful when working
44    // with modules like exportables.module that has a special table for
45    // translating keys to local database IDs.
46    //
47    // The joined table must have its own schema definition.
48    //
49    // If using joins, you should implement a 'delete callback' (see below)
50    // to ensure that deletes happen properly. export.inc does not do this
51    // automatically!
52    'join' => array(
53      'exportables' => array(
54        // The following parameters will be used in this way:
55        // SELECT ... FROM {mymodule_myobj} t__0 INNER JOIN {my_join_table} t__1 ON t__0.id = t__1.id AND extras
56        'table' => 'my_join_table',
57        'left_key' => 'format',
58        'right_key' => 'id',
59        // Optionally you can define extra clauses to add to the INNER JOIN
60        'extras' => "AND extra_clauses",
61
62        // You must specify which fields will be loaded. These fields must
63        // exist in the schema definition of the joined table.
64        'load' => array(
65          'machine',
66        ),
67
68        // And finally you can define other tables to perform INNER JOINS
69        //'other_joins' => array(
70        //   'table' => ...
71        //),
72      ),
73    )
74    'fields' => array(
75      'name' => array(
76        'type' => 'varchar',
77        'length' => '255',
78        'description' => 'Unique ID for this object. Used to identify it programmatically.',
79      ),
80      'oid' => array(
81        'type' => 'serial',
82        'unsigned' => TRUE,
83        'not null' => TRUE,
84        'description' => 'Primary ID field for the table. Not used for anything except internal lookups.',
85        'no export' => TRUE, // Do not export database-only keys.
86      ),
87    // ......
88    'primary key' => array('oid'),
89    'unique keys' => array(
90      'name' => array('name'),
91    ),
92  );
93  return $schema;
94}
95</pre>
96
97<dl>
98<dt>key</dt>
99<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>
100
101<dt>key name</dt>
102<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>
103
104<dt>primary key</dt>
105<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>
106
107<dt>object</dt>
108<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>
109
110<dt>object factory</dt>
111<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>
112
113<dt>can disable</dt>
114<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>
115
116<dt>status</dt>
117<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>
118
119<dt>default hook</dt>
120<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>
121
122<dt>identifier</dt>
123<dd>When exporting the object, the identifier is the variable that the exported object will be placed in. Defaults to $table.</dd>
124
125<dt>bulk export</dt>
126<dd>Declares whether or not the exportable will be available for bulk exporting.</dd>
127
128<dt>export type string</dt>
129<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>
130
131<dt>list callback</dt>
132<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>
133
134<dt>to hook code callback</dt>
135<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>
136</dl>
137
138<dt>create callback</dt>
139<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>
140
141<dt>load callback</dt>
142<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>
143
144<dt>load all callback</dt>
145<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>
146
147<dt>save callback</dt>
148<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>
149
150<dt>delete callback</dt>
151<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>
152
153<dt>export callback</dt>
154<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>
155
156<dt>import callback</dt>
157<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>
158
159In addition, each field can contain the following:
160<dl>
161<dt>no export</dt>
162<dd>Set to TRUE to prevent that field from being exported.</dd>
163
164<dt>export callback</dt>
165<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>
166</dl>
167
168<h3>Reserved keys on exportable objects</h3>
169
170Exportable 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.
171<dl>
172<dt>api_version</dt>
173<dd>The API version that this object implements.</dd>
174
175<dt>disabled</dt>
176<dd>A boolean for whether the object is disabled.</dd>
177
178<dt>export_module</dt>
179<dd>For objects that live in code, the module which provides the default object.</dd>
180
181<dt>export_type</dt>
182<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.
183</dd>
184
185<dt>in_code_only</dt>
186<dd>A boolean for whether the object lives only in code.</dd>
187
188<dt>table</dt>
189<dd>The schema API table that this object belongs to.</dd>
190
191<dt>type</dt>
192<dd>A string representing the storage type of this object. Can be one of the following:
193<ul>
194<li><em>Normal</em> is an object that lives only in the database.</li>
195<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>
196<li><em>Default</em> is an object that lives only in code.</li>
197</ul>
198<i>Note: This key can be changed by setting 'export type string' to something else, to try and prevent "type" from conflicting.</i>
199</dd>
200</dl>
201
202<h3>The load callback</h3>
203Calling 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.
204
205Typically, 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.
206
207<pre>
208/**
209* Load a single myobj.
210*/
211function mymodule_myobj_load($name) {
212  ctools_include('export');
213  $result = ctools_export_load_object('mymodule_myobjs', 'names', array($name));
214  if (isset($result[$name])) {
215    return $result[$name];
216  }
217}
218</pre>
219
220<h3>The save callback</h3>
221Calling 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.
222
223<pre>
224/**
225* Save a single myobj.
226*/
227function mymodule_myobj_save(&$myobj) {
228  $update = (isset($myobj->oid) && is_numeric($myobj->oid)) ? array('oid') : array();
229  return drupal_write_record('myobj', $myobj, $update);
230}
231</pre>
232
233<h3>Default hooks for your exports</h3>
234All 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.
Nota: Vea TracBrowser para ayuda de uso del navegador del repositorio.