diff options
Diffstat (limited to 'sites/all/modules/ctools/help')
24 files changed, 1703 insertions, 0 deletions
diff --git a/sites/all/modules/ctools/help/about.html b/sites/all/modules/ctools/help/about.html new file mode 100644 index 000000000..30b64c2d3 --- /dev/null +++ b/sites/all/modules/ctools/help/about.html @@ -0,0 +1,29 @@ +<p>The Chaos Tool Suite is a series of tools for developers to make code that I've found to be very useful to Views and Panels more readily available. Certain methods of doing things, particularly with AJAX, exportable objects and a plugin system, are proving to be ideas that are useful outside of just Views and Panels. This module does not offer much directly to the end user, but instead, creates a library for other modules to use. If you are an end user and some module asked you to install the CTools suite, then this is far as you really need to go. If you're a developer and are interested in these tools, read on!</p> + +<h2>Tools provided by CTools</h2> + +<dl> +<dt><a href="&topic:ctools/plugins&">Plugins</a></dt> +<dd>The plugins tool allows a module to allow <b>other</b> modules (and themes!) to provide plugins which provide some kind of functionality or some kind of task. For example, in Panels there are several types of plugins: Content types (which are like blocks), layouts (which are page layouts) and styles (which can be used to style a panel). Each plugin is represented by a .inc file, and the functionality they offer can differ wildly.</dd> + +<dt><a href="&topic:ctools/context&">Context</a></dt> +<dd>Context is the idea that the objects that are used in page generation have more value than simply creating a single piece of output. Instead, contexts can be used to create multiple pieces of content that can all be put onto the page. Additionally, contexts can be used to derive other contexts via relationships, such as determining the node author and displaying data about the new context.</dd> + +<dt><a href="&topic:ctools/ajax&">AJAX Tools</a></dt> +<dd>AJAX (also known as AHAH) is a method of allowing the browser and the server to communicate without requiring a page refresh. It can be used to create complicated interactive forms, but it is somewhat difficult to integrate into Drupal's Form API. These tools make it easier to accomplish this goal. In addition, CTools provides a few other javascript helpers, such as a modal dialog, a collapsible div, a simple dropdown and dependent checkboxes.</dd> + +<dt><a href="&topic:ctools/css&">CSS scrubbing and caching</a></dt> +<dd>Drupal comes with a fantastic array of tools to ensure HTML is safe to output but does not contain any similar tools for CSS. CTools provides a small tool to sanitize CSS, so user-input CSS code can still be safely used. It also provides a method for caching CSS for better performance.</dd> + +<dt><a href="&topic:ctools/export&">Exportable objects</a></dt> +<dd>Views and Panels both use objects that can either be in code or in the database, and the objects can be exported into a piece of PHP code, so they can be moved from site to site or out of the database entirely. This library abstracts that functionality, so other modules can use this same concept for their data.</dd> + +<dt><a href="&topic:ctools/form&">Form tools</a></dt> +<dd>Drupal 6's FAPI really improved over Drupal 5, and made a lot of things possible. Still, it missed a few items that were needed to make form wizards and truly dynamic AJAX forms possible. CTools includes a replacement for drupal_get_form() that has a few more options and allows the caller to examine the $form_state once the form has completed.</dd> + +<dt><a href="&topic:ctools/wizard&">Form wizards</a></dt> +<dd>Finally! An easy way to have form wizards, which is any 'form' that is actually a string of forms that build up to a final conclusion. The form wizard supports a single entry point, the ability to choose whether or not the user can go forward/back/up on the form and easy callbacks to handle the difficult job of dealing with data in between forms.</dd> + +<dt><a href="&topic:ctools/object-cache&">Temporary object cache</a></dt> +<dd>For normal forms, all of the data needed for an object is stored in the form so that the browser handles a lot of the work. For multi-step and ajax forms, however, this is impractical, and letting the browser store data can be insecure. The object cache provides a non-volatile location to store temporary data while the form is being worked on. This is much safer than the standard Drupal caching mechanism, which is volatile, meaning it can be cleared at any time and any system using it must be capable of recreating the data that was there. This system also allows for object locking, since any object which has an item in the cache from another person can be assumed to be 'locked for editing'.</dd> +</dl> diff --git a/sites/all/modules/ctools/help/ajax.html b/sites/all/modules/ctools/help/ajax.html new file mode 100644 index 000000000..e69de29bb --- /dev/null +++ b/sites/all/modules/ctools/help/ajax.html diff --git a/sites/all/modules/ctools/help/collapsible-div.html b/sites/all/modules/ctools/help/collapsible-div.html new file mode 100644 index 000000000..b9b6d9c63 --- /dev/null +++ b/sites/all/modules/ctools/help/collapsible-div.html @@ -0,0 +1 @@ +<p>To be written.</p> diff --git a/sites/all/modules/ctools/help/context-access.html b/sites/all/modules/ctools/help/context-access.html new file mode 100644 index 000000000..95a8d7fbe --- /dev/null +++ b/sites/all/modules/ctools/help/context-access.html @@ -0,0 +1,12 @@ +<p>Access plugins allow context based access control to pages.</p> +<pre> 'title' => Title of the plugin + 'description' => Description of the plugin + 'callback' => callback to see if there is access is available. params: $conf, $contexts, $account + 'required context' => zero or more required contexts for this access plugin + 'default' => an array of defaults or a callback giving defaults + 'settings form' => settings form. params: &$form, &$form_state, $conf + settings form validate + settings form submit +</pre> + +<p><strong>Warning:</strong> your settings array will be stored <strong>in the meny system</strong> to reduce loads, so be <strong>trim</strong>.</p>
\ No newline at end of file diff --git a/sites/all/modules/ctools/help/context-arguments.html b/sites/all/modules/ctools/help/context-arguments.html new file mode 100644 index 000000000..5c479ae65 --- /dev/null +++ b/sites/all/modules/ctools/help/context-arguments.html @@ -0,0 +1,14 @@ +<p>Arguments create a context from external input, which is assumed to be a string as though it came from a URL element.</p> + +<pre>'title' => title + 'description' => Description + 'keyword' => Default keyword for the context + 'context' => Callback to create the context. Params: $arg = NULL, $conf = NULL, $empty = FALSE + 'default' => either an array of default settings or a string which is a callback or null to not use. + 'settings form' => params: $form, $form_state, $conf -- gets the whole form. Should put anything it wants to keep automatically in $form['settings'] + 'settings form validate' => params: $form, $form_state + 'settings form submit' => params: $form, $form_state + 'criteria form' => params: $form, &$form_state, $conf, $argument, $id -- gets the whole argument. It should only put form widgets in $form[$id]. $conf may not be properly initialized so always guard against this due to arguments being changed and handlers not being updated to match. + + submit + validate + 'criteria select' => returns true if the selected criteria matches the context. params: $context, $conf +</pre> diff --git a/sites/all/modules/ctools/help/context-content.html b/sites/all/modules/ctools/help/context-content.html new file mode 100644 index 000000000..c1c6a356d --- /dev/null +++ b/sites/all/modules/ctools/help/context-content.html @@ -0,0 +1,157 @@ +<p>The CTools pluggable content system provides various pieces of content as discrete bits of data that can be added to other applications, such as Panels or Dashboard via the UI. Whatever the content is added to stores the configuration for that individual piece of content, and provides this to the content.</p> + +<p>Each content type plugin will be contained in a .inc file, with subsidiary files, if necessary, in or near the same directory. Each content type consists of some information and one or more subtypes, which all use the same renderer. Subtypes are considered to be instances of the type. For example, the 'views' content type would have each view in the system as a subtype. Many content types will have exactly one subtype.</p> + +<p>Because the content and forms can be provided via ajax, the plugin also provides a list of CSS and JavaScript information that should be available on whatever page the content or forms may be AJAXed onto.</p> + +<p>For the purposes of selecting content from the UI, each content subtype will have the following information:</p> + +<ul> + <li>A title</li> + <li>A short description</li> + <li>A category [Do we want to add hierarchy categories? Do we want category to be more than just a string?]</li> + <li>An icon [do we want multiple icons? This becomes a hefty requirement]</li> +</ul> + +<p>Each piece of content provides one or more configuration forms, if necessary, and the system that includes the content will handle the data storage. These forms can be provided in sequence as wizards or as extra forms that can be accessed through advanced administration.</p> + +<p>The plugin for a content type should contain:</p> + +<dl> + <dt>title</dt> + <dd>For use on the content permissions screen.</dd> + <dt>content types</dt> + <dd>Either an array of content type definitions, or a callback that will return content type definitions. This callback will get the plugin definition as an argument.</dd> + + <dt>content type</dt> + <dd>[Optional] Provide a single content type definition. This is only necessary if content types might be intensive.</dd> + + <dt>render callback</dt> + <dd>The callback to render the content. Parameters: + <dl> + <dt>$subtype</dt> + <dd>The name of the subtype being rendered. NOT the loaded subtype data.</dd> + + <dt>$conf</dt> + <dd>The stored configuration for the content.</dd> + + <dt>$args</dt> + <dd>Any arguments passed.</dd> + + <dt>$context</dt> + <dd>An array of contexts requested by the required contexts and assigned by the configuration step.</dd> + + <dt>$incoming_content</dt> + <dd>Any 'incoming content' if this is a wrapper.</dd> + </dl> + </dd> + + <dt>admin title</dt> + <dd>A callback to provide the administrative title. If it is not a function, then it will be counted as a string to use as the admin title.</dd> + + <dt>admin info</dt> + <dd>A callback to provide administrative information about the content, to be displayed when manipulating the content. It should contain a summary of configuration.</dd> + + <dt>edit form</dt> + <dd>Either a single form ID or an array of forms *keyed* by form ID with the value to be used as the title of the form. %title me be used as a placeholder for the administrative title if necessary. + Example: +<pre>array( + 'ctools_example_content_form_second' => t('Configure first form'), + 'ctools_example_content_form_first' => t('Configure second form'), +), +</pre> +The first form will always have required configuration added to it. These forms are normal FAPI forms, but you do not need to provide buttons, these will be added by the form wizard. + </dd> + + <dt>add form</dt> + <dd>[Optional] If different from the edit forms, provide them here in the same manner. Also may be set to FALSE to not have an add form.</dd> + + <dt>css</dt> + <dd>A file or array of CSS files that are necessary for the content.</dd> + + <dt>js</dt> + <dd>A file or array of javascript files that are necessary for the content to be displayed.</dd> + + <dt>admin css</dt> + <dd>A file or array of CSS files that are necessary for the forms.</dd> + + <dt>admin js</dt> + <dd>A file or array of JavaScript files that are necessary for the forms.</dd> + + <dt>extra forms</dt> + <dd>An array of form information to handle extra administrative forms.</dd> + + <dt>no title override</dt> + <dd>Set to TRUE if the title cannot be overridden.</dd> + + <dt>single</dt> + <dd>Set to TRUE if this content provides exactly one subtype.</dd> + + <dt>render last</dt> + <dd>Set to true if for some reason this content needs to render after other content. This is primarily used for forms to ensure that render order is correct.</dd> +</dl> + +<p>TODO: many of the above callbacks can be assumed based upon patterns: modulename + '_' + name + '_' + function. i.e, render, admin_title, admin_info, etc.</p> + +<p>TODO: Some kind of simple access control to easily filter out content.</p> + +<p>The subtype definition should contain:</p> + +<dl> + <dt>title</dt> + <dd>The title of the subtype.</dd> + + <dt>icon</dt> + <dd>The icon to display for the subtype.</dd> + + <dt>path</dt> + <dd>The path for the icon if it is not in the same directory as the plugin.</dd> + + <dt>description</dt> + <dd>The short description of the subtype, to be used when selecting it in the UI.</dd> + + <dt>category</dt> + <dd>Either a text string for the category, or an array of the text string followed by the category weight.</dd> + + <dt>required context [Optional]</dt> + + <dd>Either a ctools_context_required or ctools_context_optional or array of contexts for this content. If omitted, no contexts are used.</dd> + + <dt>create content access [Optional]</dt> + + <dd>An optional callback to determine if a user can access this subtype. The callback will receive two arguments, the type and subtype.</dd> +</dl> + +<h2>Rendered content</h2> + +<p>Rendered content is a little more than just HTML.</p> + +<dl> + <dt>title</dt> + <dd>The safe to render title of the content.</dd> + + <dt>content</dt> + <dd>The safe to render HTML content.</dd> + + <dt>links</dt> + <dd>An array of links associated with the content suitable for theme('links').</dd> + + <dt>more</dt> + <dd>An optional 'more' link (destination only)</dd> + + <dt>admin_links</dt> + <dd>Administrative links associated with the content, suitable for theme('links').</dd> + + <dt>feeds</dt> + <dd>An array of feed icons or links associated with the content. Each member of the array is rendered HTML.</dd> + + <dt>type</dt> + <dd>The content type.</dd> + + <dt>subtype</dt> + <dd>The content subtype. These two may be used together as module-delta for block style rendering.</dd> +</dl> + +<h2>Todo: example</h2> + +<p>Todo after implementations are updated to new version.</p> diff --git a/sites/all/modules/ctools/help/context-context.html b/sites/all/modules/ctools/help/context-context.html new file mode 100644 index 000000000..2314bd5ff --- /dev/null +++ b/sites/all/modules/ctools/help/context-context.html @@ -0,0 +1,13 @@ +<p>Context plugin data:</p> + +<pre> + 'title' => Visible title + 'description' => Description of context + 'context' => Callback to create a context. Params: $empty, $data = NULL, $conf = FALSE + 'settings form' => Callback to show a context setting form. Params: ($conf, $external = FALSE) + 'settings form validate' => params: ($form, &$form_values, &$form_state) + 'settings form submit' => params: 'ctools_context_node_settings_form_submit', + 'keyword' => The default keyword to use. + 'context name' => The unique identifier for this context for use by required context checks. + 'no ui' => if TRUE this context cannot be selected. +</pre>
\ No newline at end of file diff --git a/sites/all/modules/ctools/help/context-relationships.html b/sites/all/modules/ctools/help/context-relationships.html new file mode 100644 index 000000000..cc9969e1f --- /dev/null +++ b/sites/all/modules/ctools/help/context-relationships.html @@ -0,0 +1,13 @@ +<p>Relationship plugin data:</p> + +<pre> + 'title' => The title to display. + 'description' => Description to display. + 'keyword' => Default keyword for the context created by this relationship. + 'required context' => One or more ctools_context_required/optional objects + describing the context input. + new panels_required_context(t('Node'), 'node'), + 'context' => The callback to create the context. Params: ($context = NULL, $conf) + 'settings form' => Settings form. Params: $conf + 'settings form validate' => Validate. +</pre> diff --git a/sites/all/modules/ctools/help/context.html b/sites/all/modules/ctools/help/context.html new file mode 100644 index 000000000..e69de29bb --- /dev/null +++ b/sites/all/modules/ctools/help/context.html diff --git a/sites/all/modules/ctools/help/css.html b/sites/all/modules/ctools/help/css.html new file mode 100644 index 000000000..b9b6d9c63 --- /dev/null +++ b/sites/all/modules/ctools/help/css.html @@ -0,0 +1 @@ +<p>To be written.</p> diff --git a/sites/all/modules/ctools/help/ctools.help.ini b/sites/all/modules/ctools/help/ctools.help.ini new file mode 100644 index 000000000..fcb121b8d --- /dev/null +++ b/sites/all/modules/ctools/help/ctools.help.ini @@ -0,0 +1,97 @@ +[advanced help settings] +line break = TRUE + +[about] +title = About Chaos Tool Suite +weight = -100 + +[context] +title = Context tool +weight = -40 + +[context-access] +title = Context based access control plugins +parent = context + +[context-context] +title = Context plugins +parent = context + +[context-arguments] +title = Argument plugins +parent = context + +[context-relationships] +title = Relationship plugins +parent = context + +[context-content] +title = Content plugins +parent = context + +[css] +title = CSS scrubbing and caching tool + +[menu] +title = Miscellaneous menu helper tool + +[plugins] +title = Plugins and APIs tool +weight = -50 + +[plugins-api] +title = Implementing APIs +parent = plugins + +[plugins-creating] +title = Creating plugins +parent = plugins + +[plugins-implementing] +title = Implementing plugins +parent = plugins + +[export] +title = Exportable objects tool + +[export-ui] +title = Exportable objects UI creator + +[form] +title = Form tools + +[wizard] +title = Form wizard tool + +[ajax] +title = AJAX and Javascript helper tools +weight = -30 + +[modal] +title = Javascript modal tool +parent = ajax + +[collapsible-div] +title = Javascript collapsible DIV +parent = ajax + +[dropdown] +title = Javascript dropdown +parent = ajax + +[dropbutton] +title = Javascript dropbutton +parent = ajax + +[dependent] +title = Dependent checkboxes and radio buttons +parent = ajax + +[object-cache] +title = Temporary object caching + +; A bunch of this stuff we'll put in panels. + +[plugins-content] +title = Creating content type plugins +parent = panels%api diff --git a/sites/all/modules/ctools/help/dependent.html b/sites/all/modules/ctools/help/dependent.html new file mode 100644 index 000000000..b9b6d9c63 --- /dev/null +++ b/sites/all/modules/ctools/help/dependent.html @@ -0,0 +1 @@ +<p>To be written.</p> diff --git a/sites/all/modules/ctools/help/dropbutton.html b/sites/all/modules/ctools/help/dropbutton.html new file mode 100644 index 000000000..b9b6d9c63 --- /dev/null +++ b/sites/all/modules/ctools/help/dropbutton.html @@ -0,0 +1 @@ +<p>To be written.</p> diff --git a/sites/all/modules/ctools/help/dropdown.html b/sites/all/modules/ctools/help/dropdown.html new file mode 100644 index 000000000..b9b6d9c63 --- /dev/null +++ b/sites/all/modules/ctools/help/dropdown.html @@ -0,0 +1 @@ +<p>To be written.</p> diff --git a/sites/all/modules/ctools/help/export-ui.html b/sites/all/modules/ctools/help/export-ui.html new file mode 100644 index 000000000..e6b1086e0 --- /dev/null +++ b/sites/all/modules/ctools/help/export-ui.html @@ -0,0 +1,85 @@ +<p>Most user interfaces for exportables are very similar, so CTools includes a tool to provide the framework for the most common UI. This tool is a plugin of the 'export_ui' type. In order to create a UI for your exportable object with this tool, you first need to ensure that your module supports the plugin:</p> + +<pre> +function HOOK_ctools_plugin_directory($module, $plugin) { + if ($module == 'ctools' && $plugin == 'export_ui') { + return 'plugins/' . $plugin; + } +} +</pre> + +<p>Then, you need to create a plugin .inc file describing your UI. Most of the UI runs with sane but simple defaults, so for the very simplest UI you don't need to do very much. This is a very simple example plugin for the 'example' export type:</p> + +<pre> +$plugin = array( + // The name of the table as found in the schema in hook_install. This + // must be an exportable type with the 'export' section defined. + 'schema' => 'example', + + // The access permission to use. If not provided it will default to + // 'administer site configuration' + 'access' => 'administer example', + + // You can actually define large chunks of the menu system here. Nothing + // is required here. If you leave out the values, the prefix will default + // to admin/structure and the item will default to the plugin name. + 'menu' => array( + 'menu prefix' => 'admin/structure', + 'menu item' => 'example', + // Title of the top level menu. Note this should not be translated, + // as the menu system will translate it. + 'menu title' => 'Example', + // Description of the top level menu, which is usually needed for + // menu items in an administration list. Will be translated + // by the menu system. + 'menu description' => 'Administer site example objects.', + ), + + // These are required to provide proper strings for referring to the + // actual type of exportable. "proper" means it will appear at the + // beginning of a sentence. + 'title singular' => t('example'), + 'title singular proper' => t('Example'), + 'title plural' => t('examples'), + 'title plural proper' => t('Examples'), + + // This will provide you with a form for editing the properties on your + // exportable, with validate and submit handler. + // + // The item being edited will be in $form_state['item']. + // + // The submit handler is only responsible for moving data from + // $form_state['values'] to $form_state['item']. + // + // All callbacks will accept &$form and &$form_state as arguments. + 'form' => array( + 'settings' => 'example_ctools_export_ui_form', + 'validate' => 'example_ctools_export_ui_form_validate', + 'submit' => 'example_ctools_export_ui_form_submit', + ), + +); +</pre> + +<p>For a more complete list of what you can set in your plugin, please see ctools_export_ui_defaults() in includes/export-ui.inc to see what the defaults are.</p> + +<h2>More advanced UIs</h2> + +<p>The bulk of this UI is built on an class called ctools_export_ui, which is itself stored in ctools/plugins/export_ui as the default plugin. Many UIs will have more complex needs than the defaults provide. Using OO and overriding methods can allow an implementation to use the basics and still provide more where it is needed. To utilize this, first add a 'handler' directive to your plugin .inc file:</p> + +<pre> + 'handler' => array( + 'class' => 'ctools_export_ui_example', + 'parent' => 'ctools_export_ui', + ), +</pre> + +Then create your class in ctools_export_ui_example.class.php in your plugins directory: + +<pre> +class ctools_export_ui_example extends ctools_export_ui { + +} +</pre> + +<p>You can override any method found in the class (see the source file for details). In particular, there are several list methods that are good candidates for overriding if you need to provide richer data for listing, sorting or filtering. If you need multi-step add/edit forms, you can override edit_page(), add_page(), clone_page(), and import_page() to put your wizard in place of the basic editing system. For an example of how to use multi-step wizards, see the import_page() method.</p> diff --git a/sites/all/modules/ctools/help/export.html b/sites/all/modules/ctools/help/export.html new file mode 100644 index 000000000..ce24cad9f --- /dev/null +++ b/sites/all/modules/ctools/help/export.html @@ -0,0 +1,294 @@ +<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->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'.</dt> + +<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->{$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> diff --git a/sites/all/modules/ctools/help/form.html b/sites/all/modules/ctools/help/form.html new file mode 100644 index 000000000..b9b6d9c63 --- /dev/null +++ b/sites/all/modules/ctools/help/form.html @@ -0,0 +1 @@ +<p>To be written.</p> diff --git a/sites/all/modules/ctools/help/modal.html b/sites/all/modules/ctools/help/modal.html new file mode 100644 index 000000000..ea823a0de --- /dev/null +++ b/sites/all/modules/ctools/help/modal.html @@ -0,0 +1,215 @@ +<p>CTools provides a simple modal that can be used as a popup to place forms. It differs from the normal modal frameworks in that it does not do its work via an iframe. This is both an advantage and a disadvantage. The iframe simply renders normal pages in a sub-browser and they can do their thing. That makes it much easier to put arbitrary pages and forms in a modal. However, the iframe is not very good at actually communicating changes to the main page, so you cannot open the modal, have it do some work, and then modify the page. </p> + +<h2>Invoking the modal</h2> + +<p>The basic form of the modal can be set up just by including the javascript and adding the proper class to a link or form that will open the modal. To include the proper javascript, simply include the library and call the add_js function:</p> + +<code>ctools_include('modal'); +ctools_modal_add_js(); +</code> + +<p>You can have links and buttons bound to use the modal by adding the class ctools-use-modal. For convenience, there is a helper function to try and do this, though it's not great at doing all links so using this is optional:</p> + +<code>/** + * Render an image as a button link. This will automatically apply an AJAX class + * to the link and add the appropriate javascript to make this happen. + * + * @param $image + * The path to an image to use that will be sent to theme('image') for rendering. + * @param $dest + * The destination of the link. + * @param $alt + * The alt text of the link. + * @param $class + * Any class to apply to the link. @todo this should be a options array. + */ +function ctools_modal_image_button($image, $dest, $alt, $class = '') { + return ctools_ajax_text_button(theme('image', array('path' => $image), $dest, $alt, $class, 'ctools-use-modal'); +} + +/** + * Render text as a link. This will automatically apply an AJAX class + * to the link and add the appropriate javascript to make this happen. + * + * Note: 'html' => true so be sure any text is vetted! Chances are these kinds of buttons will + * not use user input so this is a very minor concern. + * + * @param $text + * The text to display as the link. + * @param $dest + * The destination of the link. + * @param $alt + * The alt text of the link. + * @param $class + * Any class to apply to the link. @todo this should be a options array. + */ +function ctools_modal_text_button($text, $dest, $alt, $class = '') { + return ctools_ajax_text_button($text, $dest, $alt, $class, 'ctools-use-modal'); +} +</code> + +<p>Like with all CTools' AJAX functionality, the href of the link will be the destination, with any appearance of /nojs/ converted to /ajax/.</p> + +<p>For submit buttons, however, the URL may be found a different, slightly more complex way. If you do not wish to simply submit the form to the modal, you can create a URL using hidden form fields. The ID of the item is taken and -url is appended to it to derive a class name. Then, all form elements that contain that class name are founded and their values put together to form a URL.</p> + +<p>For example, let's say you have an 'add' button, and it has a select form item that tells your system what widget it is adding. If the id of the add button is edit-add, you would place a hidden input with the base of your URL in the form and give it a class of 'edit-add-url'. You would then add 'edit-add-url' as a class to the select widget allowing you to convert this value to the form without posting. If no URL is found, the action of the form will be used and the entire form posted to it.</p> + +<h2>Customizing the modal</h2> + +<p>If you do not wish to use the default modal, the modal can be customized by creating an array of data to define a customized modal. To do this, you add an array of info to the javascript settings to define the customizations for the modal and add an additional class to your modal link or button to tell it which modal to use.</p> + +<p>First, you need to create a settings array. You can do this most easily with a bit of PHP:</p> + +<pre>drupal_add_js(array( + 'my-modal-style' => array( + 'modalSize' => array( + 'type' => 'fixed', + 'width' => 250, + 'height' => 250, + ), + ), + ), 'setting'); +</pre> + +<p>The key to the array above (in this case, my-modal-style) is the identifier to your modal theme. You can have multiple modal themes on a page, so be sure to use an ID that will not collide with some other module's use. Using your module or theme as a prefix is a good idea.</p> + +<p>Then, when adding the ctools-use-modal class to your link or button, also add the following class: ctools-modal-ID (in the example case, that would be ctools-modal-my-modal-style).</p> + +<p>modalSize can be 'fixed' or 'scale'. If fixed it will be a raw pixel value; if 'scale' it will be a percentage of the screen.</p> + +<p>You can set:</p> + <ul> + <li> <strong>modalSize</strong>: an array of data to control the sizing of the modal. It can contain: + <ul> + <li> <strong>type</strong>: Either <em>fixed</em> or <em>scale</em>. If fixed, the modal will always be a fixed size. If <em>scale</em> the modal will scale to a percentage of the browser window. <em>Default: scale</em>. +<li> <strong>width</strong>: If </em>fixed</em> the width in pixels. If <em>scale</em> the percentage of the screen expressed as a number less than zero. (For 80 percent, use .8, for example). <em>Default: .8</em></li> +<li> <strong>height</strong>: If <em>fixed</em> the height in pixels. If <em>scale</em> the percentage of the screen expressed as a number less than zero. (For 80 percent, use .8, for example). <em>Default: .8</em></li> +<li> <strong>addWidth</strong>: Any additional width to add to the modal in pixels. Only useful if the type is scale. <em>Default: 0</em></li> +<li> <strong>addHeight</strong>: Any additional height to add to the modal in pixels. Only useful if the type is scale. <em>Default: 0</em></li> +<li> <strong>contentRight</strong>: The number of pixels to remove from the content inside the modal to make room for scroll bar and decorations. <em>Default: 25</em></li> +<li> <strong>contentBottom</strong>: The number of pixels to remove from the content inside the modal to make room for scroll bar and decorations. <em>Default: 45</em></li> +</ul> +</li> +<li> <strong>modalTheme</strong>: The Drupal javascript themable function which controls how the modal will be rendered. This function must be in the <em>Drupal.theme.prototype</em> namespace. If you set this value, you must include a corresponding function in a javascript file and use drupal_add_js() to add that file. <em>Default: CToolsModalDialog</em> +<pre> + Drupal.theme.prototype.CToolsModalDialog = function () { + var html = '' + html += ' <div id="ctools-modal">' + html += ' <div class="ctools-modal-content">' // panels-modal-content + html += ' <div class="modal-header">'; + html += ' <a class="close" href="#">'; + html += Drupal.CTools.Modal.currentSettings.closeText + Drupal.CTools.Modal.currentSettings.closeImage; + html += ' </a>'; + html += ' <span id="modal-title" class="modal-title"> </span>'; + html += ' </div>'; + html += ' <div id="modal-content" class="modal-content">'; + html += ' </div>'; + html += ' </div>'; + html += ' </div>'; + + return html; + } +</pre></li> +<li> <strong>throbberTheme</strong>: The Drupal javascript themable function which controls how the modal throbber will be rendered. This function must be in the <em>Drupal.theme.prototype</em> namespace. If you set this value, you must include a corresponding function in a javascript file and use drupal_add_js() to add that file. <em>Default: CToolsModalThrobber</em> +<pre> + Drupal.theme.prototype.CToolsModalThrobber = function () { + var html = ''; + html += ' <div id="modal-throbber">'; + html += ' <div class="modal-throbber-wrapper">'; + html += Drupal.CTools.Modal.currentSettings.throbber; + html += ' </div>'; + html += ' </div>'; + + return html; + }; +</pre> +</li> +<li> <strong>modalOptions</strong>: The options object that's sent to Drupal.CTools.Modal.modalContent. Can contain any CSS settings that will be applied to the modal backdrop, in particular settings such as <strong>opacity</strong> and <strong>background</strong>. <em>Default: array('opacity' => .55, 'background' => '#fff');</em></li> +<li> <strong>animation</strong>: Controls how the modal is animated when it is first drawn. Either <strong>show</strong>, <strong>fadeIn</strong> or <strong>slideDown</strong>. <em>Default: show</em></li> +<li> <strong>animationSpeed</strong>: The speed of the animation, expressed either as a word jQuery understands (slow, medium or fast) or a number of milliseconds for the animation to run. <em>Defaults: fast</em></li> +<li><strong>closeText</strong>: The text to display for the close button. Be sure to wrap this in t() for translatability. <em>Default: t('Close window')</em></li> +<li><strong>closeImage</strong>: The image to use for the close button of the modal. <em>Default: theme('image', array('path' => ctools_image_path('icon-close-window.png'), 'alt' => t('Close window'), 'title' => t('Close window')))</em></li> +<li><strong>loadingText</strong>: The text to display for the modal title during loading, along with the throbber. Be sure to wrap this in t() for translatability. <em>Default: t('Close window')</em></li> +<li><strong>throbber</strong>: The HTML to display for the throbber image. You can use this instead of CToolsModalThrobber theme if you just want to change the image but not the throbber HTML. <em>Default: theme('image', array('path' => ctools_image_path('throbber.gif'), 'alt' => t('Loading...'), 'title' => t('Loading')))</em></li> +</ul> + +<h2>Rendering within the modal</h2> +<p>To render your data inside the modal, you need to provide a page callback in your module that responds more or less like a normal page.</p> + +<p>In order to handle degradability, it's nice to allow your page to work both inside and outside of the modal so that users whose javascript is turned off can still use your page. There are two ways to accomplish this. First, you can embed 'nojs' as a portion of the URL and then watch to see if that turns into 'ajax' when the link is clicked. Second, if you do not wish to modify the URLs, you can check $_POST['js'] or $_POST['ctools_js'] to see if that flag was set. The URL method is the most flexible because it is easy to send the two links along completely different paths if necessary, and it is also much easier to manually test your module's output by manually visiting the nojs URL. It's actually quite difficult to do this if you have to set $_POST['js'] to test.</p> + +<p>In your hook_menu, you can use the a CTools' AJAX convenience loader to help:</p> + +<pre> + $items['ctools_ajax_sample/%ctools_js/login'] = array( + 'title' => 'Login', + 'page callback' => 'ctools_ajax_sample_login', + 'page arguments' => array(1), + 'access callback' => TRUE, + 'type' => MENU_CALLBACK, + ); +</pre> + +<p>The first argument to the page callback will be the result of ctools_js_load() which will return TRUE if 'ajax' was the string, and FALSE if anything else (i.e, nojs) is the string. Which means you can then declare your function like this:</p> + +<pre> +function ctools_ajax_sample_login($js) { + if ($js) { + // react with the modal + } + else { + // react without the modal + } +} +</pre> + +<p>If your modal does not include a form, rendering the output you wish to give the user is just a matter of calling the modal renderer with your data:</p> + +<pre> +function ctools_ajax_hello_world($js) { + $title = t('Greetings'); + $output = '<p>' . t('Hello world') . ''</p>'; + if ($js) { + ctools_modal_render($title, $output); + } + else { + drupal_set_title($title); + return $output; + } +} +</pre> + +<p>If you need to do more than just render your modal, you can use a CTools $commands array. See the function ctools_modal_render() for more information on what you need to do here.</p> + +<p>If you are displaying a form -- and the vast majority of modals display forms -- then you need to do just slightly more. Fortunately there is the ctools_modal_form_wrapper() function:</p> + +<pre> + ctools_include('modal'); + ctools_include('ajax'); + $form_state = array( + 'title' => t('Title of my form'), + 'ajax' => $js, + ); + $output = ctools_modal_form_wrapper('my_form', $form_state); + // There are some possible states after calling the form wrapper: + // 1) We are not using $js and the form has been executed. + // 2) We are using $js and the form was successfully submitted and + // we need to dismiss the modal. + // Most other states are handled automatically unless you set flags in + // $form_state to avoid handling them, so we only deal with those two + // states. + if ($form_state['executed'] && $js) { + $commands = array(); + $commands[] = ctools_modal_command_dismiss(t('Login Success')); + // In typical usage you will do something else here, such as update a + // div with HTML or redirect the page based upon the results of the modal + // form. + print ajax_render($commands); + exit; + } + + // Otherwise, just return the output. + return $output; +</pre> + +<p>You can also use CTools' form wizard inside the modal. You do not need to do much special beyond setting $form_state['modal'] = TRUE in the wizard form; it already knows how to handle the rest.</p> diff --git a/sites/all/modules/ctools/help/object-cache.html b/sites/all/modules/ctools/help/object-cache.html new file mode 100644 index 000000000..801a83672 --- /dev/null +++ b/sites/all/modules/ctools/help/object-cache.html @@ -0,0 +1,132 @@ +<p>The CTools Object Cache is a specialized cache for storing data that is non-volatile. This differs from the standard Drupal cache mechanism, which is volatile, meaning that the data can be cleared at any time and it is expected that any cached data can easily be reconstructed. In contrast, data stored in this cache is not expected to be reconstructable. It is primarily used for storing user input which is retrieved in stages, allowing for more complex user interface interactions.</p> + +<p>The object cache consists of 3 normal functions for cache maintenance, and 2 additional functions to facilitate locking.</p> + +<p>To use any of these functions, you must first use ctools_include:</p> + +<pre> +ctools_include('object-cache'); +</pre> + +<pre> +/** + * Get an object from the non-volatile ctools cache. + * + * This function caches in memory as well, so that multiple calls to this + * will not result in multiple database reads. + * + * @param $obj + * A 128 character or less string to define what kind of object is being + * stored; primarily this is used to prevent collisions. + * @param $name + * The name of the object being stored. + * @param $skip_cache + * Skip the memory cache, meaning this must be read from the db again. + * + * @return + * The data that was cached. + */ +function ctools_object_cache_get($obj, $name, $skip_cache = FALSE) { +</pre> + +<pre> +/** + * Store an object in the non-volatile ctools cache. + * + * @param $obj + * A 128 character or less string to define what kind of object is being + * stored; primarily this is used to prevent collisions. + * @param $name + * The name of the object being stored. + * @param $cache + * The object to be cached. This will be serialized prior to writing. + */ +function ctools_object_cache_set($obj, $name, $cache) { +</pre> + +<pre> +/** + * Remove an object from the non-volatile ctools cache + * + * @param $obj + * A 128 character or less string to define what kind of object is being + * stored; primarily this is used to prevent collisions. + * @param $name + * The name of the object being removed. + */ +function ctools_object_cache_clear($obj, $name) { +</pre> + +<p>To facilitate locking, which is the ability to prohibit updates by other users while one user has an object cached, this system provides two functions:</p> + +<pre> +/** + * Determine if another user has a given object cached. + * + * This is very useful for 'locking' objects so that only one user can + * modify them. + * + * @param $obj + * A 128 character or less string to define what kind of object is being + * stored; primarily this is used to prevent collisions. + * @param $name + * The name of the object being removed. + * + * @return + * An object containing the UID and updated date if found; NULL if not. + */ +function ctools_object_cache_test($obj, $name) { +</pre> + +<p>The object returned by ctools_object_cache_test can be directly used to determine whether a user should be allowed to cache their own version of an object.</p> + +<p>To allow the concept of breaking a lock, that is, clearing another users changes:</p> + +<pre> +/** + * Remove an object from the non-volatile ctools cache for all session IDs. + * + * This is useful for clearing a lock. + * + * @param $obj + * A 128 character or less string to define what kind of object is being + * stored; primarily this is used to prevent collisions. + * @param $name + * The name of the object being removed. + */ +function ctools_object_cache_clear_all($obj, $name) { +</pre> + +<p>Typical best practice is to use wrapper functions such as these:</p> + +<pre> +/** + * Get the cached changes to a given task handler. + */ +function delegator_page_get_page_cache($name) { + ctools_include('object-cache'); + $cache = ctools_object_cache_get('delegator_page', $name); + if (!$cache) { + $cache = delegator_page_load($name); + $cache->locked = ctools_object_cache_test('delegator_page', $name); + } + + return $cache; +} + +/** + * Store changes to a task handler in the object cache. + */ +function delegator_page_set_page_cache($name, $page) { + ctools_include('object-cache'); + $cache = ctools_object_cache_set('delegator_page', $name, $page); +} + +/** + * Remove an item from the object cache. + */ +function delegator_page_clear_page_cache($name) { + ctools_include('object-cache'); + ctools_object_cache_clear('delegator_page', $name); +} +</pre> diff --git a/sites/all/modules/ctools/help/plugins-api.html b/sites/all/modules/ctools/help/plugins-api.html new file mode 100644 index 000000000..548f17b51 --- /dev/null +++ b/sites/all/modules/ctools/help/plugins-api.html @@ -0,0 +1,55 @@ +<p>APIs are a form of plugins that are tightly associated with a module. Instead of a module providing any number of plugins, each module provides only one file for an API and this file can contain hooks that the module should invoke.</p> + +<p>Modules support this API by implementing hook_ctools_plugin_api($module, $api). If they support the API, they return a packet of data:</p> + +<pre> +function mymodule_ctools_plugin_api($module, $api) { + if ($module == 'some module' && $api = 'some api') { + return array( + 'version' => The minimum API version this system supports. If this API version is incompatible then the .inc file will not be loaded. + 'path' => Where to find the file. Optional; if not specified it will be the module's directory. + 'file' => an alternative version of the filename. If not specified it will be $module.$api.inc + ); + } +} +</pre> + +<p>This implementation must be in the .module file.</p> + +<p>Modules utilizing this can invole ctools_plugin_api_include() in order to ensure all modules that support the API will have their files loaded as necessary. It's usually easiest to create a small helper function like this:</p> + +<pre> +define('MYMODULE_MINIMUM_VERSION', 1); +define('MYMODULE_VERSION', 1); + +function mymodule_include_api() { + ctools_include('plugins'); + return ctools_plugin_api_include('mymodule', 'myapi', MYMODULE_MINIMUM_VERSION, MYMODULE_VERSION); +} +</pre> + +<p>Using a define will ensure your use of version numbers is consistent and easy to update when you make API changes. You can then use the usual module_invoke type commands:</p> + +<pre> +mymodule_include_api(); +module_invoke('myhook', $data); +</pre> + +<p>If you need to pass references, this construct is standard:</p> + +<pre> +foreach (mymodule_include_api() as $module => $info) { + $function = $module . '_hookname'; + // Just because they implement the API and include a file does not guarantee they implemented + // a hook function! + if (!function_exists($function)) { + continue; + } + + // Typically array_merge() is used below if data is returned. + $result = $function($data1, $data2, $data3); +} +</pre> + +<p>TODO: There needs to be a way to check API version without including anything, as a module may simply +provide normal plugins and versioning could still matter.</p> diff --git a/sites/all/modules/ctools/help/plugins-creating.html b/sites/all/modules/ctools/help/plugins-creating.html new file mode 100644 index 000000000..23237058e --- /dev/null +++ b/sites/all/modules/ctools/help/plugins-creating.html @@ -0,0 +1,203 @@ +There are two primary pieces to using plugins. The first is getting the data, and the second is using the data. + +<h2>Defining a plugin</h2> +To define that you offer a plugin that modules can implement, you first must implement hook_ctools_plugin_type() to tell the plugin system about your plugin. + +<pre> +/** + * Implements hook_ctools_plugin_type() to inform CTools about the layout plugin. + */ +function panels_ctools_plugin_type() { + $plugins['layouts'] = array( + 'load themes' => TRUE, + ); + + return $plugins; +} +</pre> + +The following information can be specified for each plugin type: +<dl> +<dt>cache</dt> +<dd><em>Defaults to:</em> <strong>FALSE</strong></dd> +<dd>If set to TRUE, the results of ctools_get_plugins will be cached in the 'cache' table (by default), thus preventing .inc files from being loaded. ctools_get_plugins looking for a specific plugin will always load the appropriate .inc file.</dd> +<dt>cache table</dt> +<dd><em>Defaults to:</em> <strong>'cache'</strong></dd> +<dd>If 'cache' is TRUE, then this value specifies the cache table where the cached plugin information will be stored.</dd> +<dt>classes</dt> +<dd><em>Defaults to:</em> <strong>array()</strong></dd> +<dd>An array of <em>class identifiers</em>(i.e. plugin array keys) which a plugin of this type uses to provide classes to the CTools autoloader. For example, if <strong>classes</strong> is set to array('class'), then CTools will search each <strong>$plugin['class']</strong> for a class to autoload. Depending of the plugin structure, a <em>class identifier</em> may be either:</dd> +<dl> +<dt>- a file name:</dt> +<dd>the file which holds the class with the name structure as: <em>[filename].[class].php</em></dd> +<dd>in this case the class name can be different than the <em>class identifier</em></dd> +<dt>- the class name:</dt> +<dd>if the class is in the same file as the $plugin</dd> +<dd>the plugin <em>.inc</em> file can have a different name than the <em>class identifier</em></dd> +</dl> +<dt>defaults</dt> +<dd><em>Defaults to:</em> <strong>array()</strong></dd> +<dd>An array of defaults that should be added to each plugin; this can be used to ensure that every plugin has the basic data necessary. These defaults will not ovewrite data supplied by the plugin. This could also be a function name, in which case the callback will be used to provide defaults. NOTE, however, that the callback-based approach is deprecated as it is redundant with the 'process' callback, and as such will be removed in later versions. Consequently, you should only use the array form for maximum cross-version compatibility.</dd> +<dt>load themes</dt> +<dd><em>Defaults to:</em> <strong>FALSE</strong></dd> +<dd>If set to TRUE, then plugins of this type can be supplied by themes as well as modules. If this is the case, all themes that are currently enabled will provide a plugin: NOTE: Due to a slight UI bug in Drupal, it is possible for the default theme to be active but not enabled. If this is the case, that theme will NOT provide plugins, so if you are using this feature, be sure to document that issue. Also, themes set via $custom_theme do not necessarily need to be enabled, but the system has no way of knowing what those themes are, so the enabled flag is the only true method of identifying which themes can provide layouts.</dd> +<dt>hook</dt> +<dd><em>Defaults to:</em> (dynamic value)</dd> +<dd>The name of the hook used to collect data for this plugin. Normally this is <strong>$module . '_' . $type</strong> -- but this can be changed here. If you change this, you MUST be sure to document this for your plugin implementors as it will change the format of the specially named hook. +<dt>process</dt> +<dd><em>Defaults to:</em> <strong>''</strong></dd> +<dd>An optional function callback to use for processing a plugin. This can be used to provide automated settings that must be calculated per-plugin instance (i.e., it is not enough to simply append an array via 'defaults'). The parameters on this callback are: <strong>callback(&$plugin, $info)</strong> where $plugin is a reference to the plugin as processed and $info is the fully processed result of hook_ctools_plugin_api_info(). +<dt>extension</dt> +<dd><em>Defaults to:</em> <strong>'inc'</strong></dd> +<dd>Can be used to change the extension on files containing plugins of this type. By default the extension will be "inc", though it will default to "info" if "info files" is set to true. Do not include the dot in the extension if changing it, that will be added automatically.</dd> +<dt>info file</dt> +<dd><em>Defaults to:</em> <strong>FALSE</strong></dd> +<dd>If set to TRUE, then the plugin will look for a .info file instead of a .inc. Internally, this will look exactly the same, though obviously a .info file cannot contain functions. This can be good for styles that may not need to contain code.</dd> +<dt>use hooks</dt> +<dd><em>Defaults to:</em> <strong>TRUE</strong>*</dd> +<dd>Use to enable support for plugin definition hooks instead of plugin definition files. NOTE: using a central plugin definition hook is less optimal for the plugins system, and as such this will default to FALSE in later versions.</dd> +<dt>child plugins</dt> +<dd><em>Defaults to:</em> <strong>FALSE</strong></dd> +<dd>If set to TRUE, the plugin type can automatically have 'child plugins' meaning each plugin can actually provide multiple plugins. This is mostly used for plugins that store some of their information in the database, such as views, blocks or exportable custom versions of plugins.</dd> +<dd>To implement, each plugin can have a 'get child' and 'get children' callback. Both of these should be implemented for performance reasons, since it is best to avoid getting all children if necessary, but if 'get child' is not implemented, it will fall back to 'get children' if it has to.</dd> +<dd>Child plugins should be named parent:child, with the : being the separator, so that it knows which parent plugin to ask for the child. The 'get children' method should at least return the parent plugin as part of the list, unless it wants the parent plugin itself to not be a choosable option, which is not unheard of. </dd> +<dd>'get children' arguments are ($plugin, $parent) and 'get child' arguments are ($plugin, $parent, $child). +</dl> + +In addition, there is a 'module' and 'type' settings; these are for internal use of the plugin system and you should not change these. +<h2>Getting the data</h2> +To create a plugin, a module only has to execute ctools_get_plugins with the right data: + +<pre> + ctools_include('plugins'); + ctools_get_plugins($module, $type, [$id]) +</pre> + +In the above example, $module should be your module's name and $type is the type of the plugin. It is typically best practice to provide some kind of wrapper function to make this easier. For example, Panels provides the following functions to implement the 'content_types' plugin: + +<pre> +/** + * Fetch metadata on a specific content_type plugin. + * + * @param $content type + * Name of a panel content type. + * + * @return + * An array with information about the requested panel content type. + */ +function panels_get_content_type($content_type) { + ctools_include('context'); + ctools_include('plugins'); + return ctools_get_plugins('panels', 'content_types', $content_type); +} + +/** + * Fetch metadata for all content_type plugins. + * + * @return + * An array of arrays with information about all available panel content types. + */ +function panels_get_content_types() { + ctools_include('context'); + ctools_include('plugins'); + return ctools_get_plugins('panels', 'content_types'); +} +</pre> + +<h2>Using the data</h2> + +Each plugin returns a packet of data, which is added to with a few defaults. Each plugin is guaranteed to always have the following data: +<dl> +<dt>name</dt> +<dd>The name of the plugin. This is also the key in the array, of the full list of plugins, and is placed here since that is not always available.</dd> +<dt>module</dt> +<dd>The module that supplied the plugin.</dd> +<dt>file</dt> +<dd>The actual file containing the plugin.</dd> +<dt>path</dt> +<dd>The path to the file containing the plugin. This is useful for using secondary files, such as templates, css files, images, etc, that may come with a plugin.</dd> +</dl> + +<p>Any of the above items can be overridden by the plugin itself, though the most likely one to be modified is the 'path'.</p> + +<p>The most likely data (beyond simple printable data) for a plugin to provide is a callback. The plugin system provides a pair of functions to make it easy and consistent for these callbacks to be used. The first is ctools_plugin_get_function, which requires the full $plugin object.</p> + +<pre> +/** + * Get a function from a plugin, if it exists. If the plugin is not already + * loaded, try ctools_plugin_load_function() instead. + * + * @param $plugin + * The loaded plugin type. + * @param $callback_name + * The identifier of the function. For example, 'settings form'. + * + * @return + * The actual name of the function to call, or NULL if the function + * does not exist. + */ +function ctools_plugin_get_function($plugin, $callback_name) +</pre> + +<p>The second does not require the full $plugin object, and will load it:</p> + +<pre> +/** + * Load a plugin and get a function name from it, returning success only + * if the function exists. + * + * @param $module + * The module that owns the plugin type. + * @param $type + * The type of plugin. + * @param $id + * The id of the specific plugin to load. + * @param $callback_name + * The identifier of the function. For example, 'settings form'. + * + * @return + * The actual name of the function to call, or NULL if the function + * does not exist. + */ +function ctools_plugin_load_function($module, $type, $id, $callback_name) { +</pre> + +<p>Both of these functions will ensure any needed files are included. In fact, it allows each callback to specify alternative include files. The plugin implementation could include code like this:</p> + +<pre> + 'callback_name' => 'actual_name_of_function_here', +</pre> + +<p>Or like this:</p> +<pre> + 'callback_name' => array( + 'file' => 'filename', + 'path' => 'filepath', // optional, will use plugin path if absent + 'function' => 'actual_name_of_function_here', + ), +</pre> + +<p>An example, for 'plugin_example' type</p> + +<pre> +$plugin = array( + 'name' => 'my_plugin', + 'module' => 'my_module', + 'example_callback' => array( + 'file' => 'my_plugin.extrafile.inc', + 'function' => 'my_module_my_plugin_example_callback', + ), +); +</pre> + +<p>To utilize this callback on this plugin:</p> + +<pre> +if ($function = ctools_plugin_get_function($plugin, 'example_callback')) { + $function($arg1, $arg2, $etc); +} +</pre> + +<h2>Document your plugins!</h2> + +<p>Since the data provided by your plugin tends to be specific to your plugin type, you really need to document what the data returned in the hook in the .inc file will be or nobody will figure it out. Use advanced help and document it there. If every system that utilizes plugins does this, then plugin implementors will quickly learn to expect the documentation to be in the advanced help.</p> diff --git a/sites/all/modules/ctools/help/plugins-implementing.html b/sites/all/modules/ctools/help/plugins-implementing.html new file mode 100644 index 000000000..c95e72d42 --- /dev/null +++ b/sites/all/modules/ctools/help/plugins-implementing.html @@ -0,0 +1,62 @@ +<p>There are two parts to implementing a plugin: telling the system where it is, and implementing one or more .inc files that contain the plugin data.</p> + +<h2>Telling the system where your plugins live</h2> +<h3>How a module implements plugins</h3> +<p>To implement any plugins at all, you must implement a single function for all plugins: <strong>hook_ctools_plugin_directory</strong>. Every time a module loads plugins, this hook will be called to see which modules implement those plugins and in what directory those plugins will live.</p> + +<pre> +function hook_ctools_plugin_directory($module, $plugin) { + if ($module == 'panels' && $plugin == 'content_types') { + return 'plugins/content_types'; + } +} +</pre> + +<p>The directory returned should be relative to your module. Another common usage is to simply return that you implement all plugins owned by a given module (or modules):</p> + +<pre> +function hook_ctools_plugin_directory($module, $plugin) { + if ($module == 'panels') { + return 'plugins/' . $plugin; + } +} +</pre> + +<p>Typically, it is recommended that all plugins be placed into the 'plugins' directory for clarity and maintainability. Inside the directory, any number of subdirectories can be used. For plugins that require extra files, such as templates, css, javascript or image files, this is highly recommended:</p> +<pre> +mymodule.module +mymodule.info +plugins/ + content_types/ + my_content_type.inc + layouts/ + my_layout.inc + my_layout.css + my_layout.tpl.php + my_layout_image.png +</pre> + +<h3>How a theme implements plugins</h3> +<p>Themes can implement plugins if the plugin owner specified that it's possible in its hook_ctools_plugin_type() call. If so, it is generally exactly the same as modules, except for one important difference: themes don't get hook_ctools_plugin_directory(). Instead, themes add a line to their .info file:</p> + +<pre> +plugins[module][type] = directory +</pre> + +<h2>How to structure the .inc file</h2> + +<p>The top of the .inc file should contain an array that defines the plugin. This array is simply defined in the global namespace of the file and does not need a function. Note that previous versions of this plugin system required a specially named function. While this function will still work, its use is now discouraged, as it is annoying to name properly.</p> + +<p>This array should look something like this:</p> + +<pre> +$plugin = array( + 'key' => 'value', +); +</pre> + +<p>Several values will be filled in for you automatically, but you can override them if necessary. They include 'name', 'path', 'file' and 'module'. Additionally, the plugin owner can provide other defaults as well.</p> + +<p>There are no required keys by the plugin system itself. The only requirements in the $plugin array will be defined by the plugin type.</p> + +<p>After this array, if your plugin needs functions, they can be declared. Different plugin types have different needs here, so exactly what else will be needed will change from type to type.</p> diff --git a/sites/all/modules/ctools/help/plugins.html b/sites/all/modules/ctools/help/plugins.html new file mode 100644 index 000000000..1e64da095 --- /dev/null +++ b/sites/all/modules/ctools/help/plugins.html @@ -0,0 +1,5 @@ +<p>The plugins tool allows a module to allow <b>other</b> modules (and themes!) to provide plugins which provide some kind of functionality or some kind of task. For example, in Panels there are several types of plugins: Content types (which are like blocks), layouts (which are page layouts) and styles (which can be used to style a panel). Each plugin is represented by a .inc file, and the functionality they offer can differ wildly.</p> + +<p>A module which uses plugins can implement a hook describing the plugin (which is not necessary, as defaults will be filled in) and then calls a ctools function which loads either all the known plugins (used for listing/choosing) or a specific plugin (used when it's known which plugin is needed). From the perspective of the plugin system, a plugin is a packet of data, usually some printable info and a list of callbacks. It is up to the module implementing plugins to determine what that info means and what the callbacks do.</p> + +<p>A module which implements plugins must first implement the <strong>hook_ctools_plugin_directory</strong> function, which simply tells the system which plugins are supported and what directory to look in. Each plugin will then be in a separate .inc file in the directory supplied. The .inc file will contain a specially named hook which returns the data necessary to implement the plugin.</p> diff --git a/sites/all/modules/ctools/help/wizard.html b/sites/all/modules/ctools/help/wizard.html new file mode 100644 index 000000000..33fc45622 --- /dev/null +++ b/sites/all/modules/ctools/help/wizard.html @@ -0,0 +1,311 @@ +<p>Form wizards, or multi-step forms, are a process by which the user goes through or can use an arbitrary number of different forms to create a single object or perform a single task. Traditionally the multi-step form is difficult in Drupal because there is no easy place to put data in between forms. No longer! The form wizard tool allows a single entry point to easily set up a wizard of multiple forms, provide callbacks to handle data storage and updates between forms and when forms are completed. This tool pairs well with the <a href="&topic:ctools/object-cache&">object cache</a> tool for storage.</p> + +<h2>The form info array</h2> +<p>The wizard starts with an array of data that describes all of the forms available to the wizard and sets options for how the wizard will present and control the flow. Here is an example of the $form_info array as used in the delegator module:</p> + +<pre> + $form_info = array( + 'id' => 'delegator_page', + 'path' => "admin/structure/pages/edit/$page_name/%step", + 'show trail' => TRUE, + 'show back' => TRUE, + 'show return' => FALSE, + 'next callback' => 'delegator_page_add_subtask_next', + 'finish callback' => 'delegator_page_add_subtask_finish', + 'return callback' => 'delegator_page_add_subtask_finish', + 'cancel callback' => 'delegator_page_add_subtask_cancel', + 'order' => array( + 'basic' => t('Basic settings'), + 'argument' => t('Argument settings'), + 'access' => t('Access control'), + 'menu' => t('Menu settings'), + 'multiple' => t('Task handlers'), + ), + 'forms' => array( + 'basic' => array( + 'form id' => 'delegator_page_form_basic' + ), + 'access' => array( + 'form id' => 'delegator_page_form_access' + ), + 'menu' => array( + 'form id' => 'delegator_page_form_menu' + ), + 'argument' => array( + 'form id' => 'delegator_page_form_argument' + ), + 'multiple' => array( + 'form id' => 'delegator_page_argument_form_multiple' + ), + ), + ); +</pre> + +<p>The above array starts with an <strong>id</strong> which is used to identify the wizard in various places and a <strong>path</strong> which is needed to redirect to the next step between forms. It then creates some <strong>settings</strong> which control which pieces are displayed. In this case, it displays a form trail and a 'back' button, but not the 'return' button. Then there are the <strong>wizard callbacks</strong> which allow the wizard to act appropriately when forms are submitted. Finally it contains a <strong>list of forms</strong> and their <strong>order</strong> so that it knows which forms to use and what order to use them by default. Note that the keys in the order and list of forms match; that key is called the <strong>step</strong> and is used to identify each individual step of the wizard.</p> + +<p>Here is a full list of every item that can be in the form info array:</p> + +<dl> +<dt>id</dt> +<dd>An id for wizard. This is used like a hook to automatically name <strong>callbacks</strong>, as well as a form step's form building function. It is also used in trail theming.</dd> + +<dt>path</dt> +<dd>The path to use when redirecting between forms. <strong>%step</strong> will be replaced with the key for the form.</dd> + +<dt>return path</dt> +<dd>When a form is complete, this is the path to go to. This is required if the 'return' button is shown and not using AJAX. It is also used for the 'Finish' button. If it is not present and needed, the cancel path will also be checked.</dd> + +<dt>cancel path</dt> +<dd>When a form is canceled, this is the path to go to. This is required if the 'cancel' is shown and not using AJAX.</dd> + +<dt>show trail</dt> +<dd>If set to TRUE, the form trail will be shown like a breadcrumb at the top of each form. Defaults to FALSE.</dd> + +<dt>show back</dt> +<dd>If set to TRUE, show a back button on each form. Defaults to FALSE.</dd> + +<dt>show return</dt> +<dd>If set to TRUE, show a return button. Defaults to FALSE.</dd> + +<dt>show cancel</dt> +<dd>If set to TRUE, show a cancel button. Defaults to FALSE.</dd> + +<dt>back text</dt> +<dd>Set the text of the 'back' button. Defaults to t('Back').</dd> + +<dt>next text</dt> +<dd>Set the text of the 'next' button. Defaults to t('Continue').</dd> + +<dt>return text</dt> +<dd>Set the text of the 'return' button. Defaults to t('Update and return').</dd> + +<dt>finish text</dt> +<dd>Set the text of the 'finish' button. Defaults to t('Finish').</dd> + +<dt>cancel text</dt> +<dd>Set the text of the 'cancel' button. Defaults to t('Cancel').</dd> + +<dt>ajax</dt> +<dd>Turn on AJAX capabilities, using CTools' ajax.inc. Defaults to FALSE.</dd> + +<dt>modal</dt> +<dd>Put the wizard in the modal tool. The modal must already be open and called from an ajax button for this to work, which is easily accomplished using functions provided by the modal tool.</dd> + +<dt>ajax render</dt> +<dd>A callback to display the rendered form via ajax. This is not required if using the modal tool, but is required otherwise since ajax by itself does not know how to render the results. Params: &$form_state, $output.</dd> + +<dt>finish callback</dt> +<dd>The function to call when a form is complete and the finish button has been clicked. This function should finalize all data. Params: &$form_state. +Defaults to $form_info['id']._finish if function exists. +</dd> + +<dt>cancel callback</dt> +<dd>The function to call when a form is canceled by the user. This function should clean up any data that is cached. Params: &$form_state. +Defaults to $form_info['id']._cancel if function exists.</dd> + +<dt>return callback</dt> +<dd>The function to call when a form is complete and the return button has been clicked. This is often the same as the finish callback. Params: &$form_state. +Defaults to $form_info['id']._return if function exists.</dd> + +<dt>next callback</dt> +<dd>The function to call when the next button has been clicked. This function should take the submitted data and cache it for later use by the finish callback. Params: &$form_state. +Defaults to $form_info['id']._next if function exists.</dd> + +<dt>order</dt> +<dd>An optional array of forms, keyed by the step, which represents the default order the forms will be displayed in. If not set, the forms array will control the order. Note that submit callbacks can override the order so that branching logic can be used.</dd> + +<dt>forms</dt> +<dd>An array of form info arrays, keyed by step, describing every form available to the wizard. If order array isn't set, the wizard will use this to set the default order. Each array contains: + <dl> + <dt>form id</dt> + <dd> + The id of the form, as used in the Drupal form system. This is also the name of the function that represents the form builder. + Defaults to $form_info['id']._.$step._form. + </dd> + + <dt>include</dt> + <dd>The name of a file to include which contains the code for this form. This makes it easy to include the form wizard in another file or set of files. This must be the full path of the file, so be sure to use drupal_get_path() when setting this. This can also be an array of files if multiple files need to be included.</dd> + + <dt>title</dt> + <dd>The title of the form, to be optionally set via drupal_get_title. This is required when using the modal if $form_state['title'] is not set.</dd> + </dl> +</dd> +</dl> + +<h2>Invoking the form wizard</h2> +<p>Your module should create a page callback via hook_menu, and this callback should contain an argument for the step. The path that leads to this page callback should be the same as the 'path' set in the $form_info array.</p> + +<p>The page callback should set up the $form_info, and figure out what the default step should be if no step is provided (note that the wizard does not do this for you; you MUST specify a step). Then invoke the form wizard:</p> + +<pre> + $form_state = array(); + ctools_include('wizard'); + $output = ctools_wizard_multistep_form($form_info, $step, $form_state); +</pre> + +<p>If using AJAX or the modal, This part is actually done! If not, you have one more small step:</p> + +<pre> + return $output; +</pre> + +<h2>Forms and their callbacks</h2> +<p>Each form within the wizard is a complete, independent form using Drupal's Form API system. It has a form builder callback as well as submit and validate callbacks and can be form altered. The primary difference between these forms and a normal Drupal form is that the submit handler should not save any data. Instead, it should make any changes to a cached object (usually placed on the $form_state) and only the _finish or _return handler should actually save any real data.</p> + +<p>How you handle this is completely up to you. The recommended best practice is to use the CTools Object cache, and a good way to do this is to write a couple of wrapper functions around the cache that look like these example functions:</p> + +<pre> +/** + * Get the cached changes to a given task handler. + */ +function delegator_page_get_page_cache($name) { + ctools_include('object-cache'); + $cache = ctools_object_cache_get('delegator_page', $name); + if (!$cache) { + $cache = delegator_page_load($name); + $cache->locked = ctools_object_cache_test('delegator_page', $name); + } + + return $cache; +} + +/** + * Store changes to a task handler in the object cache. + */ +function delegator_page_set_page_cache($name, $page) { + ctools_include('object-cache'); + $cache = ctools_object_cache_set('delegator_page', $name, $page); +} + +/** + * Remove an item from the object cache. + */ +function delegator_page_clear_page_cache($name) { + ctools_include('object-cache'); + ctools_object_cache_clear('delegator_page', $name); +} +</pre> + +<p>Using these wrappers, when performing a get_cache operation, it defaults to loading the real object. It then checks to see if another user has this object cached using the ctools_object_cache_test() function, which automatically sets a lock (which can be used to prevent writes later on).</p> + +<p>With this set up, the _next, _finish and _cancel callbacks are quite simple:</p> + +<pre> +/** + * Callback generated when the add page process is finished. + */ +function delegator_page_add_subtask_finish(&$form_state) { + $page = &$form_state['page']; + + // Create a real object from the cache + delegator_page_save($page); + + // Clear the cache + delegator_page_clear_page_cache($form_state['cache name']); +} + +/** + * Callback generated when the 'next' button is clicked. + * + * All we do here is store the cache. + */ +function delegator_page_add_subtask_next(&$form_state) { + // Update the cache with changes. + delegator_page_set_page_cache($form_state['cache name'], $form_state['page']); +} + +/** + * Callback generated when the 'cancel' button is clicked. + * + * All we do here is clear the cache. + */ +function delegator_page_add_subtask_cancel(&$form_state) { + // Update the cache with changes. + delegator_page_clear_page_cache($form_state['cache name']); +} +</pre> + +<p>All that's needed to tie this together is to understand how the changes made it into the cache in the first place. This happened in the various form _submit handlers, which made changes to $form_state['page'] based upon the values set in the form:</p> + +<pre> +/** + * Store the values from the basic settings form. + */ +function delegator_page_form_basic_submit($form, &$form_state) { + if (!isset($form_state['page']->pid) && empty($form_state['page']->import)) { + $form_state['page']->name = $form_state['values']['name']; + } + + $form_state['page']->admin_title = $form_state['values']['admin_title']; + $form_state['page']->path = $form_state['values']['path']; + + return $form; +} +</pre> + +<p>No database operations were made during this _submit, and that's a very important distinction about this system.</p> + +<h3>Proper handling of back button</h3> +<p>When using <strong>'show back' => TRUE</strong> the cached data should be assigned to the <em>#default_value</em> form property. Otherwise when the user goes back to the previous step the forms default values instead of his (cached) input is used.</p> + +<pre> +/** + * Form builder function for wizard. + */ +function wizardid_step2_form($form, &$form_state) { + $form_state['my data'] = my_module_get_cache($form_state['cache name']); + $form['example'] = array( + '#type' => 'radios', + '#title' => t('Title'), + '#default_value' => $form_state['my data']->example ? $form_state['my data']->example : default, + '#options' => array( + 'default' => t('Default'), + 'setting1' => t('Setting1'), + ), + ); + + return $form; +} + +/** + * Submit handler to prepare needed values for storing in cache. + */ +function wizardid_step2_form_submit($form, &$form_state) { + $form_state['my data']->example = $form_state['values']['example']; +} +</pre> + +<p>The data is stored in the <em>my data</em> object on submitting. If the user goes back to this step the cached <em>my data</em> is used as the default form value. The function <em>my_module_get_cache()</em> is like the cache functions explained above.</p> + +<h2>Required fields, cancel and back buttons</h2> +<p>If you have required fields in your forms, the back and cancel buttons will not work as expected since validation of the form will fail. You can add the following code to the top of your form validation to avoid this problem:</p> +<pre> +/** + * Validation handler for step2 form + */ +function wizardid_step2_form_validate(&$form, &$form_state) { + // if the clicked button is anything but the normal flow + if ($form_state['clicked_button']['#next'] != $form_state['next']) { + drupal_get_messages('error'); + form_set_error(NULL, '', TRUE); + return; + } + // you form validation goes here + // ... +} +</pre> + +<h2>Wizard for anonymous users</h2> +<p>If you are creating a wizard which is be used by anonymous users, you might run into some issues with drupal's caching for anonymous users. You can circumvent this by using hook_init and telling drupal to not cache your wizard pages:</p> +<pre> +/** + * Implementation of hook init + */ +function mymodule_init() { + // if the path leads to the wizard + if (drupal_match_path($_GET['q'], 'path/to/your/wizard/*')) { + // set cache to false + $GLOBALS['conf']['cache'] = FALSE; + } +} +</pre> |