From a847841bfd503192790d9db98ce06ee32053c392 Mon Sep 17 00:00:00 2001 From: OpenUI5 Bot Date: Tue, 9 Apr 2024 08:16:59 +0000 Subject: [PATCH] OpenUI5 Documentation Update 09.04.2024 --- ...ating_Control_and_Class_Modules_c78c07c.md | 26 ++- ...nd_Unit_Customizing_in_OData_V4_4d1b9d4.md | 2 + ...erimental_Configuration_Options_b474a71.md | 30 +++ docs/Example_for_Defining_a_Class_f6fba4c.md | 180 +++++++++--------- docs/OData_V2_Model_6c47b2b.md | 50 +++-- docs/Performance_Speed_Up_Your_App_408b40e.md | 6 +- docs/Step_3_Controls_TypeScript_0feb70c.md | 2 +- 7 files changed, 173 insertions(+), 123 deletions(-) diff --git a/docs/Creating_Control_and_Class_Modules_c78c07c.md b/docs/Creating_Control_and_Class_Modules_c78c07c.md index 615b0aa8..7f5516d4 100644 --- a/docs/Creating_Control_and_Class_Modules_c78c07c.md +++ b/docs/Creating_Control_and_Class_Modules_c78c07c.md @@ -21,7 +21,7 @@ If you want to export the "module value" of an AMD module under a global name, y - Classes created by the `extend` method -- Renderers that are created with `sap.ui.core.Renderer.extend("…")` +- Renderers that are created with `sap/ui/core/Renderer.extend("…")` In control and class modules, you should not use global variables at all. When you derive a custom control from an existing superclass via the `extend` method, the resulting subclass is returned. @@ -33,19 +33,25 @@ JSDoc for the class should use the `@alias` tag to make sure that the variable i The `extend` function makes sure that the respective namespace is created: ```js -sap.ui.define(["sap/ui/base/Object", "sap/ui/model/json/JSONModel"], function (BaseObject, JSONModel) { - - var Foo = BaseObject.extend("foo.bar.MyClass", /** @lends foo.bar.MyClass */ { - - constructor: function(sId, mProperties) { - this.mId = sId; +sap.ui.define(["sap/ui/base/Object"], function (BaseObject) { + + /** + * Constructor for a new MyClass instance. + * + * @class + * Description for MyClass + * @extends sap.ui.base.Object + * @alias foo.bar.MyClass + */ + const Foo = BaseObject.extend("foo.bar.MyClass", /** @lends foo.bar.MyClass.prototype */ { + constructor: function() { } }); - - Foo.prototype.ownMethod = function (a) { + + Foo.prototype.ownMethod = function(a) { return a * 2; }; - + // return the module value, in this example a class return Foo; }); diff --git a/docs/Currency_and_Unit_Customizing_in_OData_V4_4d1b9d4.md b/docs/Currency_and_Unit_Customizing_in_OData_V4_4d1b9d4.md index dd015334..9ede1c2b 100644 --- a/docs/Currency_and_Unit_Customizing_in_OData_V4_4d1b9d4.md +++ b/docs/Currency_and_Unit_Customizing_in_OData_V4_4d1b9d4.md @@ -161,6 +161,8 @@ With the metadata above, you can use the data types `sap.ui.model.odata.type.Cur The code lists are automatically requested only once per browser session and code list URL. +Note that the format options of the `Decimal` type for the measure or amount part may additionally influence the number of displayed and allowed decimals.For more information, see [`sap.ui.model.odata.type.Currency#formatValue`](https://sdk.openui5.org/api/sap.ui.model.odata.type.Currency%23methods/formatValue) and [`sap.ui.model.odata.type.Unit#formatValue`](https://sdk.openui5.org/api/sap.ui.model.odata.type.Unit%23methods/formatValue). + If you use XML templating, you can use `sap.ui.model.odata.v4.AnnotationHelper.format` to generate the composite binding for an amount or measure property. To recognize a property as an amount or measure, the property needs to be annotated either with the `Org.OData.Measures.V1.ISOCurrency`, or with the `Org.OData.Measures.V1.Unit` annotation. For more informatio about XML templating, see [XML Templating](XML_Templating_5ee619f.md). **Additional annotations when using XML templating** diff --git a/docs/Deprecated_and_Experimental_Configuration_Options_b474a71.md b/docs/Deprecated_and_Experimental_Configuration_Options_b474a71.md index 2402a489..104de8e3 100644 --- a/docs/Deprecated_and_Experimental_Configuration_Options_b474a71.md +++ b/docs/Deprecated_and_Experimental_Configuration_Options_b474a71.md @@ -781,6 +781,36 @@ Whether the customizing is disabled or not. +`xx-future` + +\(experimental\) + + + + +Type: `boolean` + +Default value: `false` + +Whether to enforce throwing exceptions for fatal warnings and errors. This helps you to detect and resolve critical issues which may prevent projects from running in future framework versions such as UI5 2.x. + +For a version-dependent guidance, see *Strict Error Handling* in [Best Practices for Developers](Best_Practices_for_Developers_28fcd55.md). + + + + +![YES](images/loio3929e469c7824eb0a69206aeac69f257_LowRes.png) + + + + +![NO](images/loiodfb38de82f6d46dab60cb1397e3ed8ae_LowRes.png) + + + + + + `xx-handle-validation` \(experimental\) diff --git a/docs/Example_for_Defining_a_Class_f6fba4c.md b/docs/Example_for_Defining_a_Class_f6fba4c.md index f90730d8..7f0eb3d2 100644 --- a/docs/Example_for_Defining_a_Class_f6fba4c.md +++ b/docs/Example_for_Defining_a_Class_f6fba4c.md @@ -13,95 +13,97 @@ view on: [demo kit nightly build](https://sdk.openui5.org/nightly/#/topic/f6fba4 Full example of a class definition, including JSDoc ```js -sap.ui.define(["sap/ui/base/Object", "sap/ui/model/json/JSONModel"], function (BaseObject, JSONModel) { - - // declare and document the constructor function - - /** - * Some short sentence that summarizes the functionality of the class. - * - * A more detailed explanation of the class that might consist of multiple sentences - * and paragraphs. It is possible to use XHTML markup - * but this should be used only rarely, as it makes the doclet harder to read - * in the JS editor. - * - * Paragraphs that are separated by empty lines will be formatted as separate - * paragraphs in the final JSDOC documentation. This makes the addition of - *

or
tags unnecessary. - * - * It is possible to reference members of this class (like {@link #ownMethod}) - * or even of other classes (like {@link sap.ui.Object#destroy}). But be careful: - * in contrast to JavaDoc, the signature (parameters) of a method must not be - * included with the @link tag, only the name of the method (as !JavaScript does not support - * method overloading). - * - * @class (mandatory) Marks the function as a constructor (defining a class). - * @param {string} sId Documentation of constructor parameters. - * @param {object} [mProperties=null] For optional parameters, the name is enclosed - * in square brackets. - * A default value can be appended with a '='. - * @param {string} [mProperties.text] Even members of a configuration parameter - * can be configured. - * @see (optional, multiple) Fully qualified HTTP links to external documentation - * are also possible. - * - * @public|@private - (optional) Declares the class as public or private (default). - * @author (optional, multiple) Author is referenced by user Id, not by name. - * Multiple authors are possible, order is - * significant (first named author is the default - * contact). - * @since (optional) When the class/function has been introduced. - * @extends sap.ui.base.Object Documents the inheritance relationship. - * @name foo.bar.MyClass (Mandatory when defining a class with extend). - */ - var Foo = BaseObject.extend("foo.bar.MyClass", /** @lends foo.bar.MyClass */ { - - constructor: function(sId, mProperties) { - - // init and document members here - /** - * The ID of a MyClass. - * - * @private - */ - this.mId = sId || Utils.createGUID(); - }, - - // now add further methods to that prototype - /** - * Again a summary in one sentence. - * - * More details can be documented, when the method is more complex. - * @param {string} sMethod The same mechanism as above can be used to - * document the parameters. - * @param {object} [oListener] An optional parameter. If empty, the - * window is used instead. - * @experimental Since 1.24 Behavior might change. - * @public - */ - ownMethod: function(sMethod, oListener) { - - // ... impl - }, - - /** - * A private method. - * - * Every member with a doc comment is included in the public JSDOC. - * So we explicitly declare this as a private member: - * - * Additionally, using an underscore prefix prevents this method - * from being added to the public facade. - * - * @private - */ - _myVeryPrivateMethod: function() { - } - - }); - - // return the module value, in this example a class - return Foo; +// define the module using the AMD-like sap.ui.define +sap.ui.define(["sap/ui/base/Object"], function( BaseObject ) { + "use strict"; + + // declare and document the constructor function + + /** + * Some short sentence that summarizes the functionality of the class. + * + * A more detailed explanation of the class. Might consist of multiple sentences + * and paragraphs. It is possible to use XHTML markup + * but this should be used only rarely, as it makes the doclet harder to read + * in the JS editor. + * + * Paragraphs that are separated by empty lines will be formatted as separate paragraphs + * in the final JSDOC documentation. This makes the addition of

or
tags + * unnecessary. + * + * It is possible to reference members of this class (like {@link #ownMethod}) or even of + * other classes (like {@link sap.ui.Object#destroy}). But be careful: in contrast to JavaDoc, + * the signature (parameters) of a method must not be included with the @link tag, only the + * name of the method (as !JavaScript has no method overloading). + * + * @class (mandatory) Marks the function as a constructor (defining a class). (Note: if only one token + * follows the @class tag, JSDoc3 assumes that this token is the name of the class. + * If more tokens follow, it assumes that this is a class documentation. so to be on + * the safe side, it is best to use @classdesc for a description and @class or + * @constructor just as a marker.) + * @param {string} sId Documentation of constructor parameters. + * @param {object} [mProperties=null] For optional parameters, the name is enclosed in square brackets. + * A default value can be appended then with a '='. + * @param {string} [mProperties.text] Even members of a configuration parameter can be documented. + * @see (optional, multiple) Fully qualified HTTP links to external documentation are also possible. + * + * The following annotation below defines the visibility as public or private (default). + * Note: there MUST BE NO TEXT AFTER PUBLIC/PRIVATE. Not even in the next line. If anything, + * another tag must follow. + * @public|@private + * @author (optional, multiple) Multiple authors are possible, + * order is significant (first named author is the default contact). + * @since (optional) When the class/function has been introduced. + * @extends sap.ui.base.Object Documents the inheritance relationship. + * @alias foo.bar.MyClass (Mandatory when defining a class with extend). + */ + var MyClass = BaseObject.extend("foo.bar.MyClass", /** @lends foo.bar.MyClass.prototype */ { + + constructor: function(sId, mProperties) { + + // init and document members here + /** + * The ID of a MyClass. + * + * @private + */ + this.mId = sId || Utils.createGUID(); + }, + + // now add further methods to that prototype + /** + * Again a summary in one sentence. + * + * More details can be documented, should the method be that complex. + * @param {string} sMethod The same mechanism as above can be used to document the parameters. + * @param {object} [oListener] An optional parameter. If empty, the window is used instead. + * @experimental Since 1.24 Behavior might change. + * @public + */ + ownMethod: function(sMethod, oListener) { + + // ... impl + }, + + /** + * A private method. + * + * Every member with a doc comment is included in the public JSDOC. + * So we explicitly declare this as a private member: + * + * Additionally, using an underscore prefix prevents this method + * from being added to the public facade. + * + * @private + */ + _myVeryPrivateMethod: function() { + } + + }); + + // export the class + return MyClass; + }); ``` diff --git a/docs/OData_V2_Model_6c47b2b.md b/docs/OData_V2_Model_6c47b2b.md index 584402e3..b0857ba2 100644 --- a/docs/OData_V2_Model_6c47b2b.md +++ b/docs/OData_V2_Model_6c47b2b.md @@ -3608,28 +3608,42 @@ With the metadata above, you can use the `sap.ui.model.odata.type.Currency` and ```js ... + mode:'TwoWay', + parts:[{ + path : 'WeightMeasure', + type : 'sap.ui.model.odata.type.Decimal', + constraints : {'precision' : 13, 'scale' : 3, 'nullable' : false} + }, { + path : 'WeightUnit', + type : 'sap.ui.model.odata.type.String', + constraints : {'maxLength' : 5, 'nullable' : false}, formatOptions : {'parseKeepsEmptyString' : true} + }, { + mode : 'OneTime', + path : '/##@@requestUnitsOfMeasure', + targetType : 'any' + }], + type : 'sap.ui.model.odata.type.Unit'}"/> ... + mode : 'TwoWay', + parts : [{ + path : 'Price', + type : 'sap.ui.model.odata.type.Decimal', + constraints : {'precision' : 16, 'scale' : 3, 'nullable' : false} + }, { + path : 'CurrencyCode', + type : 'sap.ui.model.odata.type.String', + constraints : {'maxLength' : 5, 'nullable' : false}, formatOptions : {'parseKeepsEmptyString' : true} + }, { + mode : 'OneTime', + path : '/##@@requestCurrencyCodes', + targetType : 'any' + }], + type : 'sap.ui.model.odata.type.Currency'}"/> ... ``` The code lists are automatically requested only once per browser session and code list URL. +Note that the format options of the `Decimal` type for the measure or amount part may additionally influence the number of displayed and allowed decimals.For more information, see [`sap.ui.model.odata.type.Currency#formatValue`](https://sdk.openui5.org/api/sap.ui.model.odata.type.Currency%23methods/formatValue) and [`sap.ui.model.odata.type.Unit#formatValue`](https://sdk.openui5.org/api/sap.ui.model.odata.type.Unit%23methods/formatValue). + diff --git a/docs/Performance_Speed_Up_Your_App_408b40e.md b/docs/Performance_Speed_Up_Your_App_408b40e.md index 1db21393..cbecc85c 100644 --- a/docs/Performance_Speed_Up_Your_App_408b40e.md +++ b/docs/Performance_Speed_Up_Your_App_408b40e.md @@ -197,11 +197,7 @@ In this case, use the `data-sap-ui-async="true"` setting in the bootstrap. #### Too many requests -You can use the [UI5 Tooling](https://sap.github.io/ui5-tooling/) to bundle and minimize all relevant component files by creating a component-preload file. - -If you're using OpenUI5 apps with grunt as a web server, you can use the `openui5_preload` task; for more information see [Optimizing OpenUI5/SAPUI5 Apps](http://scn.sap.com/community/developer-center/front-end/blog/2015/02/18/optimizing-openui5-apps) in the SAPUI5 Developer Center on SAP SCN. - -If you're using SAP Web IDE, refer to [Application Build](https://help.sap.com/viewer/825270ffffe74d9f988a0f0066ad59f0/CF/en-US/dfb26ef028624cf486a8bbb0bfd459ff.html) in the SAP Web IDE documentation. +You can use [UI5 Tooling](https://sap.github.io/ui5-tooling/) to bundle and minimize all relevant component files by creating a component-preload file. *** diff --git a/docs/Step_3_Controls_TypeScript_0feb70c.md b/docs/Step_3_Controls_TypeScript_0feb70c.md index ff14bc35..794b7a0a 100644 --- a/docs/Step_3_Controls_TypeScript_0feb70c.md +++ b/docs/Step_3_Controls_TypeScript_0feb70c.md @@ -47,7 +47,7 @@ This will install the type definitions for OpenUI5 and update the `package.json` -### webapp.index.ts +### webapp/index.ts We then make some changes to our `index.ts` file: We remove the `alert` method and instantiate an OpenUI5 `Text` control instead; its options are passed to the constructor with a TypeScript object. For our control we set the `text` property to the value “Hello World”.