Presenter worked example

To give you an idea of how to create a display component using Presenter, we’re going to go through the process of building a basic Trade Tile component from scratch. We’ll go through everything step-by-step, creating the Trade Tile within a blade, and view the results in a workbench. Before you start, you will need to have installed BladeRunner, and know how to create blades and bladesets (if you have no idea what I’m talking about, have a look at the BladeRunner Directory Structure Overview, which will make things clearer).

For the purposes of this example, we’re going to be creating a BladeRunner application called "TutorialMotif", with the application namespace "tutorial". Within that, we’ll have a bladeset called "presenter", and the trade tile blade we are developing, which we’ll call "simpletile".

You can create a new blade easily using the BladeRunner dashboard. Simply click "Add Blade" under the designated bladeset and name it "simpletile".

When you create the new blade using this method, BladeRunner will automatically create a "Hello World" Presenter component and a workbench for the blade. You can open the workbench by clicking on "Run in Workbench" and you’ll see a workbench that looks something like this:

We’re going to be creating the tile Presenter component in its place but we’ll find the prepared workbench (with the "Messages" and "Visualise Presentation Model" widgets) handy.

First of all, we need to create a simple View template (the HTML), and a Presentation Model (in JavaScript), and then bind them together with a PresenterComponent.

At first, our tile is just going to consist of a <select> box, for picking the tile’s instrument. We’ll put that in a <div> block so that our tile can have a nice border, and we have to wrap another <div> around that, with an id that will allow the Presentation Model to be bound to it. That’s important; it won’t work otherwise. The id has to be structured like this:

In our case, we’ll call our template simpletile-template, so it will be: tutorial.presenter.simpletile.simpletile-template

In the Presentation Model, the options for our <select> box are going to be two currency pairs (GBPUSD and AUDUSD), which we’ll hard-code inside a SelectionField; an extension of the caplin.presenter.node.PresentationNode class. In Real Life, you would get your currency pairs from a currency pairs provider.

In setting up the Presentation Model, we have to define the namespace, and also include the caplin.presenter.PresentationModel class, which the Presentation Model extends.

We can now go back to the View, and bind our <select> tag to the new SelectionField node, which we’ve called currencyPairs. A SelectionField contains the option, value and label properties that you might need to populate the options of a selection list. We’ll add a data-bind attribute to call all the options in currencyPairs, and the value of the option selected:

Finally, we’re going to create the component and show it within the blade’s workbench. The blade we created already has a default entry-point to the workbench in the workbench src directory. Here we must make our modifications to get it to construct a PresenterComponent which binds our View and Model by passing in the View’s template id and the Model’s class name.

The workbench is opened via the "workbench\index.html" file. This file should already be populated if you created the blade using the dashboard, as described in the introduction. If you look inside this file, for the initialise() function, you’ll see that upon loading the page, the workbench application (ExampleBladeApplication) is started, and the DOM element containing our Presenter component is centred on the workbench.

Also, in the createWorkbench() function, two other components are added. Most Caplin libraries include workbench widgets that can be appended to the sidelines of your workbench to help you to develop your components within the workbench. In this case, an Event Logger and a Presentation Model Visualiser are added by default. The Visualiser shows all the properties and fields and their values under the Model of our Presenter component. For now it will contain only the currencyPairs field, but it will grow as we add more to the model later in the tutorial.

Having done all this, you can now start up BladeRunner and open the simpletile workbench page in a browser, and if all has gone according to plan, you should see your shiny new Presenter component. I mean OK, at the moment, it’s just a drop-down list in a box, which may not seem that exciting, but we’re only just getting started! We can now build on that until we have a fully functional tile. The workbench should be accessible at: http://localhost:7070/simpletrader/presenter-bladeset/blades/simpletile/workbench/

The workbench should look something like this:

So far, all we can do with our tile is to select a currency pair. Next, we want to be able to set up the details of the trade we want to perform with this currency pair, for which we’ll need an <input> box for the trade amount, a way to select the dealt currency, and some "Sell" and "Buy" buttons.

To do all that, we are going to set up a sub-template. Of course for one little tile, you don’t actually need a sub-template, but once you start developing something bigger, using sub-templates and nested presentation nodes will be incredibly useful, allowing you to split large components into modules, making them much easier to maintain.

We’ll start by creating a new HTML template containing some placeholder text, in much the same way that we set up our original View page, but we’ll call this one setup-template.

And then we’ll set up a corresponding presentation node, which extends caplin.presenter.node.PresentationNode. We’ll call it SetupPresentationNode.

Having done that, we need to go back to our original View and parent Presentation Model, and link the new HTML template and its presentation node to them.

We’ll do that by adding a new <div> block to the View, which binds the sub-template to it using the template’s id. That can go just under the select element we’ve already got:

Underneath the SelectionField in the Presentation Model, we’ll call our new Presentation Node, like this:

