A CBaseUrlRule derived class that helps you to work with urls that contains slugs and so on.
The format of slugged urls is in general: /controller/folder-title-slug/contentId-content-title-slug[/customAction]
Note that you can modify the format per controller (perhaps you don't want folders?)
Some examples of supported urls (routing shown assumes default configuration and a map entry for 'forum'):
- /forum/18/some-forum-name/index -> routes to forum/index with $_GET['id'] = 18
- /forum/25/some-forum-name/some-topic-name -> routes to forum/routeRequest with $_GET['id'] = 25
- /forum/25/some-forum-name/some-topic-name/post -> routes to forum/post with $_GET['id'] = 25
If you use the "alias" configuration it is possible to specify aliased controller names. Can be handy if you want to use translations for your controllers in an easy way.
For example: 'forum' => array('board') will allow "board" instead of "forum" in all previous examples as well.
The default configuration assumes the following: ¶
- /controller/id/folder-slug/index -> The "id" is referring to the "folder" (a forum in the example)
- /controller/id/folder-slug/content-slug -> The "id" refers to the content (a topic in the example)
- /controller/id/folder-slug/post -> Custom action for the folder
- /controller/id/folder-slug/content-slug/post -> Custom action for the content
If you remove the "CONTENT_ID" from the urlFormat, the component will add the ID to the content slug. For example: /controller/folder-slug/id-content-slug
Since this class uses the Custom URL rule functionality it requires Yii 1.1.8 or later.
Add it as an URL rule in your urlManager config on the appropriate place (the order in which rules are defined is important as the first matching one is used):
array ( 'class' => 'application.components.UrlRouter', ... rest of the configuration )
I'm hoping most of the configuration is self explanatory (there are a lot of comments in the file). A few pointers though:
- There is a main configuration section that contains some global entries, they count for all the mapped controllers
- The "map" variable is used to define the controllers that the UrlRouter can handle.
- 'defaultConfig' is the global entry with which every 'map' item is merged. If you wish to just support a controller but the default configuration suffices, it is enough to add an entry with 'controller' => array()
Creating Urls ¶
This rule also implements functionality for Yii's createUrl(). It will create urls for you with slugs, based on the specified parameters. Parameters supported are:
- f: [optional] Either a model or a string to be used for the folder slug
- c: Either a model or a string to be used for the content slug
- id: [optional] The ID to use. It will be obtained from the content-model if specified
- action: [optional] name of a custom action
Configuration allows you to change the parameter names for folder and content.
An example, assuming a "forum" object with a title "A Cool Forum" and id 15: Yii::app()->urlManager->createUrl('forum', array('c' => $oForum));
The returned result will be: /forum/15/a-cool-forum The router will ask the forum object for the title and the id property and assemble the url with that.
Imagine a "topic" object in this forum with title "Awesome topic" and id 12: Yii::app()->urlManager->createUrl('forum', array('f' => $oForum, 'c' => $oTopic));
Result will be: /forum/12/a-cool-forum/awesome-topic
Note: Imagine you added the "board" alias talked about in the beginning. If the user entered the site using that, it will be used instead of the forum for these Urls as well. Since you have the code you can remove this behavior but for me the consistency is important.