API.txt

   1
   2 Spaces 3.x API
   3 --------------
   4 The following is an overview of using the Spaces API.
   5
   6
   7 Basic usage & concepts
   8 ----------------------
   9 This section is for developers who are using Spaces simply in the context of
  10 site building and don't plan to create any new space types or controllers
  11 (...yet).
  12
  13
  14 ### The active space
  15
  16 On a single page load, only one space (or no space) may be active. Spaces can
  17 be activated through a variety of means, e.g. PURL callback or `hook_init()`,
  18 but they generally must happen early enough in the Drupal bootstrap to be before
  19 the main page callback is executed.
  20
  21 What a space activation looks like in code:
  22
  23     // Loads space class for user uid = 5.
  24     $space = spaces_load('user', 5);
  25
  26     // Makes this the active space for the page.
  27     $space->activate();
  28
  29 You can retrieve the active space later in the page load at any point:
  30
  31     // Retrieve the active space, and use it to set the page title.
  32     $space = spaces_get_space();
  33     drupal_set_title($space->title());
  34
  35
  36 ### Spaces that use PURL
  37
  38 Two of the space types included in Spaces make use of PURL for their activation
  39 (OG, taxonomy). When working with these spaces, you will want to be familiar
  40 with the PURL API for doing things like redirecting between spaces, creating
  41 links that leave or enter a space, and so forth. Please consult the PURL
  42 `README.txt`.
  43
  44
  45 ### Checking access
  46
  47 Each space can have a different configuration for how features and settings can
  48 be accessed. For example, group spaces for private groups (`og_private`) require
  49 that a user is a member of that group before she may access any of its features.
  50
  51 You can check for feature access on a specific space:
  52
  53     // Check that the current user can view the spaces_blog feature for this
  54     // space
  55     $space->access_feature('view', 'space_blog');
  56
  57     // Check that the current user can create a node type associated with
  58     // spaces_blog feature for this space
  59     $space->access_feature('create', 'spaces_blog');
  60
  61     // Function wrapper around performing equivalent checks for the current
  62     // active space, useful for menu access callbacks
  63     spaces_access_feature('view', 'spaces_blog');
  64
  65 Other methods for similar checks can be provided by each space type. In each
  66 pair, the first can be run against any space object while the
  67 equivalent will call the equivalent method for only the current active space.
  68
  69 - `$space->access_space()` and `spaces_access_space()`: Can the current user
  70   access view this space at all when it is active?
  71 - `$space->access_admin()` and `spaces_access_admin()`: Can the current user
  72   administer this space, e.g. enable or disable features.
  73 - `$space->access_user()` and `spaces_access_user()`: Can the current user view
  74   the specified user account in this space?
  75
  76
  77 ### Using controllers
  78
  79 Much of Spaces overrides are handled transparently in Drupal UI elements and API
  80 functions. However, some times you need to get at a specific value or check
  81 whether, for example, the value you got from `variable_get()` originated from
  82 the space, its preset, or the site. Controllers provides methods for doing this.
  83
  84 The space object will have all of the available controller plugins available
  85 under `$space->controllers`. Each controller provides three methods:
  86
  87
  88 `$controller->get($id = NULL, $environment = NULL)`
  89
  90 - `$id` refers to the name of the object you're getting. Example:
  91   `site_frontpage`.
  92 - `$environment` may be either `original`, `preset`, or `space` or `NULL`. If an
  93   environment is specified, the value for that specific environment will
  94   be used. If no environment is provided, the controller will perform a
  95   cascade (e.g. if there is no space value, preset will be checked, if there is
  96   no preset value, original will be checked.)
  97
  98 Examples:
  99
 100     // Get an inherited value for the 'site_frontpage' variable.
 101     $space->controllers->variable->get('site_frontpage');
 102
 103     // Get this space's override value for 'site_frontpage'.
 104     $space->controllers->variable->get('site_frontpage', 'space');
 105
 106     // Get all contexts in this space's preset.
 107     $space->controllers->context->get(NULL, 'preset');
 108
 109
 110 `$controller->set($id, $value)`
 111
 112 - `$id` refers to the name of the object you'd like to override for this space.
 113   Example: `site_frontpage`.
 114 - `$value` is the value that you would like to set for this object. Example:
 115  `node`.
 116
 117
 118 Examples:
 119
 120     // Set the site frontpage to 'dashboard' for this space.
 121     $space->controllers->variable->set('site_frontpage', 'dashboard');
 122
 123     // Set a context override for this space.
 124     $context = context_load('foo');
 125     $space->controllers->context->set('bar', $context);
 126
 127
 128 `$controller->del($id)`
 129
 130 - `$id` refers to the name of the override you'd like to remove in this space.
 131   Example: `site_frontpage`.
 132
 133 Examples:
 134
 135     // Clear out the site frontpage override for this space.
 136     $space->controllers->variable->del('site_frontpage');
 137
 138
 139 Adding a space type or controller plugin
 140 ----------------------------------------
 141 Both space types and controllers utilize the CTools plugins API. In order
 142 to add a new plugin fro your module, follow these steps:
 143
 144 1. Implement `hook_ctools_plugin_api()` in your module. This declares that your
 145   module is API compatible with Spaces 3.
 146
 147         function mymodule_ctools_plugin_api($module, $api) {
 148           if ($module == 'spaces' && $api == 'plugins') {
 149             return array('version' => 3);
 150           }
 151         }
 152
 153 2. Implement `hook_spaces_plugins()` to define your plugins, classes, and class
 154   hierarchy.
 155
 156         function mymodule_spaces_plugins() {
 157           $plugins = array();
 158           $plugins['mymodule_space_foo'] = array(
 159             'handler' => array(
 160               'path' => drupal_get_path('module', 'mymodule') .'/plugins',
 161               'file' => 'mymodule_space_foo.inc',
 162               'class' => 'mymodule_space_foo',
 163               'parent' => 'space',
 164             ),
 165           );
 166           return $plugins;
 167         }
 168
 169 3. Implement `hook_spaces_registry()` to define your space types and/or
 170   controllers and map them to plugins.
 171
 172         function mymodule_spaces_registry() {
 173           return array(
 174             'types' => array(
 175               'foo' => array(
 176                 'title' => t('The foo space'),
 177                 'plugin' => 'mymodule_space_foo',
 178               ),
 179             ),
 180           );
 181         }
 182
 183 4. Write your space type or controller plugin class. It's best to look at one of
 184   the included plugins as a starting point.
 185
 186
 187 Replacing or extending existing plugins
 188 ---------------------------------------
 189 You can replace a space or controller plugin with your own plugin class using
 190 `hook_spaces_registry_alter()`:
 191
 192     function mymodule_spaces_registry_alter(&$registry) {
 193       if (!empty($registry['types']['og'])) {
 194         $registry['type']['og']['plugin'] = 'mymodule_space_og_improved';
 195       }
 196     }
 197
 198 This entry would swap out the default og space type plugin for a custom one
 199 provided by `mymodule`. Note that any replacement plugins must have an entry in
 200 `hook_spaces_plugins()`.