Refreshing the workbench updates our tile with the sub-template’s placeholder text.

To enter an amount for the trade, we’ll need a text box, and while we’re at it, we can set up another <select> box for the dealt currencies. Before we add them to the HTML though, we’ll add the necessary fields to the Presentation Node.

If we want the amount field to accept only numeric values, we can apply Caplin’s NumericValidator on the amount field’s value property, setting an error message that will be displayed if someone tries to enter anything other than a valid number.

For the message to be displayed correctly we will need to add the token used above to the translation file:

The validator will be triggered whenever the value in the field is changed. If validation fails, failureMessage (which is a built-in attribute of caplin.presenter.node.Field) is set to the error message that we just defined. Now all we have to do is bind an element to that failureMessage, and it will be displayed whenever the amount field fails validation.

If you go back to the workbench page, you should now see this, when you enter an invalid string into the amount input box. (Notice how the presentation model visualiser gives us more insight into the contents of the amount field and how its values change.)

OK. We can select our currency pair, enter an amount to trade, and specify a dealt currency. Now we need some "Sell" and "Buy" buttons that display the appropriate trade rates for the selected currencies.

Note that we’re still using our sub-template for this, so we’ll start by adding some buttons to the sub-template, and binding them to properties called sellRate and buyRate in the Presentation Node.

For the labels to be displayed correctly we will need to add the tokens used above to the translation file:

And now we’d better create the sellRate and buyRate properties, to make sure that our buttons have something to bind to. For the sake of this exercise, we’ll hard-code the exchange rates. In reality of course, you’d be streaming live prices straight into the tile.

Now it’s quite likely that you don’t actually want your buttons to display prices down to seven decimal places, but as luck would have it, Presenter provides us with a very simple way to format property values before they are displayed! We must first create a formatter which is an extension of caplin.core.Formatter and which will format any numeric value to a desired number of decimal places. The code for this class is pretty straightforward:

This formatter must be a singleton and therefore must be created when the script is loaded. Once a formatter has been added to a property, the format() will be applied every time the property’s value is updated.

Notice from the visualiser, when you refresh the workbench page, that the values of the sell and buy rates have not changed. The formatter only changes the way they are displayed.

Our tile is almost there now. All that’s left is to implement the trading behaviour.

Now we have our buttons, what we really need is to be able to trade when we click them. We’ll do that by binding the click event on each button to a function that we will then set up in our presentation node:

These functions will have to call out to the tile’s Presentation Model to execute a trade. To do that, we’ll add a reference to the Presentation Model as the parent node of the Setup Presentation Node, and the Presentation Model must identify itself to the Setup Presentation Node as its parent.

The executeTrade function, which we’ll create in the Presentation Model, will now have to link out to a Domain Model in order to process the trade. For our purposes, this will be a fake trade model, which at the risk of becoming predictable, we will call FakeTradeModel.

Our executeTrade function has to collect all the trade details from the Presenter Component, and pass them into the FakeTradeModel upon construction. We’ll create an object from the selected option values of the currencyPairs and dealtCurrencies selection fields, the amount property value, and the property value of the rate that applies to the button that the user clicked on.

The fake trade is constructed using the trade details, and identifies the listener to which confirmation should be sent, once the trade has completed. When the executeTrade function in the Trade Model is called, it creates a confirmation message from the trade details, and notifies the listener (which in this case is the tile Presentation Model) with an onTradeCompleted callback.

If you click on one of the trading buttons now, your tile should now react something like this:

All that’s left at this point is to finalise the tile, and to display the confirmation message within the tile itself. To do that, we’ll create a new sub-template and presentation node, just as we did for the setup.

Next, we’ll bind this new sub-template and alter the onTradeCompleted callback, to set the confirmation message on the new presentation node, instead of just outputting it to an alert box.

We can now make the tile hide the setup area when the trade is complete, and also disable the currency pair selector when the confirmation message is displayed. We’ll add two Boolean editable properties to the Presentation Model, and bind them to the sub-templates' visibility, so that the setup node is visible by default and the confirmation node isn’t. We’ll also use the ‘enable’ binding for the currency pairs selector, to bind it to the enabled property of the associated SelectionField.

We can now add a bit more to the onTradeCompleted function, to make it swap the visibility settings of the nodes, and disable the currency pairs selector when a trade is completed.

Our tile is now fully functional. After a trade has been completed, it now displays the confirmation message and hides all the setup controls, while disabling the currency pair, so that we can’t click it again, as you can see here:

Now we have completed the structure and functionality of the tile, all that remains is to add a liberal sprinkling of CSS to make it look pretty, and we’re done! Simply adjust the HTML to have the following classes and ids. We will also need to add a couple of images and some CSS in the themes folder under presenter-bladeset\blades\simpletile\themes, these can be copied across from the TutorialMotif.zip.

Once this is done your tile should now look complete, like this: