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 U= RIs. 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 r=
oute 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 construct=
orTo tweak any behavior in the application, the way to go is to write a pl= ugin and in this case a plugin for the Application.
The module has to be declared in the extension bundle's yui.yml file. It can be done in the following way:
system:
default:
yui:
modules:
# use your own prefix, not "ez-"
ezconf-listapplugin: # module identifier
dependencyOf: ['ez-platformuiapp']
requires: ['ez-pluginregistry', 'plugin', 'base'] # dep=
ends on the plugin code
path: %extending_platformui.public_dir%/js/apps/plugins=
/ezconf-listappplugin.js=20
This configuration means we are declaring a module whose identifier is <=
code>ezconf-listapplugin. It will be added to the dependency list of=
the module ez-platformuiapp (the one providing the applicatio=
n component). The plugin module requires ez-pluginregistry, 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 a=
nd again the base path to the public directory. Of course, it is also perfe=
ctly possible to write the full path to the module.
Before creating the actual plugin code, we have to first create the modu= le in the configured file. The minimal module code is:
YUI.add('ezconf-listapplugin', function (Y) {
// module code goes here!
=09// this function will executed when the module loaded in the app,
// not when the file is loaded by the browser
// the Y parameter gives access to the YUI env, for instance the compon=
ents
// defined by others modules.
}); =20
The first parameter of YUI.add should be exactly the module=
identifier used in yui.yml otherwise the module won't be corr=
ectly loaded in the application. If the module code does not seem to be tak=
en into account, it is the very first thing to check.
After the module creation, it is time to create the minimal Application = plugin:
YUI.add('ezconf-listapplugin', function (Y) {
// Good practices:
// * use a custom namespace. 'eZConf' is used as an example here.
// * put the plugins in a 'Plugin' sub namespace
Y.namespace('eZConf.Plugin');
Y.eZConf.Plugin.ListAppPlugin =3D Y.Base.create('ezconfListAppPlugin', =
Y.Plugin.Base, [], {
initializer: function () {
var app =3D this.get('host'); // the plugged object is called h=
ost
console.log("Hey, I'm a plugin for PlatformUI App!");
console.log("And I'm plugged in ", app);
},
}, {
NS: 'ezconfTypeApp' // don't forget that
});
// registering the plugin for the app
// with that, the plugin is automatically instantiated and plugged in
// 'platformuiApp' component.
Y.eZ.PluginRegistry.registerPlugin(
Y.eZConf.Plugin.ListAppPlugin, ['platformuiApp']
);
});
=20
The added code creates a plugin class and registers it under Y.eZC=
onf.Plugin.ListAppPlugin, then the PlatformUI plugin registry is con=
figured so that this plugin is automatically instantiated and plugged in th=
e PlatformUI App component.
The PlatformUI's plugin system comes almost entirely from the YUI plugin. While that's not a strict requirement, you should us=
e the Advanced Plugins strategy mentioned in the YUI documentation=
. That's why in this example and in most cases, the plugin will have the base YUI plugin as dependencies. b=
ase also provides the low level foundations for most PlatformUI comp=
onent, so reading the Base YUI documentation will also h=
elp you understand 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 cal=
ls in the above code.
Finally, the plugin is ready to add a new route to the application. As w=
ritten in the previous code sample, the plugged object, the application her=
e, is available through this.get('host') in the plugin. The Ap=
p object provides a route<=
/code> method allowing to add route.
YUI.add('ezconf-listapplugin', function (Y) {
Y.namespace('eZConf.Plugin');
Y.eZConf.Plugin.ListAppPlugin =3D Y.Base.create('ezconfListAppPlugin', =
Y.Plugin.Base, [], {
initializer: function () {
var app =3D this.get('host'); // the plugged object is called h=
ost
app.route({
name: "eZConfList",
path: "/ezconf/list",
view: "dashboardView", // let's display the dashboard since=
we don't have a custom view... yet :)
// we want the navigationHub (top menu) but not the discove=
ryBar
// (left bar), we can try different options
sideViews: {'navigationHub': true, 'discoveryBar': false},
callbacks: ['open', 'checkUser', 'handleSideViews', 'handle=
MainView'],
});
},
}, {
NS: 'ezconfTypeApp' // don't forget that
});
Y.eZ.PluginRegistry.registerPlugin(
Y.eZConf.Plugin.ListAppPlugin, ['platformuiApp']
);
});
=20
Now, if you refresh your browser, you still need not see any visible cha=
nge but the application should recognize the /ezconf/list=
hash URI. Going to /ez#/ezconf/list should display the same t=
hing as /ez#/dashboard.
The PlatformUI Application component extends the YUI App component, as a= result the complete API of this component can be used.
The resulting code can be seen in the 3_routing tag on GitHub, this step result can a=
lso be viewed as a diff between tags 2_configuration and <=
code>3_routing.
The next step is then to de= fine a new view and to use it when the newly added route is matched.