URL routing in IPS4
Most URLs in IPS4 are 'friendly URLs', also known as FURLs - that is, they are plain English and easy to read for users and search engines. The FURL is mapped by IPS4 to a traditional URL with parameters, based on the mappings provided by the application.
For example, the FURL community.com/messenger/compose might be mapped to community.com/index.php?app=core&module=messaging&controller=messenger&do=compose.
How controllers are loaded
Controllers are automatically run when the URL matches. The parameters of the URL are used by IPS4 to locate the correct controller:
app=core
Indicates the controller is in the core app
module=messaging
Indicates the controller is in the messaging module, in the core app
controller=messenger
Indicates we're loading the messenger controller, in the messaging module, in the core app
do=compose
The do param is optional, and allows a particular method within the controller to be called to handle the request. If omitted, by default the manage method of the controller will be called.
So, for the URL community.com/index.php?app=core&module=messaging&controller=messenger&do=compose, the controller loaded would be located at /applications/core/modules/front/messaging/messenger.php, and the compose method inside the controller will be called to handle the request.
Because of this structure, it's very easy to identify exactly which method in which controller is handling a request for any given URL.
Defining friendly URLs
When developing an application, your FURL configuration is created in a file named furl.json in the /data directory of your app. This JSON structure defines the friendly URL, the real URL it maps to, and some other data the FURL might use.
A simple FURL example
... "messenger_compose": { "friendly": "messenger/compose", "real": "app=core&module=messaging&controller=messenger&do=compose" }, ...
The key (messenger_compose in this case) is what identifies this FURL throughout IPS4. When you build links in your templates or controllers, you'll use this key to indicate which FURL is to be used to generate and parse the URL.
The friendly value is the URL links will use and users will see. Don't use leading or trailing slashes. In this example, the URL would end up being community.com/messenger/compose.
The real value is the actual URL that IPS4 will use to locate the correct app/module/controller to handle the request.
FURLs using parameters
Although many FURLs are static and simple, as above, many others will be dynamic and include parameters that identify a particular record that should be displayed - for example, viewing a topic in a forum. To facilitate this, FURL definitions support parameters.
... "profile": { "friendly": "profile/{#id}-{?}", "real": "app=core&module=members&controller=profile" }, ...
Parameters within the FURL are enclosed in {curly braces}. The first character can either be # to match numbers, or @ to match strings. This is followed by the parameter name, and this should match the parameter name that will passed into the real URL. For example, here we use {#id}, which matches a number and will result in &id=123 being passed into our real URL.
The {?} tag can be used for the SEO title; that is, friendly text that identifies the individual record, but which isn't part of the real URL. An example of this would be a topic title - it's included in the URL to help users and search engines, but only the topic ID is used to locate the topic record in the real URL.
You can support multiple SEO titles within a URL by using a zero-indexed number in the tag, for example {?0}, {?1} and {?2}.
Note: You shouldn't specify the FURL parameters you collect in your real URL; they are automatically added to the real URL by the Dispatcher. In the example above, the URL a user would see and visit would be something like community.com/profile/123-someuser.
FURL specificity
The order in which you specify your FURL rules is significant. When the Dispatcher is trying to match a URL, it moves sequentially through the FURL rules, and stops at the first rule that matches. It follows therefore that your most specific rules should come before the less-specific rules in furl.json.
For example, assume we have two rules relating to a user's profile. One is the profile homepage, the other is the profile edit screen. If we ordered the rules like this:
"profile": { "friendly": "profile/{#id}-{?}", "real": "app=core&module=members&controller=profile" }, "edit_profile": { "friendly": "profile/{#id}-{?}/edit", "real": "app=core&module=members&controller=profile&do=edit" },
...then edit_profile will never match. The profile/1-someuser URL would match first, and be called by the Dispatcher. Instead, ordering them like this:
"edit_profile": { "friendly": "profile/{#id}-{?}/edit", "real": "app=core&module=members&controller=profile&do=edit" }, "profile": { "friendly": "profile/{#id}-{?}", "real": "app=core&module=members&controller=profile" },
...means edit_profile will be skipped unless it's an exact match, allowing the more general profile FURL to handle other profile requests.
Report Document