Step 34: Custom Controls

이번 튜토리얼은 사용자지정 컨트롤을 사용하여 SAPUI5의 기능을 확장해본다.
detail 페이지에 표시된 제품의 평가를 표시하기 위해 glue code를 추가한다.
이렇게하면 앱 전체에서 컨트롤을 재사용하고 모든 관련 기능을 하나의 모듈에 보관할 수 있다.

Preview

Coding

Walkthrough - Step 34.

webapp/control/ProductRating.js (New)

sap.ui.define([
	"sap/ui/core/Control"
], function (Control) {
	"use strict";
	return Control.extend("sap.ui.demo.walkthrough.control.ProductRating", {
		metadata : {
		},
		init : function () {
		},
		renderer : function (oRM, oControl) {
		}
	});
});

사용자 정의 컨트롤은 SAPUI5의 base object의 common control 기능을 상속받는다.
control의 경우 base object sap.ui.core.Control을 확장하여 이 컨트롤을 수행한다.
custom control은 쉽게 만들 수 있는 재사용 component이다.
이러한 특성 때문에 "notepad"또는 "on the fly" control 이라고 불린다.

custom control은 두 가지 특수 section(metadata 및 renderer)과 기능을 구현하는 여러 메서드가 있는 JavaScript Object이다.

• Metadata

  Metadata section은 data structure control의 API를 정의한다.
  SAPUI5 컨트롤의 property, event 및 aggregation에 대한이 meta 정보를 사용하여
  setter 및 getter 메서드와 응용 프로그램 내에서 호출 할 수 있는 편리한 함수를 자동으로 만들어준다.

• Renderer

  renderer는 control이 view에서 instance화 될 때마다 App의 DOM tree에 추가되는 HTML 구조를 정의한다.
  렌더 함수의 매개 변수 oRM은 문자열을 작성하고 HTML 페이지에 속성을 제어하는 데 사용할 수 있는 SAPUI5 render manager이다.

• init

  init 메서드는 control이 instance화 될 때마다 SAPUI5 core에서 호출되는 함수이다.
  컨트롤을 설정하고 내용을 표시 할 준비를 하는데 사용할 수 있다.

note:
control은 항상 sap.ui.core.Control을 확장하고 자체 rendering을 한다.  
Data binding을 포함하고 있고 Rendering되지 않은 Object에 대한 SAPUI5의 life cycle 특징을 재사용(상속받고자) 하는경우  
sap.ui.core.Element 또는 sap.ui.base.ManagedObject를 직접 확장 할 수 있다.

webapp/control/ProductRating.js

sap.ui.define([
	"sap/ui/core/Control",
	"sap/m/RatingIndicator",
	"sap/m/Label",
	"sap/m/Button"

], function (Control, RatingIndicator, Label, Button) {
	"use strict";
	return Control.extend("sap.ui.demo.walkthrough.control.ProductRating", {
		metadata : {
			properties : {
				value: 	{type : "float", defaultValue : 0}
			},
			aggregations : {
				_rating : {type : "sap.m.RatingIndicator", multiple: false, visibility : "hidden"},
				_label : {type : "sap.m.Label", multiple: false, visibility : "hidden"},
				_button : {type : "sap.m.Button", multiple: false, visibility : "hidden"}
			},
			events : {
				change : {
					parameters : {
						value : {type : "int"}
					}
				}
			}
		},
		init : function () {
			this.setAggregation("_rating", new RatingIndicator({
				value: this.getValue(),
				iconSize: "2rem",
				visualMode: "Half",
				liveChange: this._onRate.bind(this)
			}));
			this.setAggregation("_label", new Label({
				text: "{i18n>productRatingLabelInitial}"
			}).addStyleClass("sapUiSmallMargin"));
			this.setAggregation("_button", new Button({
				text: "{i18n>productRatingButton}",
				press: this._onSubmit.bind(this)
			}).addStyleClass("sapUiTinyMarginTopBottom"));
		},

		setValue: function (fValue) {
			this.setProperty("value", fValue, true);
			this.getAggregation("_rating").setValue(fValue);
		},

		reset: function () {
			var oResourceBundle = this.getModel("i18n").getResourceBundle();

			this.setValue(0);
			this.getAggregation("_label").setDesign("Standard");
			this.getAggregation("_rating").setEnabled(true);
			this.getAggregation("_label").setText(oResourceBundle.getText("productRatingLabelInitial"));
			this.getAggregation("_button").setEnabled(true);
		},

		_onRate : function (oEvent) {
			var oRessourceBundle = this.getModel("i18n").getResourceBundle();
			var fValue = oEvent.getParameter("value");

			this.setProperty("value", fValue, true);

			this.getAggregation("_label").setText(oRessourceBundle.getText("productRatingLabelIndicator", [fValue, oEvent.getSource().getMaxValue()]));
			this.getAggregation("_label").setDesign("Bold");
		},

		_onSubmit : function (oEvent) {
			var oResourceBundle = this.getModel("i18n").getResourceBundle();

			this.getAggregation("_rating").setEnabled(false);
			this.getAggregation("_label").setText(oResourceBundle.getText("productRatingLabelFinal"));
			this.getAggregation("_button").setEnabled(false);
			this.fireEvent("change", {
				value: this.getValue()
			});
		},
		renderer : function (oRM, oControl) {
			oRM.write("<div");
			oRM.writeControlData(oControl);
			oRM.addClass("myAppDemoWTProductRating");
			oRM.writeClasses();
			oRM.write(">");
			oRM.renderControl(oControl.getAggregation("_rating"));
			oRM.renderControl(oControl.getAggregation("_label"));
			oRM.renderControl(oControl.getAggregation("_button"));
			oRM.write("</div>");
		}
	});
});

