Permalinks

By default, detail page links look like /news.php?my-article-8. The Permalinks plugin replaces them with clean URLs of your choosing, such as /news/my-article/, and can also alias any other URL on your site. It’s included with current CMS Builder releases; if it isn’t in your plugins list, download it from the Permalinks plugin page.

Permalinks requires Apache with .htaccess support and mod_rewrite.

Setup

1. Activate the plugin under CMS Setup > Plugins.

2. Generate the .htaccess rules with Admin > Code Generator > Permalinks and place them in your website’s root folder. The rules send any request that doesn’t match a real file or folder to the plugin’s dispatcher, which looks up the permalink and serves the target page. Real files always win, so existing URLs keep working.

3. Add a text field named permalink to each section that should have permalink URLs (see Field Editor). The field’s Default value acts as a required prefix for that section’s permalinks — for example news/ (no leading slash). In the record editor the field displays as a full URL.

4. Make sure the section’s Detail Page Url is set on its Viewers tab (CMS Setup > Database Editor > modify > Viewers), since that’s the page a record’s permalink serves.

Filling in permalinks

Editors can type a permalink for each record, or leave the field blank: on save, blank permalinks are filled in automatically from the record’s name or title field (configurable via autopopulate_fromFields at the top of permalinks.php). Values are sanitized either way: lowercased, spaces converted to dashes, and accents and special characters removed.

In viewers

No viewer code changes are needed. When a record has a permalink, the _link pseudo-field is automatically rewritten to the permalink URL, so existing links on list pages and in search results point to the new URLs.

When a permalink is changed, the old one is kept and visitors requesting it are 301-redirected to the current URL, so links and search engine listings don’t break.

To also redirect the original URLs (/news.php?my-article-8) to their new permalinks, add one line to the viewer:

<?php permalinks_301redirectToPermalink($record); ?>

On list or static pages, call it with no argument.

Aliases for list pages and other URLs

Permalinks aren’t limited to record detail pages. The Permalinks DB link in the plugin’s Action column (CMS Setup > Plugins) opens the table of all permalinks, where you can add records by hand: set Permalink to the clean URL and Custom Target Url to the site-root-relative page it should serve, such as /news.php or /about.php?tab=history (query strings are passed through to the target page).

Custom 404 page

Requests that match no file and no permalink get a 404 response rendered by the plugin’s permalinks_notFound404.php. Point $GLOBALS['PERMALINKS']['404_not_found_filepath'] (top of permalinks.php) at your own file to customize it.