URL Controller and Sitemap

Files

/resources/[language].sitemap.ini

/controllers/controller.url.php

Introduction

Wave Framework comes with a URL Controller and a sitemap system that is used to build a website on Wave Framework. This URL controller is entirely optional and can be removed from a system if you plan to implement your own URL Controller or simply use Wave Framework for API, without a website.

Sitemap is an INI file that defines all the URL's for all the languages - with one sitemap file per language - and these files are used by the URL Controller to find a match in URL and apply a number of settings to the page. Sitemap has groups that act as URL keywords, separated by forward slash '/' characters. URL nodes can also be dynamic and include a regular expression or fixed list.

You can edit Sitemap file and URL Controller file according to your needs. While default URL Controller can easily work for majority of websites, you would have to do some tweaks to URL Controller if you wish to implement a user and permissions management using the set of methods and functions that already exist in Wave Framework.

Sitemap

Sitemap file is an easy-to-edit file that defines every base URL per every language on your website that is built on Wave Framework. There is one Sitemap file per language and the name of the Sitemap file must match the language keywords listed in your configuration file. If 'en' is one of your languages, then you need an en.sitemap.ini file in your /resources/ folder.

Wave Framework has an example 'en' language sitemap by default in the /resources/ folder and you can edit it according to your needs.

Sitemap file consists or groups where every group is a single URL. For example, this is one of the entries in sitemap file:

	
	[home]
	view="home"
	meta-title="Home!"
	cache-timeout=30

This entry says that there exists a URL node of 'home'. This URL is stored in the brackets, as [home]. If you wish to add a URL that has multiple levels, then you can add it as [example/page]. This means that if you visit page http://www.example.com/example/page/ with your browser, then it will load the view information that is under [example/page] group. If it cannot find such a group, then the view will be 404.

Wave Framework also supports language nodes as part of URL's. These language nodes should not be written to Sitemap file. So if you have a Finnish website URL as http://www.example.com/fi/home/ then the fi.sitemap.ini file only has to have a group for [home].

Groups can also accept a dynamic variable as a URL node that can be matched in the Sitemap. There are multiple options that you can use as a URL node:

Also note that 'alpha' and 'alphanumeric' matches also allow dashes and underscores in the URL's. This is because both are accepted URL-friendly characters and used often in variety of projects as part of clean URL's. Additionally, you can define lengths with aterisk, such as ':numeric:1-*', which means that all numbers are allowed that are greater than 1.

Each group has a number of variables assigned under it. You don't have to define all of these variables and the only required variable is 'view', which tells what view will View Controller later on load for showing the web page.

All possible variables are:

General rule is to create one Sitemap file for each language that is defined in configuration and then add your basic URL's to your Sitemap file. Please note that you should also add your View files to /views/ folder, that are referenced in Sitemap, otherwise Wave Framework is unable to load the appropriate views.

URL Controller

Wave Framework comes with a single URL Controller by default and this URL Controller is used to make all decisions about converting requested URL to match languages, sitemaps, views and more.

This URL Controller does a number of things:

URL Controller has a main method of solve() which is called by Data Handler through Index Gateway. This method gets input value of 'url', which is the user-agent requested URL. This solve() method is what does all the URL formatting, redirects and finds the proper view information from Sitemap. If it cannot find a view that matches the URL, then it assumes a '404' view (this view can be changed in configuration file).

After solve() is run, it will call returnViewData() method which will format the data from solve() according to how View Controller expects it. It also assigns a number of defaults for the view:

URL Controller also has a commented-out section for user accounts and permission checks, which allows to check for user sessions and user permissions and redirect the user to log-in page if this is not present. Wave Framework comes with a framework for users and permission management, but does not come with a system where users and their permissions are created. Latter you would have to develop yourself. But URL Controller has an example of how to test existence of users and their permissions and this topic is covered further in Users and Permissions Guide.

Dynamic URL Examples

Wave Framework allows you to define dynamic URL's. Dynamic URL's are URL's that are not matched exactly and are instead matched based on very simple rules. All the rule options are defined in the Sitemap section of this documentation page, but below are a couple of examples where a dynamic URL could be useful.

If you make an e-shop and you want to show product information on some specific View and under some specific URL, then it is not useful to define all of those URL's in the sitemap file itself. This would make the sitemap file very large and possibly slow down the lookup times whenever a user makes a request. But you can define a URL like this:

	
	[products/:numeric:]
	view="products"

The above example works so that if a user makes a request to address 'http://www.example.com/products/123', then that URL would be matched against your sitemap. Since the second URL node after 'products' is declared with a ':numeric:' rule, then that 123 would also match, thus the 'products' view would be loaded.

You can also use dynamic URL's for redirects. The following example redirects all requests to Facebook based on the second URL node:

	
	[facebook/:alphanumeric:]
	temporary-redirect="http://www.facebook.com/:0:"

This means that if a user makes a request like 'http://www.example.com/facebook/johndoe', then they would be redirected to 'http://www.facebook.com/johndoe'. You can also use multiple dynamic variables there and define them as :1:, :2: and so on.

This can be very useful if you wish to redirect old URL's to a new one or do some other form of redirection.