URL Paths
An important step in learning to develop in MonkCMS is understanding the relationship between templates and URLs. The following information will help you grasp how content created in MonkCMS is accessed via the web browser.
Overview
MonkCMS uses your local web server’s .htaccess file to map requested URLs to their associated templates. This is done using Apache’s “mod_rewrite” URL Rewriting Engine. The system is designed to make use of "clean", or search-engine friendly URLs, e.g. "/path/to/page".
In a nutshell, URL rewriting converts a request for a page using a clean URL into a request for a particular file with a query string (e.g., /template.php?segment1=path&segment2=to&segment3=page). This is all done behind the scenes so that the user’s web browser displays the clean URL but the server knows to use the mapped template or file with query parameters.
Much of the system’s content is outputted to predetermined URLs and mapped to templates automatically by MonkCMS. However, you have the ability to output module content to templates using the Template Manager. In addition, you can do more advanced mapping by specifying custom .htaccess rewrite rules. Both the template manager and custom htaccess manager can be found in the Control Panel.
Anatomy of a Rewrite Rule
Our rewrite rules take advantage of regular expressions, a powerful way of matching specified patterns of text strings. A full explanation of regular expressions is outside of the scope of this article, but having a basic understanding of how they are used to find and substitute text is recommended for those who intend to create custom rules (see Article, Custom Template URL Mapping with .htaccess for more).
Figure 1 shows an example of a rewrite rule and how it works. Keep in mind that this is a very simplified explanation of a more involved process, but understanding the basic concepts will enable you to see how your site URL's are mapped to their various templates.
Figure 1
Default MonkCMS URL Mapping by Module/Type:
Important Notes:
- the following list generally uses conventions for template names (e.g., mcms_page.php for default Pages). For most templates, these names can be changed by you and configured in the Template Manager. Any template names that are reserved by the system and should not be changed are marked by an asterisk (*). You can change the contents of these templates to fit the structure and presentation of your site, but the getContent() calls in the Starter Set files show how to best bring in the content.
- “Slugs” are url-friendly conversions, generally used for the titles of Pages, Articles, Events, etc. A title is converted to a slug by making all characters lowercase and hyphen-separated. Example: “Meet Our Staff” would have a page slug of “meet-our-staff”.
- Display modes: Detail view refers to the individual article, blog post, sermon, etc. List view refers to, not surprisingly, a list of these elements based on a set of criteria.
Home Page
site.com/ ⇒ index.php*
Query variables: nav, clickpath
Universal, System-Outputted Rule:
RewriteRule ^$ index.php?nav=p-36241&clickpath=index [QSA,NC,L]
Pages not in Navigation Hierarchy (Independent Pages)
site.com/[page-slug]/ ⇒ mcms_page.php
Query variables: nav, clickpath, wildcard
Example Rule:
RewriteRule ^about-us(/.*)?/?$ /mcms_page.php?nav=p-36308&clickpath=&wildcard=$1 [QSA,NC,L]
Example URL: site.com/about-us/
Pages in Navigation Hierarchy
site.com/nav-tier1/nav-tier2/[page-slug]/ ⇒ mcms_page.php
Query variables: nav, clickpath, wildcard
Example Rule:
RewriteRule ^welcome/about-us/our-staff(/.*)?/?$ /mcms_page_subnav.php?nav=p-35756&clickpath=welcome/about-us/our-staff&wildcard=$1 [QSA,NC,L]
Example URL: site.com/welcome/about-us/our-staff/
Article Detail Pages
site.com/article/[article-slug] ⇒ ekk_articlepage.php*
Query variables: sermonslug, slug
Universal, System-Outputted Rule:
RewriteRule ^article/([a-z0-9_-]+)/?$ /ekk_articlepage.php?sermonslug=$1&slug=$1 [L,NC,QSA]
Event Detail Page
/event/[year]-[month]-[day]-[event-slug] ⇒ ekk_eventpage.php*
Query variables: slug
Universal, System-Outputted Rule:
RewriteRule ^event/([a-z0-9_-]+)/?$ /ekk_eventpage.php?slug=$1 [L,NC,QSA]
Example URL: site.com/event/2008-07-25-bowling-night
Event List Page (Day Listing)
site.com/events/[year]/[month]/[day]/ ⇒ ekk_events.php*
Query variables: year, month, day
Universal, System-Outputted Rule:
RewriteRule ^events/([0-9]+)/?([0-9]+)?/?([0-9]+)?/?$ /ekk_events.php?year=$1&month=$2&day=$3 [NC,L,QSA]
Example URL: site.com/events/2008/07/25/
Note: often times there is a need to create a Page called “Events”. If this page is independent or in the top level of Navigation, it’s URL will also be mapped to “site.com/events/”, and it will be displayed instead of the Event Detail page. To work around this, simply create a custom .htaccess rewrite rule like the following:
RewriteRule ^daylisting/([0-9]+)/([0-9]+)/([0-9]+)/?$ /ekk_events.php?year=$1&month=$2&day=$3 [NC,L,QSA]
You can use whatever text you want in place of “daylisting”, but you will need to make sure your Event List links point to this instead of the default one.
Sermon Detail Page
site.com/sermon/[sermon-slug]/ ⇒ ekk_sermonpage.php*
Query variables: sermonslug, slug
Universal, System-Outputted Rule:
RewriteRule ^sermon/([a-z0-9_-]+)/?$ /ekk_sermonpage.php?sermonslug=$1&slug=$1 [L,NC,QSA]
Example URL: site.com/sermon/the-love-of-god/