path.module 13 KB
Newer Older
Dries's avatar
Dries committed
1
2
3
<?php
/* $Id$ */

4
5
6
7
8
/**
 * Implementation of hook_help().
 */
function path_help($section) {
  switch ($section) {
Dries's avatar
   
Dries committed
9
    case 'admin/modules#description':
10
11
12
13
14
15
16
17
18
19
20
      return t('Enables users to create custom URLs.');
    case 'admin/path':
      return t('Drupal provides users complete control over URLs through aliasing. While the original Drupal URLs are always created and accessible, advanced users have the option to override these normal paths.');
    case 'admin/path/add':
      return t('Enter the path you wish to create the alias for, followed by the name of the new alias. Each path can be associated with only one alias.');
    case 'admin/help#path':
      return t("
<h3>Background</h3>
<p>A very powerful feature of Drupal is the ability to have control over all paths. The path module is the tool that provides this functionality and is part of the basic Drupal installation, although it is not enabled by default. Some examples of re-mapping paths are:</p>
<pre>
user/login => login
Dries's avatar
Dries committed
21

22
image/tid/16 => store
Dries's avatar
Dries committed
23

24
taxonomy/page/or/7,19,20,21 => store/products/whirlygigs
Dries's avatar
Dries committed
25

Dries's avatar
   
Dries committed
26
node/3 => contact
27
28
29
</pre>
<p>This functionality integrates seamlessly into node forms and also provides the administrator an interface to view all aliases that have been created.</p>
<p>Aliases have a 1 to 1 relationship with their original Drupal URLs. In other words you cannot have an alias map to more than one path. Likewise, a Drupal URL can't be mapped to more than one alias.</p>
Dries's avatar
Dries committed
30

31
32
33
<h3>Permissions</h3>
<p>Two permissions are related to URL aliasing: <em>create url aliases</em> and <em>administer url aliases</em>.</p>
<ol><li><strong>create url aliases</strong> - Allows users to create aliases for nodes. Enabling this permission will display a path field to the user in any node form, allowing them to enter an alias for that node. They will be able to edit/delete the alias after it is created using the same form.</li><li><strong>administer url aliases</strong> - Allows users to access the alias administration interface. They must also have the <em>access administration pages</em> permission set as well. This interface displays all aliases and provides a way to create and modify them. This is also the location to build aliases for things other than nodes. For example, you can create an alias for a taxonomy URL or even re-map the admin path (although the original admin path will still be accessible since aliases do not cancel out original paths).</li></ol>
Dries's avatar
   
Dries committed
34

35
36
37
38
39
<h3>Mass URL aliasing</h3>
<p>Drupal also comes with user defined mass URL aliasing capabilities. You might like to see completely different URLs used by Drupal, or even URLs translated to the visitors' native language, in which case this feature is handy. Only an administrator with access to the website source code can set up this kind of aliases. You can define a <code>conf_url_rewrite</code> function in conf.php, following this example:</p>
<pre>
function conf_url_rewrite(\$path, \$mode = 'incoming') {
  if (\$mode == 'incoming') { // URL coming from a client
Dries's avatar
   
Dries committed
40
    return preg_replace('!^display/(\\d+)\$!', 'node/\\1', \$path);
41
42
  }
  else { // URL going out to a client
Dries's avatar
   
Dries committed
43
    \$aliased = preg_replace('!^node/(\\d+)\$!', 'display/\\1', \$path);
44
45
46
47
    if (\$aliased != \$path) { return \$aliased; }
  }
}
</pre>
Dries's avatar
   
Dries committed
48
49
<p>This function will shorten every <code>node/\$node_id</code> type of URL to <code>display/\$node_id</code>. Individual URL aliases defined on the browser interface of Drupal take precedence, so if you have the 'contact' page alias from the example above, then the <code>display/3</code> alias will not be effective when outgoing links are created. Incoming URLs however always work with the mass URL aliased variant. Only the 'incoming' and 'outgoing' modes are supposed to be supported by your <code>conf_url_rewrite</code> function.</p>
<p>You cannot only use this feature to shorten the URLs, or to translate them to you own language, but also to add completely new subURLs to an already existing module's URL space, or to compose a bunch of existing stuff together to a common URL space. You can create a <code>news</code> section for example aliasing nodes and taxonomy overview pages falling under a 'news' vocabulary, thus having <code>news/15</code> and <code>news/sections/3</code> instead of <code>node/15</code> and <code>taxonomy/view/or/3</code>. You need extensive knowledge of Drupal's inner workings and regular expressions though to make such advanced aliases.</p>");
50
51
  }
}
Dries's avatar
   
Dries committed
52

53
/**
Dries's avatar
   
Dries committed
54
 * Implementation of hook_menu().
55
 */
Dries's avatar
   
Dries committed
56
57
function path_menu() {
  $items = array();
Dries's avatar
   
Dries committed
58
  $items[] = array('path' => 'admin/path', 'title' => t('url aliases'),
Dries's avatar
   
Dries committed
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
    'callback' => 'path_admin',
    'access' => user_access('administer url aliases'));
  $items[] = array('path' => 'admin/path/edit', 'title' => t('edit alias'),
    'callback' => 'path_admin_edit',
    'access' => user_access('administer url aliases'),
    'type' => MENU_CALLBACK);
  $items[] = array('path' => 'admin/path/delete', 'title' => t('delete alias'),
    'callback' => 'path_admin_delete',
    'access' => user_access('administer url aliases'),
    'type' => MENU_CALLBACK);
  // Tabs:
  $items[] = array('path' => 'admin/path/add', 'title' => t('add alias'),
    'callback' => 'path_admin_edit',
    'access' => user_access('administer url aliases'),
    'type' => MENU_LOCAL_TASK);
  return $items;
75
}
Dries's avatar
   
Dries committed
76

77
78
79
80
81
82
83
84
85
86
87
88
/**
 * Menu callback; presents an overview of all URL aliases.
 */
function path_admin() {
  print theme('page', path_overview());
}

/**
 * Menu callback; handles pages for creating and editing URL aliases.
 */
function path_admin_edit($pid = 0) {
  if ($_POST['op'] == t('Create new alias') || $_POST['op'] == t('Update alias')) {
Dries's avatar
   
Dries committed
89
    path_save($_POST['edit']);
Dries's avatar
Dries committed
90
  }
91
92
93
94
95
96
97
  else {
    if ($pid) {
      $output = path_form(path_load($pid));
    }
    else {
      $output = path_form();
    }
Dries's avatar
   
Dries committed
98
99

    print theme('page', $output);
100
101
  }
}
Dries's avatar
   
Dries committed
102

103
104
105
106
107
108
/**
 * Menu callback; handles deletion of an URL alias.
 */
function path_admin_delete($pid = 0) {
  path_delete($pid);
  print theme('page', path_overview());
Dries's avatar
Dries committed
109
110
}

111
112
113
114
115
116
117
118
119
120
/**
 * Menu callback; presents the path-specific information from admin/help.
 */
function path_admin_help() {
  print theme('page', path_help('admin/help#path'));
}

/**
 * Set an aliased path for a given Drupal path, preventing duplicates.
 */
Dries's avatar
   
Dries committed
121
122
function path_set_alias($path = NULL, $alias = NULL) {
  if ($path && !$alias) {
Dries's avatar
   
Dries committed
123
    db_query("DELETE FROM {url_alias} WHERE src = '%s'", $path);
Dries's avatar
   
Dries committed
124
125
126
    drupal_rebuild_path_map();
  }
  else if (!$path && $alias) {
Dries's avatar
   
Dries committed
127
    db_query("DELETE FROM {url_alias} WHERE dst = '%s'", $alias);
Dries's avatar
   
Dries committed
128
129
130
    drupal_rebuild_path_map();
  }
  else if ($path && $alias) {
Dries's avatar
   
Dries committed
131
132
    $path_count = db_result(db_query("SELECT COUNT(src) FROM {url_alias} WHERE src = '%s'", $path));
    $alias_count = db_result(db_query("SELECT COUNT(dst) FROM {url_alias} WHERE dst = '%s'", $alias));
Dries's avatar
   
Dries committed
133
134
135

    // We have an insert:
    if ($path_count == 0 && $alias_count == 0) {
136
      db_query("INSERT INTO {url_alias} (src, dst) VALUES ('%s', '%s')", $path, $alias);
Dries's avatar
   
Dries committed
137
138
139
      drupal_rebuild_path_map();
    }
    else if ($path_count == 1 && $alias_count == 0) {
Dries's avatar
   
Dries committed
140
      db_query("UPDATE {url_alias} SET dst = '%s' WHERE src = '%s'", $alias, $path);
Dries's avatar
   
Dries committed
141
142
143
      drupal_rebuild_path_map();
    }
    else if ($path_count == 0 && $alias_count == 1) {
Dries's avatar
   
Dries committed
144
      db_query("UPDATE {url_alias} SET src = '%s' WHERE dst = '%s'", $path, $alias);
Dries's avatar
   
Dries committed
145
146
147
148
149
150
151
152
153
      drupal_rebuild_path_map();
    }
    else if ($path_count == 1 && $alias_count == 1) {
      // This will delete the path that alias was originally pointing to:
      path_set_alias(NULL, $alias);
      path_set_alias($path);
      path_set_alias($path, $alias);
    }
  }
Dries's avatar
Dries committed
154
155
}

156
157
158
159
/**
 * Return a form for editing or creating an individual URL alias.
 */
function path_form($edit = '') {
Dries's avatar
Dries committed
160

Dries's avatar
   
Dries committed
161
  $form .= form_textfield(t('Existing path'), 'src', $edit['src'], 50, 64, t('Specify the existing path you wish to alias. For example: node/28, forum/1, taxonomy/page/or/1,2.'));
162
  $form .= form_textfield(t('New path alias'), 'dst', $edit['dst'], 50, 64, t('Specify an alternative path by which this data can be accessed.  For example, type "about" when writing an about page.  Use a relative path and don\'t add a trailing slash or the URL alias won\'t work.'));
Dries's avatar
Dries committed
163

164
165
166
  if ($edit['pid']) {
    $form .= form_hidden('pid', $edit['pid']);
    $form .= form_submit(t('Update alias'));
Dries's avatar
   
Dries committed
167
168
  }
  else {
169
    $form .= form_submit(t('Create new alias'));
Dries's avatar
   
Dries committed
170
171
172
  }

  return form($form);
Dries's avatar
Dries committed
173
174
}

Dries's avatar
   
Dries committed
175
/**
176
177
178
179
 * Implementation of hook_nodeapi().
 *
 * Allows URL aliases for nodes to be specified at node edit time rather
 * than through the administrative interface.
Dries's avatar
   
Dries committed
180
 */
Dries's avatar
   
Dries committed
181
function path_nodeapi(&$node, $op, $arg) {
182
  if (user_access('create url aliases') || user_access('administer url aliases')) {
Dries's avatar
Dries committed
183

Dries's avatar
   
Dries committed
184
    switch ($op) {
185
      case 'validate':
Dries's avatar
   
Dries committed
186
187
188
        // is_null provides a mechanism for us to determine if this is the first
        // viewing of the form.  If it is the first time, load the alias, if it isn't
        // (i.e., user has clicked preview) let them work with their current form alias.
189
        if (is_null($node->path)) {
Dries's avatar
   
Dries committed
190
          $path = "node/$node->nid";
191
192
193
194
          $alias = drupal_get_path_alias($path);
          if ($alias != $path) {
            $node->path = $alias;
          }
Dries's avatar
   
Dries committed
195
196
        }
        else {
197
198
          $node->path = trim($node->path);
          if ($node->path && !valid_url($node->path)) {
199
            $error['path'] = t('The path is invalid.');
Dries's avatar
   
Dries committed
200
201
            return $error;
          }
Dries's avatar
   
Dries committed
202
          else if (db_result(db_query("SELECT COUNT(dst) FROM {url_alias} WHERE dst = '%s' AND src != '%s'", $node->path, "node/$node->nid"))) {
203
            $error['path'] = t('The path is already in use.');
Dries's avatar
   
Dries committed
204
205
206
207
            return $error;
          }
        }
        break;
Dries's avatar
Dries committed
208

209
210
      case 'form pre':
        return form_textfield(t('Path alias'), 'path', $node->path, 60, 250, t('Optionally specify an alternative URL by which this node can be accessed.  For example, type "about" when writing an about page.  Use a relative path and don\'t add a trailing slash or the URL alias won\'t work.') . theme_error($arg['path']));
Dries's avatar
   
Dries committed
211

212
213
214
      case 'insert':
        // Don't try to insert if path is NULL.  We may have already set
        // the alias ahead of time.
Dries's avatar
   
Dries committed
215
        if ($node->path) {
Dries's avatar
   
Dries committed
216
          path_set_alias("node/$node->nid", $node->path);
Dries's avatar
   
Dries committed
217
218
        }
        break;
219
      case 'update':
Dries's avatar
   
Dries committed
220
        path_set_alias("node/$node->nid", $node->path);
Dries's avatar
   
Dries committed
221
222
        break;

223
      case 'delete':
Dries's avatar
   
Dries committed
224
        $path = "node/$node->nid";
225
226
        if (drupal_get_path_alias($path) != $path) {
          path_set_alias($path);
Dries's avatar
   
Dries committed
227
228
229
        }
        break;
    }
Dries's avatar
Dries committed
230
231
232
  }
}

233
234
235
/**
 * Implementation of hook_perm().
 */
Dries's avatar
Dries committed
236
function path_perm() {
237
  return array('create url aliases', 'administer url aliases');
Dries's avatar
Dries committed
238
239
}

240
241
242
/**
 * Return a listing of all defined URL aliases.
 */
Dries's avatar
Dries committed
243
function path_overview() {
244
  $sql = 'SELECT * FROM {url_alias}';
Dries's avatar
Dries committed
245
  $header = array(
246
247
248
    array('data' => t('alias'), 'field' => 'dst', 'sort' => 'asc'),
    array('data' => t('normal'), 'field' => 'src'),
    array('data' => t('operations'), 'colspan' => 2)
Dries's avatar
Dries committed
249
250
251
252
253
  );
  $sql .= tablesort_sql($header);
  $result = pager_query($sql, 50);

  while ($data = db_fetch_object($result)) {
254
    $rows[] = array($data->dst, $data->src, l(t('edit'), "admin/path/edit/$data->pid"), l(t('delete'), "admin/path/delete/$data->pid"));
Dries's avatar
Dries committed
255
256
  }

257
258
  if ($pager = theme('pager', NULL, 50, 0, tablesort_pager())) {
    $rows[] = array(array('data' => $pager, 'colspan' => '4'));
Dries's avatar
Dries committed
259
260
  }

Dries's avatar
   
Dries committed
261
  if (!$rows) {
262
    $rows[] = array(array('data' => t('No URL aliases available.'), 'colspan' => '4'));
Dries's avatar
   
Dries committed
263
264
  }

265
  return theme('table', $header, $rows);
Dries's avatar
Dries committed
266
267
}

268
269
270
/**
 * Fetch a specific URL alias from the database.
 */
Dries's avatar
   
Dries committed
271
function path_load($pid) {
272
  return db_fetch_array(db_query('SELECT * FROM {url_alias} WHERE pid = %d', $pid));
Dries's avatar
   
Dries committed
273
}
Dries's avatar
Dries committed
274

275
276
277
/**
 * Remove an URL alias from the database.
 */
Dries's avatar
   
Dries committed
278
function path_delete($pid) {
279
280
  db_query('DELETE FROM {url_alias} WHERE pid = %d', $pid);
  drupal_set_message(t('the alias has been deleted.'));
Dries's avatar
   
Dries committed
281
}
Dries's avatar
Dries committed
282

283
284
285
/**
 * Verify that a new URL alias is valid, and save it to the database.
 */
Dries's avatar
   
Dries committed
286
function path_save($edit) {
287
288
289
  $src = $edit['src'];
  $dst = $edit['dst'];
  $pid = $edit['pid'];
Dries's avatar
Dries committed
290

Dries's avatar
   
Dries committed
291
  if (!valid_url($src)) {
Dries's avatar
   
Dries committed
292
    form_set_error('src', t('the normal path "%src" is invalid.', array('%src' => $src)));
Dries's avatar
Dries committed
293
294
  }

295
  if (db_result(db_query("SELECT COUNT(src) FROM {url_alias} WHERE pid != %d AND src = '%s'", $pid, $src))) {
Dries's avatar
   
Dries committed
296
    form_set_error('src', t('the normal path "%src" is already aliased.', array('%src' => $src)));
Dries's avatar
Dries committed
297
298
  }

Dries's avatar
   
Dries committed
299
  if (!valid_url($dst)) {
Dries's avatar
   
Dries committed
300
    form_set_error('dst', t('the alias "%dst" is invalid.', array('%dst' => $dst)));
Dries's avatar
Dries committed
301
302
  }

303
  if (db_result(db_query("SELECT COUNT(dst) FROM {url_alias} WHERE pid != %d AND dst = '%s'", $pid, $dst))) {
Dries's avatar
   
Dries committed
304
    form_set_error('dst', t('the alias "%dst" is already in use.', array('%dst' => $dst)));
Dries's avatar
   
Dries committed
305
  }
Dries's avatar
Dries committed
306

Dries's avatar
   
Dries committed
307
  if (form_has_errors()) {
Dries's avatar
   
Dries committed
308
    return path_form($edit, $error);
Dries's avatar
Dries committed
309
  }
Dries's avatar
   
Dries committed
310
  else {
311
312
313
    // Normally, you would use path_set_alias() to update the paths table,
    // but this is a special case.  We want to modify a specific row and the only
    // way to do that is with pid.
Dries's avatar
   
Dries committed
314
315

    if ($pid) {
316
      db_query("UPDATE {url_alias} SET src = '%s', dst = '%s' WHERE pid = %d", $src, $dst, $pid);
Dries's avatar
   
Dries committed
317
318
319
320
    }
    else {
      path_set_alias($src, $dst);
    }
Dries's avatar
Dries committed
321

Dries's avatar
   
Dries committed
322
    drupal_set_message(t('the alias has been saved.'));
Dries's avatar
   
Dries committed
323
    drupal_goto('admin/path');
Dries's avatar
   
Dries committed
324
  }
Dries's avatar
Dries committed
325
326
327
}

?>