Helix:URLs
From HelixCore
The URL management of Helix is a deep and complex system, but can be controlled very easily. For the best part, you will only need to edit one field to control the URL for each page, or leave it be and URLs will be generated automatically.
Contents |
Understanding URLs
First and foremost, it's important to know how Helix manages URLs. In the database there are four fields that hold information on URLs:
- url
- urlCompiled
- urlShadow
- urlTitle
The 'url' is the field we see under "URL" in the content editor, this is a template in which the URL is defined from and defaults to '{AUTO}'. You will probably want to leave it on auto, but we'll come back to that shortly.
'urlCompiled' is the complete URL, beginning with a forward slash (/). This exactly matches what you see in the browser, it is kept in the database and you can not directly edit this field from within Helix. If you rebuild you URLs then this field will be overwritten so editing it in the database is pointless.
'urlShadow' is used to track changes to URLs, you can use the Redirect Manager to make massive lists of 301 redirects when restructuring the site from this field. The shadow contains the old URL after a change, you can not edit this field.
'urlTitle' is the important field, this matches the 'URL Generation' field under 'Alternative Names' in the content editor. This field can override the title used by the automatic generation allowing you to customise the URL without needing to change the page title or the URL template.
Advanced URLs
Not all content is static and requires it's own page. Although discouraged, you can create components that will look at the URL to select or create their content. These pages may only have one content ID and have a Regular Expression run over the URL and pointed back to a page. To do this, you must edit the database directly, there is no interface to do this. For more, see Helix:Advanced URLs.
URL Extensions
It's best that every site keeps a common URL extension or suffix, typically .html. Helix defaults the URL extension to .html although this can be changed. To change the default URL extension you must edit the /core/config.php file.
To have URLs display no extension, set the line
$site->urlExtension = "";
For it to display .htm set the line
$site->urlExtension = ".htm";
URL Generation
A URL is defined from it's template (see below) in the URL field. When set to '{AUTO}' Helix will look to the page's primary component for a template. If there is no primary component set then Helix uses a default template of '{PARENTURL}/{ITEMNAME}{EXT}'. You don't need to worry about double forward slashes, Helix will automatically remove any double slashes your template may create and convert them to a single forward slash.
The default template will create URLs based on the content tree of your content structure. Imagine the below example:
/ (Home) | |-- /page-1.html (Page 1) | | | |-- /page-1/subpage-1.html (Subpage 1) | |-- /page-2.html (Page 2)
Page 1 and Page 2 both branch off of the Home page. This makes them children to the Home page. Subpage 1 branches off of Page 1, making it a child page of Page 1. Page 1 and Page 2 are both sibling pages, as they both share the same parent (the Home page).
Lets look at the URLs for each page. The Home page is unique, it is the top-level page for the site and Helix deploys with this page's template being overridden. The URL field for the home page will always be "/". It's a static template, there are no variables in it, so when compiling the URL will always be "/". All URLs should start with a forward slash.
Page 1 used the default template of '{PARENTURL}/{ITEMNAME}{EXT}' so it takes the parent URL (which is Home's "/") and adds a slash, ("//") then adds the ITEMNAME, which is the "name" of the current page. The item name will first look for at the URL Generation field and take that if it exists. If the URL Generation field is blank, then it turns to another setting in the config file:
$site->nameOrder = array( 'title', 'heading' );
This defines the order in which the URL engine then looks to select the item name. In this case, the default case, the site is configured to first look at the title, then the heading. The title is mandatory, so it should always use the title. If you would like it to look at the heading, and if there is no heading then to look at the title, change this line in the config.php to:
$site->nameOrder = array( 'heading', 'title' );
So, now the URL engine has the parent URL, the slash and now the item name, which looks like '//page-1'. {EXT} is the sites default extension, which is '.html' as default. So the URL engine gets a string of '//page-1.html' then removes the double slash for a compiled URL of '/page-1.html'.
The URL engine will convert all names to lower-case, the URL should always be in lower-case. It will also most special characters like quotes, and it will convert spaces as desired. You can choose how to convert spaces, by default it will choose a hyphen.
$site->urlSpace = "-";
Change the hyphen to the character you would like spaces converted to.
Now, the URL for Subpage 1 will look like:
- Parent URL: /page-1.html
- Item Name: subpage-1
- Ext: .html
Note that the engine is smart enough to detect and remove the URL extension from the parent URL. It will ONLY do this if you use {EXT}, if you hard-code .html it WILL NOT remove the extension when compiling the URLs. So, with the {EXT} removed from the parent URL, the engine outputs the final URL of '/page-1/subpage-1.html'.
URL Templates
The URL template (which is the URL field in the content editor) is generally a selection of wildcards, although it can be used to define the URL entirely. If you do change it from {AUTO} then be sure that you begin the URL with a forward slash, ie:
/content/{ITEMHEADING}{EXT}
This would compile the page to look like '/content/page-1.html' regardless of the pages position in the site structure. Wildcards you can use are:
- {AUTO}
- This can only be used as the entire template, {AUTO} can not be combined with other wildcards. Auto will attempt to use the component template else the default template.
- {PARENTURL}
- This seeks the parent pages URL with any reference to {EXT} removed from it.
- {ITEMNAME}
- Is taken from the 'URL Generation' field, then the title and heading, depending on settings.
- {ITEMTITLE}
- Is the page's Title field
- {ITEMHEADING}
- Attempts to take the page's Heading, then the Title if the heading doesn't exist.
- {COMPONENT}
- This will inject the template with the components template. In most cases, you would want this to be the entire template, although it could be only part of it.
- {ASCENDANT#}
- Replace # with a depth integer - this works much like {PARENTURL} but allows you do look much deeper up the sites structure, see below for more.
- {ASCENDANTNAME#}
- Replace # with a depth integer - same as above except it takes the ascendants name, not URL.
- {EXT}
- Takes the sites default URL extension, defined in the config.php file.
Ascendancy in URLs
Imagine you had the structure: Section -> Category -> Item for a store. Lets assume the section page is named "Stationary", then category page is named "Pens" and the item pages is named "Blue Pen". Using {AUTO} we would get the URL '/stationary/pens/blue-pen.html', but what if we want only the section in the URL, and not the category. To achieve this we need to use the ascendant keys: '{ASCENDANT2}/{ITEMNAME}{EXT}' will give us '/stationary/blue-pen.html'. If we wanted it to be '/pens/blue-pen.html' but the Pens URL was '/stationary/pens.html' then we can use the ascendant name key: '{ASCENDANTNAME1}/{ITEMNAME}{EXT}' which will give us the desired URL.
Rebuilding URLs
URLs will not change automatically after making changes to the site, this is done to increase page load time. In order to have URLs update, you need to 'Rebuild URLs'. There is a page in the admin that will do this for you. You can also go directly there from the content page when saving if you select it under the Save button. When you create a new page, the default option is to take you to Rebuild URLs.
Rebuilding the URLs will update the urlCompiled field, and if the URL changes it will move the old URL into the urlShadow field. You can go to the Redirect Manager to install new 301 redirects from the shadow, and can choose to reset the shadow fields.