RatingIndicator control은 제품에 대한 사용자 입력을 수집하고 Label은 추가 정보를 표시하며 Button이 App에 등급을 저장하도록 사용된다.

metadata 섹션에서 구현시 사용할 속성을 몇 가지 정의한다.

• Properties

  사용자가 rating에서 선택한 값을 보유 할 control property 값을 정의한다.
  이 속성에 대한 Getter 및 Setter function이 자동으로 만들어지며 원하는 경우 데이터 model 필드에 바인딩 할 수도 있다.

• Aggregations

  등급 기능을 실현하려면 세 가지 internal control이 필요하다.
  따라서 visibility 속성을 hidden으로 설정하여 세 가지 "hidden aggregation"를 만든다.
  이렇게하면 inner control에서도 view에 설정된 model을 사용할 수 있으며 SAPUI5의 life cycle관리로 더 이상 필요 없는 컨트롤을 파괴한다.
  Aggregation를 사용하여 control 배열을 사용 할 수도 있지만 각 Aggregation에 하나의 control 만 있으면 되므로
  multiple 속성을 false로 설정하여 카디널리티를 낮게 조정한다.

_rating: A sap.m.RatingIndicator 사용자 입력 제어
_label: A sap.m.Label 추가 정보를 표시하는 레이블
_button: A sap.m.Button 등급을 제출할 버튼

note: 컨트롤에 대한 집계 및 연결을 정의 할 수 있다. 차이점은 부모와 관련 컨트롤간의 관계이다.

aggregation : 관련 control의 수명주기를 관리한다.
예를 들어 부모가 삭제된 경우 관련 control도 파괴된다.
또한 컨트롤은 하나의 단일 집계에만 할당 할 수 있다. 두 번째 집계에 할당 된 컨트롤은 이전 집계에서 자동으로 제거된다.

Association : lifecycle를 관리하지 않으며 여러번 정의 할 수있는 약한 관계이다.
분명한 구분을 위해 Association은 ID만 저장하지만 aggregation는 control에 대한 직접 참조를 저장한다.
이 예제에서는 association을 지정하지 않는다. internal control이 부모에 의해 관리된다.

• Events

  rating을 submit할 때 control이 종료(fire)되는 change event를 지정한다. 현재 값을 이벤트 매개 변수로 포함 하고 있다.

control의 new instance가 instance화 될 때마다 SAPUI5에 의해 자동으로 호출되는 init 함수에서 internal control을 설정한다.
3개의 control을 instance화하고 sap.ui.core.Control에서 상속 된 framework method setAggregation을 호출하여 내부 aggregation에 저장한다.
custom control을 RatingIndicator의 liveChange event를  등록하고 Button의 press event도 등록한다. 
일부 컨트롤 속성도 지정한다. Label과 Button의 초기 텍스트는 i18n model에서 참조된다.

renderer를 함수는 참조로 전달되는 SAPUI5 render manager와 control instance의 도움으로 이제 control의 HTML 구조를 rendering할 수 있다.
바깥 쪽

<mvc:View
	controllerName="sap.ui.demo.walkthrough.controller.Detail"
	xmlns="sap.m"
	xmlns:mvc="sap.ui.core.mvc"
	xmlns:wt="sap.ui.demo.walkthrough.control">
	<Page
		title="{i18n>detailPageTitle}"
		showNavButton="true"
		navButtonPress=".onNavBack">
		<ObjectHeader
			intro="{invoice>ShipperName}"
			title="{invoice>ProductName}"/>
		<wt:ProductRating id="rating" class="sapUiSmallMarginBeginEnd" change=".onRatingChange"/>
	</Page>
</mvc:View>

sap.ui.define([
	"sap/ui/core/mvc/Controller",
	"sap/ui/core/routing/History",
	"sap/m/MessageToast",

	"sap/ui/core/UIComponent"
], function (Controller, History, MessageToast, UIComponent) {
	"use strict";

	return Controller.extend("sap.ui.demo.walkthrough.controller.Detail", {
		…
		_onObjectMatched: function (oEvent) {
			this.byId("rating").reset();
			this.getView().bindElement({
				path: "/" + oEvent.getParameter("arguments").invoicePath,
				model: "invoice"
			});
		},

		onNavBack: function () {
			var oHistory = History.getInstance();
			var sPreviousHash = oHistory.getPreviousHash();

			if (sPreviousHash !== undefined) {
				window.history.go(-1);
			} else {
				var oRouter = UIComponent.getRouterFor(this);
				oRouter.navTo("overview", {}, true);
			}
		},

		onRatingChange: function (oEvent) {
			var fValue = oEvent.getParameter("value");
			var oResourceBundle = this.getView().getModel("i18n").getResourceBundle();

			MessageToast.show(oResourceBundle.getText("ratingConfirmation", [fValue]));
		}
	});
});

.myAppDemoWTmyCustomButton.sapMBtn {
	margin-right: 0.125rem;
}
.myAppDemoWTmyCustomText {
	font-weight: bold;
}
/*  ProductRating */
.myAppDemoWTProductRating {
	padding: 0.75rem;
}
.myAppDemoWTProductRating .sapMRI {
	vertical-align: initial;
}

…
# Detail Page
detailPageTitle=Walkthrough - Details
ratingConfirmation=You have rated this product with {0} stars

# Product Rating
productRatingLabelInitial=Please rate this product
productRatingLabelIndicator=Your rating: {0} out of {1}
productRatingLabelFinal=Thank you for your rating!
productRatingButton=Rate