[Summary view] [Print] [Text view]

   1  <!-- $Id: context-content.html,v 1.3 2009/07/18 22:06:33 merlinofchaos Exp $ -->
   2  <p>The CTools pluggable content system provides various pieces of
   3  content as discrete bits of data that can be added to other
   4  applications, such as Panels or Dashboard via the UI. Whatever the
   5  content is added to stores the configuration for that individual piece
   6  of content, and provides this to the content.</p>
   7  
   8  <p>Each content type plugin will be contained in a .inc file, with
   9  subsidiary files, if necessary, in or near the same directory. Each
  10  content type consists of some information and one or more subtypes,
  11  which all use the same renderer. Subtypes are considered to be
  12  instances of the type. For example, the 'views' content type would have
  13  each view in the system as a subtype. Many content types will have
  14  exactly one subtype.</p>
  15  
  16  <p>Because the content and forms can be provided via ajax, the plugin
  17  also provides a list of CSS and JavaScript information that should be available
  18  on whatever page the content or forms may be AJAXed onto.</p>
  19  
  20  <p>For the purposes of selecting content from the UI, each content
  21  subtype will have the following information:</p>
  22  
  23  <ul>
  24    <li>A title</li>
  25  
  26    <li>A short description</li>
  27  
  28    <li>A category [Do we want to add hierarchy categories? Do we want
  29    category to be more than just a string?]</li>
  30  
  31    <li>An icon [do we want multiple icons? This becomes a hefty
  32    requirement]</li>
  33  </ul>
  34  
  35  <p>Each piece of content provides one or more configuration forms, if
  36  necessary, and the system that includes the content will handle the
  37  data storage. These forms can be provided in sequence as wizards or as
  38  extra forms that can be accessed through advanced administration.</p>
  39  
  40  <p>The plugin for a content type should contain:</p>
  41  
  42  <dl>
  43    <dt>title</dt>
  44  
  45    <dd>For use on the content permissions screen.</dd>
  46  
  47    <dt>content types</dt>
  48  
  49    <dd>Either an array of content type definitions, or a callback that
  50    will return content type definitions. This callback will get the
  51    plugin definition as an argument.</dd>
  52  
  53    <dt>content type</dt>
  54  
  55    <dd>[Optional] Provide a single content type definition. This is only
  56    necessary if content types might be intensive.</dd>
  57  
  58    <dt>render callback</dt>
  59  
  60    <dd>
  61      The callback to render the content. Parameters:
  62  
  63      <dl>
  64        <dt>$subtype</dt>
  65  
  66        <dd>The name of the subtype being rendered. NOT the loaded
  67        subtype data.</dd>
  68  
  69        <dt>$conf</dt>
  70  
  71        <dd>The stored configuration for the content.</dd>
  72  
  73        <dt>$args</dt>
  74  
  75        <dd>Any arguments passed.</dd>
  76  
  77        <dt>$context</dt>
  78  
  79        <dd>An array of contexts requested by the required contexts and
  80        assigned by the configuration step.</dd>
  81  
  82        <dt>$incoming_content</dt>
  83  
  84        <dd>Any 'incoming content' if this is a wrapper.</dd>
  85      </dl>
  86    </dd>
  87  
  88    <dt>admin title</dt>
  89  
  90    <dd>A callback to provide the administrative title. If it is not a
  91    function, then it will be counted as a string to use as the admin
  92    title.</dd>
  93  
  94    <dt>admin info</dt>
  95  
  96    <dd>A callback to provide administrative information about the
  97    content, to be displayed when manipulating the content. It should
  98    contain a summary of configuration.</dd>
  99  
 100    <dt>edit form</dt>
 101  
 102    <dd>
 103      Either a single form ID or an array of forms *keyed* by form ID
 104      with the value to be used as the title of the form. %title me be
 105      used as a placeholder for the administrative title if necessary.
 106      Example:
 107      <pre>
 108    array(
 109      'ctools_example_content_form_second' =&gt; t('Configure first form'),
 110      'ctools_example_content_form_first' =&gt; t('Configure second form'),
 111    ),
 112  </pre>The first form will always have required configuration added to
 113  it. These forms are normal FAPI forms, but you do not need to provide
 114  buttons, these will be added by the form wizard.
 115    </dd>
 116  
 117    <dt>add form</dt>
 118  
 119    <dd>[Optional] If different from the edit forms, provide them here in
 120    the same manner. Also may be set to FALSE to not have an add
 121    form.</dd>
 122  
 123    <dt>css</dt>
 124  
 125    <dd>A file or array of CSS files that are necessary for the
 126    content.</dd>
 127  
 128    <dt>js</dt>
 129  
 130    <dd>A file or array of javascript files that are necessary for the
 131    content to be displayed.</dd>
 132  
 133    <dt>admin css</dt>
 134  
 135    <dd>A file or array of CSS files that are necessary for the
 136    forms.</dd>
 137  
 138    <dt>admin js</dt>
 139  
 140    <dd>A file or array of JavaScript files that are necessary for the
 141    forms.</dd>
 142  
 143    <dt>extra forms</dt>
 144  
 145    <dd>An array of form information to handle extra administrative
 146    forms.</dd>
 147  
 148    <dt>no title override</dt>
 149  
 150    <dd>Set to TRUE if the title cannot be overridden.</dd>
 151  
 152    <dt>single</dt>
 153  
 154    <dd>Set to TRUE if this content provides exactly one subtype.</dd>
 155  
 156    <dt>render last</dt>
 157  
 158    <dd>Set to true if for some reason this content needs to render after
 159    other content. This is primarily used for forms to ensure that render
 160    order is correct.</dd>
 161  </dl>
 162  
 163  <p>TODO: many of the above callbacks can be assumed based upon
 164  patterns: modulename + '_' + name + '_' + function. i.e, render,
 165  admin_title, admin_info, etc.</p>
 166  
 167  <p>TODO: Some kind of simple access control to easily filter out
 168  content.</p>
 169  
 170  <p>The subtype definition should contain:</p>
 171  
 172  <dl>
 173    <dt>title</dt>
 174  
 175    <dd>The title of the subtype.</dd>
 176  
 177    <dt>icon</dt>
 178  
 179    <dd>The icon to display for the subtype.</dd>
 180  
 181    <dt>path</dt>
 182  
 183    <dd>The path for the icon if it is not in the same directory as the
 184    plugin.</dd>
 185  
 186    <dt>description</dt>
 187  
 188    <dd>The short description of the subtype, to be used when selecting
 189    it in the UI.</dd>
 190  
 191    <dt>category</dt>
 192  
 193    <dd>Either a text string for the category, or an array of the text
 194    string followed by the category weight.</dd>
 195  
 196    <dt>required context [Optional]</dt>
 197  
 198    <dd>Either a ctools_context_required or ctools_context_optional or
 199    array of contexts for this content. If omitted, no contexts are
 200    used.</dd>
 201  </dl>
 202  
 203  <h3>Rendered content</h3>
 204  
 205  <p>Rendered content is a little more than just HTML.</p>
 206  
 207  <dl>
 208    <dt>title</dt>
 209  
 210    <dd>The safe to render title of the content.</dd>
 211  
 212    <dt>content</dt>
 213  
 214    <dd>The safe to render HTML content.</dd>
 215  
 216    <dt>links</dt>
 217  
 218    <dd>An array of links associated with the content suitable for
 219    theme('links').</dd>
 220  
 221    <dt>more</dt>
 222  
 223    <dd>An optional 'more' link (destination only)</dd>
 224  
 225    <dt>admin_links</dt>
 226  
 227    <dd>Administrative links associated with the content, suitable for
 228    theme('links').</dd>
 229  
 230    <dt>feeds</dt>
 231  
 232    <dd>An array of feed icons or links associated with the content. Each
 233    member of the array is rendered HTML.</dd>
 234  
 235    <dt>type</dt>
 236  
 237    <dd>The content type.</dd>
 238  
 239    <dt>subtype</dt>
 240  
 241    <dd>The content subtype. These two may be used together as
 242    module-delta for block style rendering.</dd>
 243  </dl>
 244  
 245  <h3>Todo: example</h3>
 246  
 247  <p>Todo after implementations are updated to new version.</p>