Issue #1811196 by grndlvl: Add descriptions for 'administer spaces' and 'view users...
[project/spaces.git] / 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()`.