PlatformUI routing mechanism
The essential task of the PlatformUI Application component is to handle the routing. It is based on the routing capabilities provided by the YUI App component and it uses hash-based URIs. By default, the PlatformUI Application will recognize and handle several routes which are declared in the app component itself.
A route is described by an object with the following properties:
path: the path to matchview: the identifier of the main view to render when the route is matchedcallbacks: a list of middlewares to executename: an optional name to generate linkssideViews: an optional side view configurationservice: an optional reference to a view service constructor
Modifying the routing from the bundle with a plugin
To tweak any behavior in the application, the way to go is to write a plugin and in this case a plugin for the Application.
Declaring the module providing plugin
The module has to be declared in the extension bundle's yui.yml file. It can be done in the following way:
This configuration means we are declaring a module whose identifier is ezconf-listapplugin. It will be added to the dependency list of the module ez-platformuiapp (the one providing the application component). The plugin module requires ez-pluginregistry, plugin and base. It is stored on the disk in %extending_platformui.public_dir%/js/apps/plugins/ezconf-listappplugin.js.
%extending_platformui.public_dir% is a container parameter which was added in the previous step. It is here to avoid repeating again and again the base path to the public directory. Of course, it is also perfectly possible to write the full path to the module.
Module creation
Before creating the actual plugin code, we have to first create the module in the configured file. The minimal module code is:
The first parameter of YUI.add should be exactly the module identifier used in yui.yml otherwise the module won't be correctly loaded in the application. If the module code does not seem to be taken into account, it is the very first thing to check.
Base plugin code
After the module creation, it is time to create the minimal Application plugin:
The added code creates a plugin class and registers it under Y.eZConf.Plugin.ListAppPlugin, then the PlatformUI plugin registry is configured so that this plugin is automatically instantiated and plugged in the PlatformUI App component.
The PlatformUI's plugin system comes almost entirely from the YUI plugin. While that's not a strict requirement, you should use the Advanced Plugins strategy mentioned in the YUI documentation. That's why in this example and in most cases, the plugin will have the plugin and base YUI plugin as dependencies. base also provides the low level foundations for most PlatformUI component, so reading the Base YUI documentation will also help understanding several concepts used all over the application.
At this point, if you open PlatformUI in your favorite browser with the console open, you should see the result of the console.log calls in the above code.
Adding a route to the application
Finally, the plugin is ready to add a new route to the application. As written in the previous code sample, the plugged object, the application here, is available through this.get('host') in the plugin. The App object provides a route method allowing to add route.
Now, if you refresh your browser, you still need not see any visible change but the application should recognize the /ezconf/list hash URI. Going to /ez#/ezconf/list should display the same thing as /ez#/dashboard.
The PlatformUI Application component extends the YUI App component, as a result the complete API of this component can be used.
Results and next step:
The resulting code can be seen in the 3_routing tag on GitHub, this step result can also be viewed as a diff between tags 2_configuration and 3_routing.
The next step is then to define a new view and to use it when the newly added route is matched.