Step 34: Custom Controls

介绍

In this step, we are going to extend the functionality of SAPUI5 with a custom control. We want to rate the product shown on the detail page, so we create a composition of multiple standard controls using the SAPUI5 extension mechanism and add some glue code to make them work nicely together. This way, we can reuse the control across the app and keep all related functionality in one module.

1.练习效果

2.源码

You can view and download all files at Walkthrough – Step 34.

We create a new folder control and a file
ProductRating.js that will hold our new control. As with our
controllers and views, the custom control inherits the common control functionality
from a SAPUI5 base
object, for controls this is done by extending the base class
sap.ui.core.Control.

Custom controls are small reuse components that can be created within the app very
easily. Due to their nature, they are sometimes also referred to as “notepad” or “on
the fly” controls. A custom control is a JavaScript object that has two special
sections (metadata and renderer) and a number of
methods that implement the functionality of the control.

The metadata section defines the data structure and thus the API of
the control. With this meta information on the properties, events, and aggregations
of the control SAPUI5
automatically creates setter and getter methods and other convenience functions that
can be called within the app.

The renderer defines the HTML structure that will be added to the DOM tree of your app whenever the control is instantiated in a view. It is usually
called initially by the core of SAPUI5 and whenever a property of the control is
changed. The parameter oRM of the render function is the SAPUI5
render manager that can be used to write strings and control properties to the HTML page.

The init method is a special function that is called by the SAPUI5 core whenever
the control is instantiated. It can be used to set up the control and prepare its
content for display.

3.Note

Controls always extend sap.ui.core.Control and render themselves. You could also extend sap.ui.core.Element or sap.ui.base.ManagedObject directly if you want to reuse life cycle features of SAPUI5 including data binding for objects that are not rendered. Please refer to the API reference to learn more about the inheritance hierarchy of controls.

We now enhance our new custom control with the custom functionality that we need. In
our case we want to create an interactive product rating, so we define a value and
use three internal controls that are displayed updated by our control automatically.
A RatingIndicator control is used to collect user input on the
product, a label is displaying further information, and a button submits the rating
to the app to store it.

3.Note

In the init function that is called by SAPUI5 automatically
whenever a new instance of the control is instantiated, we set up our internal
controls. We instantiate the three controls and store them in the internal
aggregation by calling the framework method setAggregation that has
been inherited from sap.ui.core.Control. We pass on the name of the
internal aggregations that we specified above and the new control instances. We
specify some control properties to make our custom control look nicer and register a
liveChange event to the rating and a press event to the button.
The initial texts for the label and the button are referenced from our
i18n model.

Let’s ignore the other internal helper functions and event handlers for now and
define our renderer. With the help of the SAPUI5 render manager
and the control instance that are passed on as a reference, we can now render the
HTML structure of our control. We render the start of the outer
<div> tag as <div and call the helper
method writeControlData to render the ID and other basic attributes
of the control inside the div tag. Next, we add a custom CSS class
so that we can define styling rules for the custom control in our CSS file later.
This CSS class and others that have been added in the view are then rendered by
calling writeClasses on the renderer instance. Then we close the
surrounding div tag and render three internal controls by passing
the content of the internal aggregation to the render managers
renderControl function. This will call the renderer of the
controls and add their HTML to the page. Finally, we close our surrounding
<div> tag.

The setValue is an overridden setter. SAPUI5 will generate a
setter that updates the property value when called in a controller or defined in the
XML view, but we also need to update the internal rating control in the hidden
aggregation to reflect the state properly. Also, we can skip the rerendering of SAPUI5 that is usually
triggered when a property is changed on a control by calling the
setProperty method to update the control property with true as
the third parameter.

Now we define the event handler for the internal rating control. It is called every
time the user changes the rating. The current value of the rating control can be
read from the event parameter value of the sap.m.RatingIndicator
control. With the value we call our overridden setter to update the control state,
then we update the label next to the rating to show the user which
value he has selected currently and also displays the maximum value. The string with
the placeholder values is read from the i18n model that is assigned
to the control automatically.

Next, we have the press handler for the rating button that submits our
rating. We assume that rating a product is a one-time action and first disable the
rating and the button so that the user is not allowed to submit another rating. We
also update the label to show a “Thank you for your rating!” message, then we fire
the change event of the control and pass in the current value as a parameter so that
applications that are listening to this event can react on the rating
interaction.

We define the reset method to be able to revert the state of the
control on the UI to its initial state so that the user can again submit a
rating.

A new namespace wt is defined on the detail view so that we can
reference our custom controls easily in the view. We then add an instance of the
ProductRating control to our detail page and register an event
handler for the change event. To have a proper layout, we also add a margin style
class.

In the Detail controller we load the dependency to the
sap.m.MessageToast because we will simply display a message
instead of sending the rating to the backend to keep the example simple. The event
handler onRatingChange reads the value of our custom change event
that is fired when the rating has been submitted. We then display a confirmation
message with the value in a MessageToast control.

In the onObjectMatched private method, we call the
reset method to make it possible to submit another rating as
soon as the detail view is displayed for a different item.

To layout our control, we add a little padding to the root class to have some space
around the three inner controls, and we override the alignment of the
RatingIndicator control so that it is aligned in one line with
the label and the button.

We could also do this with more HTML in the renderer but this is the simplest way and
it will only be applied inside our custom control. However, please be aware that the
custom control is in your app and might have to be adjusted when the inner controls
change in future versions of SAPUI5.

The resource bundle is extended with the confirmation message and the strings that we
reference inside the custom control. We can now rate a product on the detail page
with our brand new control.