Documentation Level: 
Advanced
Documentation Status: 
No known problems

A URL (Uniform Resource Locator) is essentially the generic term for web addresses, meaning the link in the address bar of your browser, such as http://backdropcms.org/documents.

To access content on a Backdrop site, users need a URL to find it, so every content item is given an internal URL in the format "[[Entity Type]]/[[Entity ID]]", leading to URLs for your content and users like http://mysite/node/61, or http://mysite/user/42, or http://mysite/taxonomy/term/55.

These, however, are not friendly or easy to remember; it would be much better to have readable addresses like http://mysite/documentation, or http://myothersite/user/bob. Therefore Backdrop's built-in Path module allows you to automatically override those default internal URLs with URL aliases based on simple rules. 

A URL alias is just an alternate URL that will load an internal Backdrop URL. For example, if the post at URL "node/61" can also be accessed at the URL "about-dragons" then "about-dragons" is an alias of "node/61".

Backdrop creates automatic path aliases for content, users, and taxonomy terms, eliminating the need to create them manually. This way, your site is more user and search engine friendly, and more descriptive about its content with less work from your side. To do so, Backdrop requires that you provide patterns to set how your aliases are generated.

Replacement Patterns

The aliases are generated when you create an object in your site. The generated aliases are based upon patterns (placeholders) you specify; for Page URLs the pattern is the node title. For example if you create a Page with the title "About Dragons", an alias "about-dragons" is automatically created from the node title (the pattern) and your new Page will be accessible at this URL alias.

Patterns are generated using wildcards called tokens to extract elements of the entity which can be then used for creating the URL alias. For example the Token for the node title is [node:title]. Therefore if you set the pattern for Page content to be "my-pages/[node:title]", the alias for the node mentioned in the previous paragraph would become "my-pages/about-dragons".

The pattern for any alias should of course contain at least one part which is expected to be unique for each node. If the pattern was to be set as "my-pages/[node:type]" then every Page node which is created will have exactly the same alias - "my-pages/page" - since the node type for every Page is, of course, "page". Using [node:title] in the alias pattern works because it is likely that the majority of nodes would have unique titles.

Tokens

Backdrop provides several tokens to use as wildcards in patterns, and a "Token browser" to select these tokens. To choose a token, click the "Browse available tokens ..." link to launch the Token browser, browse through the available tokens, and when you are ready to select a token, then click in the textfield where you need to insert the token to activate this field and click the token name to copy it automatically into the textfield.

See the Token documentation for more information about Tokens.

URL Pattern list

The list of patterns can be found at Admin > Configuration > Search and Metadata > URL aliases > Patterns > List patterns. This form lists URL patterns grouped by content type. By default only three patterns are provided, the other fields are blank. These are:

  • Pattern for all Page URLs - [node:title]
  • Default taxonomy term URL pattern (applies to all vocabularies without patterns defined) - [term:vocabulary]/[term:name]
  • Pattern for user account URLs - accounts/[user:name]

To change any of these existing patterns, or to create a new pattern in any one of the blank textfields, enter a pattern text/token combination and click Save configuration.

Pattern settings

The form at Admin > Configuration > Search and Metadata > URL aliases > URL Alias Patterns sets configuration options for patterns. The following field options are available:

Verbose 

When this checkbox is selected, Backdrop will display a message whenever an alias changes (except during bulk updates), such as when a node is saved with a new title. The message format is "Created new alias [[new alias]] for [[internal path]], replacing [[old alias]]".

Separator

This allows you to enter the character used to separate words in titles. This will replace any spaces and punctuation characters. It is recommended not to use spaces or a + character and in fact it is probably best to keep the default dash "-" character. A Page with a title "More about dragons" will be converted to "more-about-dragons" (spaces replaced with dashes).

Character case

Choose whether token values (for example for a token [node:title]) are converted to lowercase or not. Options:

  • Leave case the same as source token values.
  • Change to lower case

 
Maximum URL alias length

Maximum length of aliases to generate. 100 is the recommended length. 255 is the maximum possible length. Aliases longer than this will be truncated at this value.

Maximum component length

Maximum text length of any component in the alias. For example a pattern such as "document/[node:title]/[node:author]" neither [node:title] nor [node:author] will be allowed to be greater than this value, regardless of the Maximum alias length set. 100 is the recommended length. 255 is the maximum possible length.

Update action

This setting determines the action taken when an item already has an alias and has been changed, such as if a node is given a new title. However this is affected by settings on the Redirect module settings. The default options are:

  • Create a new alias. Replace the old alias with a redirect.
  • Create a new alias. Leave the existing alias functioning.
  • Do nothing. Leave the old alias intact.

The Redirect module by default will create a Redirect once an alias is updated. If the Redirect setting at Configuration > Search and Metadata > URL redirects > Settings for "Automatically create redirects when URL aliases are changed" is checked, the default options would remain as listed above; however, if this is unchecked, the first options changes from "Create a new alias. Replace the old alias with a redirect" to "Create a new alias. Delete the old alias". See the Redirect documentation for more information.

Transliterate prior to creating alias

When a pattern includes certain characters (such as those with accents) this determines if these characters should be converted into the US-ASCII alphabet.

Reduce strings to letters and numbers

Filters the new alias to only letters and numbers found in the ASCII-96 set.

Strings to Remove

Certain short and frequently occuring words such as prepositions may not add much to the meaning of a sentence, and consequently an alias formed from a sentence. These words can be automatically removed by this setting. By default the following are stripped:

a, an, as, at, before, but, by, for, from, is, in, into, like, of, off, on, onto, per, since, than, the, this, that, to, up, via, with

Punctuation

This option determines whether a set list of punctuation marks would be removed or replaced from the alias. For each punctuation mark the options are:

  • Remove - the punctuation will be removed
  • Replace by separator - the punctuation mark will be replaced by the default separator (by default a dash "-")
  • No action (do not replace) - punctuation marks will continue to form part of the alias

The following punctuation marks can be replaced:

  • Double quotation marks (")
  • Single quotation marks (apostrophe) (')
  • Back tick (`)
  • Comma (,)
  • Period (.)
  • Hyphen (-)
  • Underscore (_)
  • Colon (:)
  • Semicolon (;)
  • Vertical bar (pipe) (|)
  • Left curly bracket ({)
  • Left square bracket ([)
  • Right curly bracket (})
  • Right square bracket (])
  • Plus sign (+)
  • Equal sign (=)
  • Asterisk (*)
  • Ampersand (&)
  • Percent sign (%)
  • Caret (^)
  • Dollar sign ($)
  • Number sign (pound sign, hash) (#)
  • At sign (@)
  • Exclamation mark (!)
  • Tilde (~)
  • Left parenthesis (()
  • Right parenthesis ())
  • Less-than sign (<)
  • Greater-than sign (>)
  • Slash (/)
  • Backslash (\)

Managing URL Aliases

The URL Aliases list

This is a simple table which lists all aliases created by Backdrop with the internal (system) path which it replaces, and the option to edit or delete this alias.

Bulk generate URL Aliases

If you have recently enabled the Pathauto module (which provides the URL alias functionality) or have recently changed one or more patterns, there may be internal URLs which would not have had aliases generated as yet. For example if you changed the pattern for Post nodes, all existing Posts would still have the old alias or no alias at all. This page allows you to bulk generate these missing aliases. URL aliases will only be created for items that do not already have URL aliases.

To bulk generate aliases, select the types of paths for which you need aliases to be generated and click the Generate URL aliases button.

Bulk delete URL aliases

The form at Admin > Configuration > Search and Metadata > URL aliases > Delete Aliases allows mass deletion of aliases. Caution should be exercised when deleting aliases as no redirects are created for deleted aliases, and your users may already have bookmarked or shared the existing aliases. You may delete all Aliases or delete all of a particular path type. An indicator beneath each option indicates how many of each type exists and therefore what number of aliases which will be deleted.

Manually creating and modifying aliases

Although Backdrop normally silently takes care of alias creation, this can also be done manually. To add a new URL alias go to Admin > Configuration > Search and Metadata > URL aliases > Add URL alias.

Ad URL Alias

A simple form offers two fields for the internal system path for which you wish to create an alias and the alias you wish to assign. For example, if you wish the path "node/55" to have the alias "dragon-watching", enter "node55" in the "Existing system path" textfield and "node/55" in the URL alias field.

URL aliases can all be manually modified. Navigate to the URL Aliases list at Admin > Configuration > Search and Metadata > URL aliases > List URL Aliases and click the "Edit" button for the alias you wish to modify. The options are the same as for the Add URL alias form described above.

List URL Aliases

URL settings on entity forms

Backdrop provides a field in the Edit forms for Content, Taxonomy, and Users  to allow you to add or modify URL aliases during creation or editing of these entities. If the entity type (such as a Post or Page) has a pattern set in the URL Pattern list, the form will also include a checkbox to "Generate automatic URL alias" from this pattern. 

For example the Page content type has a set pattern by default, therefore it is usually not necessary to add a manual alias during creation or update of a Page node: Backdrop will create an automatic alias from this pattern. However you may find situations where you might wish to override this. For instance if the Page title is "Our Wonderful Staff" the generated alias would be of course "our-wonderful-staff" but if you preferred to use just "staff" as your alias, you can uncheck the "Generate automatic URL alias" checkbox, and enter "staff" in the URL alias field.

Post nodes do not have automatic aliases set up  by default. If you find that many of your Post nodes require an alias, it may be smarter to set a pattern for Posts, rather than needing to generate a URL each time.