├── .editorconfig ├── .eslintrc.json ├── .gitignore ├── .prettierignore ├── .prettierrc.json ├── LICENSE ├── LICENSES └── Apache-2.0.txt ├── README.md ├── REUSE.toml ├── karma-ci-cov.conf.js ├── karma-ci.conf.js ├── karma.conf.js ├── package.json ├── src ├── .library ├── Example.gen.d.ts ├── Example.ts ├── ExampleRenderer.ts ├── library.ts ├── messagebundle.properties └── themes │ ├── base │ ├── Example.less │ └── library.source.less │ ├── sap_fiori_3 │ └── library.source.less │ ├── sap_fiori_3_dark │ └── library.source.less │ ├── sap_fiori_3_hcb │ └── library.source.less │ ├── sap_fiori_3_hcw │ └── library.source.less │ ├── sap_horizon │ └── library.source.less │ ├── sap_horizon_dark │ └── library.source.less │ ├── sap_horizon_hcb │ └── library.source.less │ └── sap_horizon_hcw │ └── library.source.less ├── test ├── Example.html ├── Example.ts └── qunit │ ├── Example.qunit.ts │ ├── testsuite.qunit.html │ └── testsuite.qunit.ts ├── tsconfig.json ├── ui5-dist.yaml ├── ui5-jsdoc.yaml └── ui5.yaml /.editorconfig: -------------------------------------------------------------------------------- 1 | # EditorConfig helps developers define and maintain consistent 2 | # coding styles between different editors and IDEs 3 | # editorconfig.org 4 | 5 | root = true 6 | 7 | [*] 8 | # We recommend you to keep these unchanged 9 | max_line_length = 200 10 | end_of_line = lf 11 | charset = utf-8 12 | trim_trailing_whitespace = true 13 | insert_final_newline = true 14 | 15 | # Change these settings to your own preference 16 | indent_style = tab 17 | indent_size = 2 18 | 19 | [*.{yaml,yml}] 20 | indent_style = space 21 | 22 | [*.md] 23 | indent_style = unset 24 | trim_trailing_whitespace = false 25 | -------------------------------------------------------------------------------- /.eslintrc.json: -------------------------------------------------------------------------------- 1 | { 2 | "env": { 3 | "browser": true, 4 | "es6": true, 5 | "node": true 6 | }, 7 | "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended", "plugin:@typescript-eslint/recommended-requiring-type-checking"], 8 | "parser": "@typescript-eslint/parser", 9 | "parserOptions": { 10 | "project": ["./tsconfig.json"], 11 | "sourceType": "module" 12 | }, 13 | "plugins": ["@typescript-eslint"] 14 | } 15 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules/ 2 | coverage/ 3 | dist/ 4 | package-lock.json 5 | .env 6 | 7 | .vscode/ 8 | .DS_Store 9 | -------------------------------------------------------------------------------- /.prettierignore: -------------------------------------------------------------------------------- 1 | # Ignore build output files 2 | coverage/* 3 | dist/* 4 | 5 | # files to format manually 6 | *.gen.d.ts 7 | README.md 8 | -------------------------------------------------------------------------------- /.prettierrc.json: -------------------------------------------------------------------------------- 1 | { 2 | "singleQuote": false, 3 | "trailingComma": "none", 4 | "overrides": [ 5 | { 6 | "files": ["*.xml"], 7 | "options": { 8 | "xmlWhitespaceSensitivity": "ignore" 9 | } 10 | }, 11 | { 12 | "files": ["*.properties"], 13 | "options": { 14 | "keySeparator": "=" 15 | } 16 | } 17 | ] 18 | } 19 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /LICENSES/Apache-2.0.txt: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [![REUSE status](https://api.reuse.software/badge/github.com/SAP-samples/ui5-typescript-control-library)](https://api.reuse.software/info/github.com/SAP-samples/ui5-typescript-control-library) 2 | 3 | # ui5-typescript-control-library - a Sample UI5 Control Library Developed in TypeScript 4 | 5 | This repository demonstrates and explains how to develop UI5 control libraries in TypeScript. 6 | 7 | ## Table of Contents 8 | 9 | * [Description](#description) 10 | * [Requirements](#requirements) 11 | * [Installation / Setup](#installation---setup) 12 | * [Usage](#usage) 13 | * [Things to Consider When Developing Control Libraries in TypeScript](#things-to-consider-when-developing-control-libraries-in-typescript) 14 | + [TypeScript Transpilation](#typescript-transpilation) 15 | + [tsconfig.json](#tsconfigjson) 16 | + [ui5.yaml](#ui5yaml) 17 | + [Control Implementation](#control-implementation) 18 | + [library.ts](#libraryts) 19 | + [Usage in Non-TypeScript Applications](#usage-in-non-typescript-applications) 20 | + [ESLint](#eslint) 21 | + [Tests](#tests) 22 | * [How to Convert a Library to TypeScript](#how-to-convert-a-library-to-typescript) 23 | * [Known Issues](#known-issues) 24 | * [How to obtain support](#how-to-obtain-support) 25 | * [Contributing](#contributing) 26 | * [Credits](#credits) 27 | * [License](#license) 28 | 29 | ## Description 30 | 31 | This is an example UI5 control library, implemented in TypeScript, including tests, themes (CSS/LESS files), a sample page for trying the control(s), and the entire tool setup for TypeScript transpilation, UI5 build, code linting, etc. 32 | 33 | ## Requirements 34 | 35 | * git client, Node.js 36 | 37 | ## Installation / Setup 38 | 39 | ```sh 40 | git clone https://github.com/SAP-samples/ui5-typescript-control-library.git 41 | cd ui5-typescript-control-library 42 | npm i 43 | ``` 44 | 45 | ## Usage 46 | 47 | Start the control sample page: 48 | 49 | ```sh 50 | npm start 51 | ``` 52 | 53 | This opens the example control sample page in a browser window which triggers several things at once whenever any code is changed: 54 | 55 | * A re-generation of the TypeScript interfaces for the controls (so TypeScript knows all the generated control methods) 56 | * A reload of the page displayed in the browser (and implicit transpilation of TypeScript to JavaScript code) 57 | 58 | This is the mode in which you can best develop the controls within this library when doing changes to the control metadata or creating new controls. 59 | 60 | When the control APIs remain stable, you can also use `npm run start:server` instead, which does almost the same, but skips the TypeScript interface generation. 61 | 62 | **NOTE:** as mentioned above, while you extend/change the API of your control(s), TypeScript needs to be made aware of the methods generated by the UI5 framework at runtime (like `getText()` and `setText(...)` for a `text` property). This happens using the npm package [@ui5/ts-interface-generator](https://github.com/SAP/ui5-typescript/tree/main/packages/ts-interface-generator). This generator runs whenever a file is saved and creates a `*.gen.d.ts` file with the needed declarations next to each control file. So when TypeScript does not seem to know control API accessor methods, save the file and this problem should be gone. Those generated files will be overwritten and may be deleted automatically by the generator, so do not bother to change them manually. 63 | 64 | ## Things to Consider When Developing Control Libraries in TypeScript 65 | 66 | This section walks you through noteworthy points which are different or special in comparison to standard JavaScript development. 67 | 68 | Topics like the themes/CSS and the translation texts are not different at all and hence not explained here. 69 | 70 | ### TypeScript Transpilation 71 | 72 | In general, the TypeScript transpilation is set up as explained in the [step-by-step description](https://github.com/SAP-samples/ui5-typescript-helloworld/blob/main/step-by-step.md#6-using-a-ui5-tooling-extension-for-code-transformation). It uses the UI5 Tooling extension "[ui5-tooling-transpile](https://www.npmjs.com/package/ui5-tooling-transpile)" to transpile the TypeScript sources to JavaScript on the fly. 73 | 74 | ### tsconfig.json 75 | 76 | To make references using the library name work, a path mapping needs to be configured, which points to the respective path below the `src` folder: 77 | 78 | ```json 79 | "paths": { 80 | "com/myorg/myui5lib/*": [ 81 | "./src/*" 82 | ] 83 | } 84 | ``` 85 | 86 | ### ui5.yaml 87 | 88 | To enable the transpilation of TypeScript sources to JavaScript, the UI5 Tooling extension `ui5-tooling-transpile` needs to be added to the `ui5.yaml`. There is no configuration needed by default. 89 | 90 | ```yaml 91 | builder: 92 | customTasks: 93 | - name: ui5-tooling-transpile-task 94 | afterTask: replaceVersion 95 | server: 96 | customMiddleware: 97 | - name: ui5-tooling-transpile-middleware 98 | afterMiddleware: compression 99 | - name: ui5-middleware-livereload 100 | afterMiddleware: compression 101 | ``` 102 | 103 | The `ui5-middleware-livereload` which reloads your HTML page in the browser in case of changes needs to be also listed here. Also this extension is by default configuration free. 104 | 105 | ### Control Implementation 106 | 107 | General aspects of control development in TypeScript are also explained in the [`custom-controls` branch of the "Hello World" repository](https://github.com/SAP-samples/ui5-typescript-helloworld/tree/custom-controls). 108 | 109 | As explained in that other project, the namespace of the control needs to be defined, so the transformation to the traditional UI5 class inheritance with `Control.extend(...)` can reconstruct the full control name. In contrast to there, now an `@name` JSDoc tag with the *full* name is used (but both ways are valid!): 110 | 111 | ``` 112 | @name com.myorg.myui5lib.Example 113 | ``` 114 | 115 | As explained as well in that other project, an npm package named [`ts-interface-generator`](https://www.npmjs.com/package/@ui5/ts-interface-generator) is recommended to be used to generate an interface for all the property/aggregation/association/event setters, getters etc. They are not written down explicitly in the control code, but generated by the UI5 framework at runtime, so TypeScript wouldn't know about their existence otherwise. In addition to running the tool for generating a separate interface file, one needs to manually copy the constructor signatures from the terminal output of the interface generator into the control implementation. This is why there are the following lines at the beginning of the class body: 116 | 117 | ```ts 118 | // The following three lines were generated and should remain as-is to make TypeScript aware of the constructor signatures 119 | constructor(id?: string | $ExampleSettings); 120 | constructor(id?: string, settings?: $ExampleSettings); 121 | constructor(id?: string, settings?: $ExampleSettings) { super(id, settings); } 122 | ``` 123 | 124 | As also explained in that other project, the control metadata should be typed as `MetadataOptions`. Make sure to import it from `sap/ui/core/Element` in case of controls, or the closest base class in general - the metadata option structure is also defined for `Object`, `ManagedObject` and `Component`. You should also use the TypeScript-specific `import type` instead of just `import` to make clear that this import is only needed for types at designtime, with no runtime impact (unless you need to import other things from the `Element` module). `MetadataOptions` is available since UI5 version 1.110; for earlier versions simply use `object` instead: 125 | 126 | ```ts 127 | import type { MetadataOptions } from "sap/ui/core/Element"; 128 | ... 129 | static readonly metadata: MetadataOptions = { ... } 130 | ``` 131 | 132 | Typing it will give you type safety and code completion for this structure. Not typing it, on the other hand, will lead to issues when inheriting from this control, as the TypeScript compiler will expect the same properties to be present in any derived control's metadata. But properties are inherited, so they should not be repeated. 133 | 134 | In contrast to the custom control in that other project, the Renderer is implemented in a separate file, like it is typically done in the original UI5 libraries. But both options are equally valid! 135 | 136 | Make sure to export the control class as default export and to do it immediately when the class is defined, otherwise you will run into trouble using the ts-interface-generator. 137 | 138 | Note that the transformation from ES6 modules to AMD-style UI5 syntax causes named exports to be appended to the object exported as default (which can lead to name clashes), so the import of these modules in legacy code works as expected. 139 | 140 | The following is not specific to TypeScript, but you may not be aware: at the beginning of the file, there is a `${copyright}` placeholder. When you don't remove it, it will be replaced during the UI5 build with content from the `.library` file. 141 | 142 | ### library.ts 143 | 144 | In the `library.ts` file there is one thing to keep in mind: 145 | 146 | In UI5 Libraries implemented in JavaScript, enums must be directly appended to the global namespace of the library. This is required by the UI5 runtime to find the enum type when used for control properties. 147 | 148 | The same is also done here, but as the global object is not known by TypeScript, the object is first acquired using the [`ObjectPath` API](https://openui5.hana.ondemand.com/api/module:sap/base/util/ObjectPath#methods/sap/base/util/ObjectPath.get): 149 | 150 | ```js 151 | const thisLib : {[key: string]: unknown} = ObjectPath.get("com.myorg.myui5lib") as {[key: string]: unknown}; 152 | ``` 153 | 154 | Then the enum is attached to this object: 155 | 156 | ```js 157 | thisLib.ExampleColor = ExampleColor; 158 | ``` 159 | 160 | This is important to be done for all enums. Most things will still seem to work when not doing it, but when the enum is used as type for a control property, UI5 will not be able to find the type (the console will show this as an issue!) and then stop type checking for this property, which can even result in an XSS vulnerability. 161 | 162 | This is not intuitive and quite easy to forget, therefore it is intended to get the UI5 transformer modified to do this automatically. 163 | 164 | When the `${version}` placeholder is used, it is replaced with the version from the `.library` file. 165 | 166 | ### Usage in Non-TypeScript Applications 167 | 168 | Being transpiled to JavaScript, libraries developed in TypeScript can of course also be used in traditionally-written JavaScript-based applications. 169 | 170 | However, the usage of additional Babel plugins can cause issues: one of them occurs when [`@babel/preset-env`](https://babeljs.io/docs/en/babel-preset-env) is used before the `transform-ui5` step in the Babel pipeline (listed further down among the presets in `.babelrc.json`, as the presets are executed bottom-up). It then transforms the default exports of modules to a "default" property on the exported object, when the runtime expects it to be the exported object itself. 171 | 172 | This means that `@babel/preset-env` needs to be applied after `transform-ui5`. This is also documented in the [transform-modules part of `transform-ui5`](https://github.com/ui5-community/babel-plugin-transform-modules-ui5#babelrc). 173 | 174 | ### Building Documentation / Generating `api.json` 175 | 176 | An `api.json` file, which for standard UI5 libraries is the source of the API documentation displayed in the UI5 SDK as well as the source of the generated type definitions, can be generated with the `build:jsdoc` script, which uses a streamlined `ui5.yaml` configuration: 177 | 178 | ```sh 179 | npm run build:jsdoc 180 | ``` 181 | 182 | The generated api.json file can then be found in `dist/test-resources/designtime`. A slightly extended version generated specifically for the SDK is inside the `apiref` folder at the same location. 183 | 184 | ### ESLint 185 | 186 | TypeScript code linting is configured for this repository, using the "eslint", "@typescript-eslint/eslint-plugin" and "@typescript-eslint/parser" npm packages and the `eslintrc.json` file. It is triggered using the npm `lint` script. 187 | 188 | ### Tests 189 | 190 | The `test` directory contains a QUnit-based unit test setup. There is actually nothing TypeScript-specific in that area, but one thing to note: 191 | 192 | The project uses private APIs in the testing area, e.g. resources/sap/ui/test/starter/createSuite.js. This is because the underlying template does so and should be replaced by a cleaner solution. 193 | 194 | ## How to Convert a Library to TypeScript 195 | 196 | If you don't want to simply use the control library in this repository as starting point, e.g. because you already have an existing control library implemented in JavaScipt, you can follow the below steps to convert it to TypeScript: 197 | 198 | 1. Add the `tsconfig.json` to the root directory, with content like in this repository 199 | 1. Add dependencies to the required type definitions, to the UI5 Tooling extensions, and to the interface generator for controls: 200 | * `npm install --save-dev typescript @types/openui5@1.115.1` (You can use the [@sapui5/types](https://www.npmjs.com/package/@sapui5/types) types instead of the OpenUI5 ones when working with SAPUI5. In case the jQuery/QUnit type versions coming with the UI5 types don't match well enough, you can additionally npm install e.g. `@types/jquery@3.5.9` and `@types/qunit@2.5.4`.) 201 | * `npm install --save-dev ui5-tooling-transpile` 202 | * `npm install --save-dev @ui5/ts-interface-generator` 203 | 1. Rename the JavaScript file extensions to `*.ts` and convert their content to TypeScript. 204 | * Depending on the amount of code, this can be major effort, but it can be done partially/increasingly. To avoid TypeScript errors during the transition phase, start with files that have no dependencies to not-yet-converted files. 205 | * In general, look at the respective files inside this repository to understand how your files should look after conversion. Apart from that, you can also find help by looking at the existing documentation for UI5 applications, e.g. regarding the [project setup](https://github.com/SAP-samples/ui5-typescript-helloworld/blob/main/step-by-step.md) and the [code conversion](https://github.com/SAP-samples/ui5-cap-event-app/blob/typescript/docs/typescript.md#converting-ui5-apps-from-javascript-to-typescript). 206 | * Like all UI5 modules written in TypeScript, the control files need to be written as standard ES6 modules and like all UI5 classes written in TypeScript, the controls need to be written as standard ES6 classes. This means: 207 | ```ts 208 | sap.ui.define([ 209 | "./library", 210 | "sap/ui/core/Control", 211 | "./ExampleRenderer" 212 | ], function (library, Control, ExampleRenderer) { 213 | var ExampleColor = library.ExampleColor; 214 | ``` 215 | needs to be converted to: 216 | ```ts 217 | import Control from "sap/ui/core/Control"; 218 | import ExampleRenderer from "./ExampleRenderer"; 219 | import { ExampleColor } from "./library"; 220 | ``` 221 | and 222 | ```ts 223 | var Example = Control.extend("com.myorg.myui5lib.Example", { 224 | metadata: { ... }, 225 | onclick: function() { 226 | ... 227 | } 228 | ... 229 | ``` 230 | needs to be converted to: 231 | ```ts 232 | import type { MetadataOptions } from "sap/ui/core/Element"; 233 | /** 234 | * @name com.myorg.myui5lib.Example 235 | */ 236 | export default class Example extends Control { 237 | static readonly metadata: MetadataOptions = { ... } 238 | onclick = () => { // can of course also be written as traditional "function" 239 | ... 240 | } 241 | ... 242 | ``` 243 | * The `library.ts` file also needs to be converted to an ES6 module. But the `sap.ui.getCore().initLibrary({...})` call needs to remain as-is (using the global `sap` object) to support preloading the library with synchronous bootstrap.
244 | Enums defined within the file can be written as standard TypeScript enums and exported as named exports: 245 | ```ts 246 | export enum ExampleColor { ... } 247 | ``` 248 | But for the time being, each enum also must be added to the global library object *in addition*, in order to enable the UI5 runtime to find it when given as type for a control property. This is because control property types are given as global names: `type: "com.myorg.myui5lib.ExampleColor"`. Do so by acquiring the global object and attaching each enum like this: 249 | ```ts 250 | const thisLib = ObjectPath.get("com.myorg.myui5lib"); 251 | thisLib.ExampleColor = ExampleColor; 252 | ``` 253 | It is intended to handle this automatically during the code transformation in the future. 254 | * While converting control files, it makes sense to run the control interface generator in watch mode, to have interfaces with all the setters, getters etc. for properties, aggregations, events etc. generated, so TypeScript knows about them: `npx @ui5/ts-interface-generator --watch` 255 | * Note: the JSDoc for controls/classes may not contain the `@param` or `@class` JSDoc tag, otherwise the UI5 transformer will not convert the code structure to the classic UI5 class definition. 256 | 1. Adapt the content of the `.library` file which is used during the UI5 build 257 | 1. Adapt `ui5.yaml` to make use of the UI5 Tooling extension `ui5-tooling-transpile` to transpile your sources 258 | 1. It is recommended to persist the various commands as scripts in `package.json`, so you don't have to re-type them every time (the below suggestion requires a small tool, which you can install with `npm i --save-dev npm-run-all`): 259 | * `"build": "npm run build:ts-interfaces && ui5 build --clean-dest",` 260 | * `"build:ts-interfaces": "npx @ui5/ts-interface-generator",` 261 | * `"start": "run-p 'build:ts-interfaces -- --watch' start:server",` 262 | * `"start:server": "ui5 serve --port 8080 -o test-resources/com/myorg/myui5lib/Example.html",` 263 | * `"testsuite": "ui5 serve --open test-resources/com/myorg/myui5lib/qunit/testsuite.qunit.html",` 264 | 1. While the functional setup is now done, you can choose to add further utilities helping with development. The exact setup can be seen inside this repository. Examples are: 265 | * Linting using ESLint: add the `.eslint.json` configuration file and dependencies to ESLint and its TypeScript plugins: `npm i --save-dev eslint @typescript-eslint/eslint-plugin @typescript-eslint/parser` 266 | * Watch mode for the UI5-based preview of the control sample pages, using the [ui5-middleware-livereload](https://www.npmjs.com/package/ui5-middleware-livereload) 267 | 268 | ## Known Issues 269 | 270 | There are limitations, including: 271 | 272 | * The project uses private APIs in the testing area, e.g. `resources/sap/ui/test/starter/createSuite.js`. This is because the underlying template does so and only some of the private API usages have been removed so far. 273 | 274 | ## How to obtain support 275 | 276 | This project is provided *as-is*, without any support guarantees. 277 | 278 | However, you are encouraged to [create an issue](https://github.com/SAP-samples/ui5-typescript-control-library/issues) in this repository or open a pull request if you find a bug or have have an improvement suggestion. 279 | 280 | ## Contributing 281 | 282 | If you wish to contribute code, offer fixes or improvements, please send a pull request. Due to legal reasons, contributors will be asked to accept a DCO when they create the first pull request to this project. This happens in an automated fashion during the submission process. SAP uses [the standard DCO text of the Linux Foundation](https://developercertificate.org/). 283 | 284 | ## Credits 285 | 286 | This project has been generated with 💙 and [generator-ui5-library](https://github.com/geert-janklaps/generator-ui5-library) and then adapted to TypeScript. 287 | 288 | ## License 289 | 290 | Copyright (c) 2021-2023 SAP SE or an SAP affiliate company. All rights reserved. This project is licensed under the Apache Software License, version 2.0 except as noted otherwise in the [LICENSE](LICENSES/Apache-2.0.txt) file. 291 | -------------------------------------------------------------------------------- /REUSE.toml: -------------------------------------------------------------------------------- 1 | version = 1 2 | SPDX-PackageName = "ui5-typescript-control-library" 3 | SPDX-PackageSupplier = "SAP OpenUI5 " 4 | SPDX-PackageDownloadLocation = "https://github.com/SAP-samples/ui5-typescript-control-library" 5 | SPDX-PackageComment = "The code in this project may include calls to APIs (“API Calls”) of\n SAP or third-party products or services developed outside of this project\n (“External Products”).\n “APIs” means application programming interfaces, as well as their respective\n specifications and implementing code that allows software to communicate with\n other software.\n API Calls to External Products are not licensed under the open source license\n that governs this project. The use of such API Calls and related External\n Products are subject to applicable additional agreements with the relevant\n provider of the External Products. In no event shall the open source license\n that governs this project grant any rights in or to any External Products,or\n alter, expand or supersede any terms of the applicable additional agreements.\n If you have a valid license agreement with SAP for the use of a particular SAP\n External Product, then you may make use of any API Calls included in this\n project’s code for that SAP External Product, subject to the terms of such\n license agreement. If you do not have a valid license agreement for the use of\n a particular SAP External Product, then you may only make use of any API Calls\n in this project for that SAP External Product for your internal, non-productive\n and non-commercial test and evaluation of such API Calls. Nothing herein grants\n you any rights to use or access any SAP External Product, or provide any third\n parties the right to use of access any SAP External Product, through API Calls." 6 | 7 | [[annotations]] 8 | path = "**" 9 | precedence = "aggregate" 10 | SPDX-FileCopyrightText = "2021 SAP SE or an SAP affiliate company and ui5-typescript-control-library contributors" 11 | SPDX-License-Identifier = "Apache-2.0" 12 | -------------------------------------------------------------------------------- /karma-ci-cov.conf.js: -------------------------------------------------------------------------------- 1 | module.exports = function (config) { 2 | require("./karma-ci.conf")(config); 3 | config.set({ 4 | reporters: ["progress", "coverage"], 5 | preprocessors: { 6 | "src/**/*.ts": ["ui5-transpile"], 7 | "test/**/*.ts": ["ui5-transpile"] 8 | }, 9 | proxies: { 10 | '/resources/com/myorg/myui5lib/': '/base/src/', 11 | '/test-resources/com/myorg/myui5lib/': '/base/test/', 12 | }, 13 | coverageReporter: { 14 | dir: "coverage", 15 | reporters: [ 16 | { type: "html", subdir: "report-html" }, 17 | { type: "cobertura", subdir: ".", file: "cobertura.txt" }, 18 | { type: "lcovonly", subdir: ".", file: "report-lcovonly.txt" }, 19 | { type: "text-summary" } 20 | ] 21 | } 22 | }); 23 | }; 24 | -------------------------------------------------------------------------------- /karma-ci.conf.js: -------------------------------------------------------------------------------- 1 | module.exports = function (config) { 2 | require("./karma.conf")(config); 3 | config.set({ 4 | browsers: ["ChromeHeadless"], 5 | singleRun: true 6 | }); 7 | }; 8 | -------------------------------------------------------------------------------- /karma.conf.js: -------------------------------------------------------------------------------- 1 | // karma-ui5 usage: https://github.com/SAP/karma-ui5 2 | module.exports = function (config) { 3 | config.set({ 4 | frameworks: ["ui5"], 5 | browsers: ["Chrome"] 6 | }); 7 | }; 8 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "ui5-typescript-control-library", 3 | "version": "1.0.0", 4 | "description": "Showcase of a TypeScript setup for developing UI5 control libraries", 5 | "author": "SAP SE", 6 | "license": "Apache-2.0", 7 | "repository": { 8 | "type": "git", 9 | "url": "https://github.com/SAP-samples/ui5-typescript-control-library.git" 10 | }, 11 | "types": "dist/index.d.ts", 12 | "scripts": { 13 | "clean": "rimraf dist coverage", 14 | "build": "npm run build:ts-interfaces && ui5 build --clean-dest", 15 | "build:ts-interfaces": "npx @ui5/ts-interface-generator", 16 | "build:jsdoc": "ui5 build jsdoc --config ui5-jsdoc.yaml --exclude-task buildThemes", 17 | "start": "run-p 'build:ts-interfaces -- --watch' start:server", 18 | "start:server": "ui5 serve --port 8080 -o test-resources/com/myorg/myui5lib/Example.html", 19 | "start:dist": "ui5 serve --port 8080 -o test-resources/com/myorg/myui5lib/Example.html --config ui5-dist.yaml", 20 | "testsuite": "ui5 serve --open test-resources/com/myorg/myui5lib/qunit/testsuite.qunit.html", 21 | "ts-typecheck": "tsc --noEmit", 22 | "format": "prettier --write .", 23 | "lint": "eslint src test", 24 | "karma": "karma start", 25 | "karma-ci": "karma start karma-ci.conf.js", 26 | "karma-ci-cov": "karma start karma-ci-cov.conf.js", 27 | "test": "npm run lint && npm run karma-ci-cov" 28 | }, 29 | "devDependencies": { 30 | "@prettier/plugin-xml": "^3.1.1", 31 | "@types/openui5": "1.115.1", 32 | "@typescript-eslint/eslint-plugin": "^6.0.0", 33 | "@typescript-eslint/parser": "^6.0.0", 34 | "@ui5/cli": "^3.3.2", 35 | "@ui5/ts-interface-generator": "^0.7.0", 36 | "eslint": "^8.45.0", 37 | "karma": "^6.4.2", 38 | "karma-chrome-launcher": "^3.2.0", 39 | "karma-coverage": "^2.2.1", 40 | "karma-ui5": "^3.0.3", 41 | "karma-ui5-transpile": "^0.3.24", 42 | "npm-run-all": "^4.1.5", 43 | "prettier": "^3.0.0", 44 | "prettier-plugin-properties": "^0.2.0", 45 | "rimraf": "^5.0.1", 46 | "typescript": "^5.1.6", 47 | "ui5-middleware-livereload": "^0.8.4", 48 | "ui5-tooling-transpile": "^0.7.19" 49 | } 50 | } 51 | -------------------------------------------------------------------------------- /src/.library: -------------------------------------------------------------------------------- 1 | 2 | 3 | com.myorg.myui5lib 4 | myorg 5 | 1.0.0 6 | (c) 2023 com.myorg.myui5lib contributors 7 | com.myorg.myui5lib 8 | Some description about com.myorg.myui5lib 9 | 10 | 11 | sap.ui.core 12 | 13 | 14 | 15 | -------------------------------------------------------------------------------- /src/Example.gen.d.ts: -------------------------------------------------------------------------------- 1 | import Event from "sap/ui/base/Event"; 2 | import { ExampleColor } from "com/myorg/myui5lib/library"; 3 | import { PropertyBindingInfo } from "sap/ui/base/ManagedObject"; 4 | import { $ControlSettings } from "sap/ui/core/Control"; 5 | 6 | declare module "./Example" { 7 | 8 | /** 9 | * Interface defining the settings object used in constructor calls 10 | */ 11 | interface $ExampleSettings extends $ControlSettings { 12 | 13 | /** 14 | * The text to display. 15 | */ 16 | text?: string | PropertyBindingInfo; 17 | 18 | /** 19 | * The color to use (default to "Default" color). 20 | */ 21 | color?: ExampleColor | PropertyBindingInfo | `{${string}}`; 22 | 23 | /** 24 | * Event is fired when the user clicks the control. 25 | */ 26 | press?: (event: Example$PressEvent) => void; 27 | } 28 | 29 | export default interface Example { 30 | 31 | // property: text 32 | 33 | /** 34 | * Gets current value of property "text". 35 | * 36 | * The text to display. 37 | * 38 | * @returns Value of property "text" 39 | */ 40 | getText(): string; 41 | 42 | /** 43 | * Sets a new value for property "text". 44 | * 45 | * The text to display. 46 | * 47 | * When called with a value of "null" or "undefined", the default value of the property will be restored. 48 | * 49 | * @param text New value for property "text" 50 | * @returns Reference to "this" in order to allow method chaining 51 | */ 52 | setText(text: string): this; 53 | 54 | // property: color 55 | 56 | /** 57 | * Gets current value of property "color". 58 | * 59 | * The color to use (default to "Default" color). 60 | * 61 | * Default value is: "ExampleColor.Default" 62 | * @returns Value of property "color" 63 | */ 64 | getColor(): ExampleColor; 65 | 66 | /** 67 | * Sets a new value for property "color". 68 | * 69 | * The color to use (default to "Default" color). 70 | * 71 | * When called with a value of "null" or "undefined", the default value of the property will be restored. 72 | * 73 | * Default value is: "ExampleColor.Default" 74 | * @param [color="ExampleColor.Default"] New value for property "color" 75 | * @returns Reference to "this" in order to allow method chaining 76 | */ 77 | setColor(color: ExampleColor): this; 78 | 79 | // event: press 80 | 81 | /** 82 | * Attaches event handler "fn" to the "press" event of this "Example". 83 | * 84 | * Event is fired when the user clicks the control. 85 | * 86 | * When called, the context of the event handler (its "this") will be bound to "oListener" if specified, 87 | * otherwise it will be bound to this "Example" itself. 88 | * 89 | * @param fn The function to be called when the event occurs 90 | * @param listener Context object to call the event handler with. Defaults to this "Example" itself 91 | * 92 | * @returns Reference to "this" in order to allow method chaining 93 | */ 94 | attachPress(fn: (event: Example$PressEvent) => void, listener?: object): this; 95 | 96 | /** 97 | * Attaches event handler "fn" to the "press" event of this "Example". 98 | * 99 | * Event is fired when the user clicks the control. 100 | * 101 | * When called, the context of the event handler (its "this") will be bound to "oListener" if specified, 102 | * otherwise it will be bound to this "Example" itself. 103 | * 104 | * @param data An application-specific payload object that will be passed to the event handler along with the event object when firing the event 105 | * @param fn The function to be called when the event occurs 106 | * @param listener Context object to call the event handler with. Defaults to this "Example" itself 107 | * 108 | * @returns Reference to "this" in order to allow method chaining 109 | */ 110 | attachPress(data: CustomDataType, fn: (event: Example$PressEvent, data: CustomDataType) => void, listener?: object): this; 111 | 112 | /** 113 | * Detaches event handler "fn" from the "press" event of this "Example". 114 | * 115 | * Event is fired when the user clicks the control. 116 | * 117 | * The passed function and listener object must match the ones used for event registration. 118 | * 119 | * @param fn The function to be called, when the event occurs 120 | * @param listener Context object on which the given function had to be called 121 | * @returns Reference to "this" in order to allow method chaining 122 | */ 123 | detachPress(fn: (event: Example$PressEvent) => void, listener?: object): this; 124 | 125 | /** 126 | * Fires event "press" to attached listeners. 127 | * 128 | * Event is fired when the user clicks the control. 129 | * 130 | * @param parameters Parameters to pass along with the event 131 | * @returns Reference to "this" in order to allow method chaining 132 | */ 133 | firePress(parameters?: Example$PressEventParameters): this; 134 | } 135 | 136 | /** 137 | * Interface describing the parameters of Example's 'press' event. 138 | * Event is fired when the user clicks the control. 139 | */ 140 | // eslint-disable-next-line 141 | export interface Example$PressEventParameters { 142 | } 143 | 144 | /** 145 | * Type describing the Example's 'press' event. 146 | * Event is fired when the user clicks the control. 147 | */ 148 | export type Example$PressEvent = Event; 149 | } 150 | -------------------------------------------------------------------------------- /src/Example.ts: -------------------------------------------------------------------------------- 1 | /*! 2 | * ${copyright} 3 | */ 4 | 5 | // Provides control com.myorg.myui5lib.Example. 6 | import Control from "sap/ui/core/Control"; 7 | import ExampleRenderer from "./ExampleRenderer"; 8 | import { ExampleColor } from "./library"; 9 | import type { MetadataOptions } from "sap/ui/core/Element"; 10 | 11 | /** 12 | * Constructor for a new com.myorg.myui5lib.Example control. 13 | * 14 | * Some class description goes here. 15 | * @extends sap.ui.core.Control 16 | * 17 | * @author OpenUI5 Team 18 | * @version ${version} 19 | * 20 | * @constructor 21 | * @public 22 | * @name com.myorg.myui5lib.Example 23 | */ 24 | export default class Example extends Control { 25 | // The following three lines were generated and should remain as-is to make TypeScript aware of the constructor signatures 26 | constructor(id?: string | $ExampleSettings); 27 | constructor(id?: string, settings?: $ExampleSettings); 28 | constructor(id?: string, settings?: $ExampleSettings) { 29 | super(id, settings); 30 | } 31 | 32 | static readonly metadata: MetadataOptions = { 33 | library: "com.myorg.myui5lib", 34 | properties: { 35 | /** 36 | * The text to display. 37 | */ 38 | text: { 39 | type: "string", 40 | group: "Data", 41 | defaultValue: null 42 | }, 43 | /** 44 | * The color to use (default to "Default" color). 45 | */ 46 | color: { 47 | type: "com.myorg.myui5lib.ExampleColor", 48 | group: "Appearance", 49 | defaultValue: ExampleColor.Default 50 | } 51 | }, 52 | events: { 53 | /** 54 | * Event is fired when the user clicks the control. 55 | */ 56 | press: {} 57 | } 58 | }; 59 | 60 | static renderer: typeof ExampleRenderer = ExampleRenderer; 61 | 62 | onclick = () => { 63 | this.firePress(); 64 | }; 65 | } 66 | -------------------------------------------------------------------------------- /src/ExampleRenderer.ts: -------------------------------------------------------------------------------- 1 | /*! 2 | * ${copyright} 3 | */ 4 | 5 | import ResourceBundle from "sap/base/i18n/ResourceBundle"; 6 | import Core from "sap/ui/core/Core"; 7 | import RenderManager from "sap/ui/core/RenderManager"; 8 | import Example from "./Example"; 9 | import { ExampleColor } from "./library"; 10 | 11 | /** 12 | * Example renderer. 13 | * @namespace 14 | */ 15 | export default { 16 | apiVersion: 2, // usage of DOM Patcher 17 | 18 | /** 19 | * Renders the HTML for the given control, using the provided {@link RenderManager}. 20 | * 21 | * @param rm The reference to the sap.ui.core.RenderManager 22 | * @param control The control instance to be rendered 23 | */ 24 | render: function (rm: RenderManager, control: Example) { 25 | const i18n = Core.getLibraryResourceBundle("com.myorg.myui5lib") as ResourceBundle; 26 | 27 | rm.openStart("div", control); 28 | if (control.getColor() === ExampleColor.Highlight) { 29 | rm.class("myLibPrefixExampleHighlight"); 30 | } else { 31 | rm.class("myLibPrefixExample"); 32 | } 33 | rm.openEnd(); 34 | rm.text(`${i18n.getText("ANY_TEXT")}: ${control.getText()}`); 35 | rm.close("div"); 36 | } 37 | }; 38 | -------------------------------------------------------------------------------- /src/library.ts: -------------------------------------------------------------------------------- 1 | /*! 2 | * ${copyright} 3 | */ 4 | 5 | import ObjectPath from "sap/base/util/ObjectPath"; 6 | 7 | /** 8 | * Initialization Code and shared classes of library com.myorg.myui5lib. 9 | */ 10 | 11 | // delegate further initialization of this library to the Core 12 | // Hint: sap.ui.getCore() must still be used here to support preload with sync bootstrap! 13 | sap.ui.getCore().initLibrary({ 14 | name: "com.myorg.myui5lib", 15 | version: "${version}", 16 | dependencies: [ 17 | // keep in sync with the ui5.yaml and .library files 18 | "sap.ui.core" 19 | ], 20 | types: ["com.myorg.myui5lib.ExampleColor"], 21 | interfaces: [], 22 | controls: ["com.myorg.myui5lib.Example"], 23 | elements: [], 24 | noLibraryCSS: false // if no CSS is provided, you can disable the library.css load here 25 | }); 26 | 27 | // get the library object from global object space because all enums must be attached to it to be usable as UI5 types 28 | // FIXME: this line is planned to become obsolete and may need to be removed later 29 | const thisLib: { [key: string]: unknown } = ObjectPath.get("com.myorg.myui5lib") as { [key: string]: unknown }; 30 | 31 | /** 32 | * Semantic Colors of the com.myorg.myui5lib.Example control. 33 | * 34 | * @enum {string} 35 | * @public 36 | */ 37 | export enum ExampleColor { 38 | /** 39 | * Default color (brand color) 40 | * @public 41 | */ 42 | Default = "Default", 43 | 44 | /** 45 | * Highlight color 46 | * @public 47 | */ 48 | Highlight = "Highlight" 49 | } 50 | // FIXME: this line is planned to become obsolete and may need to be removed later 51 | thisLib.ExampleColor = ExampleColor; // add the enum to the library; this is important because UI5 otherwise cannot identify the type and will skip type checking for properties of this type 52 | 53 | // export the library namespace 54 | export default thisLib; 55 | -------------------------------------------------------------------------------- /src/messagebundle.properties: -------------------------------------------------------------------------------- 1 | # Translation file of library com.myorg.myui5lib. 2 | ANY_TEXT=Any Text 3 | -------------------------------------------------------------------------------- /src/themes/base/Example.less: -------------------------------------------------------------------------------- 1 | /* Theme Parameter Toolbox: https://openui5.hana.ondemand.com/test-resources/sap/m/demokit/theming/webapp/index.html */ 2 | 3 | .myLibPrefixExample, 4 | .myLibPrefixExampleHighlight { 5 | color: @sapUiText; 6 | background-color: @sapUiNeutralBG; 7 | border: 1rem solid @sapUiContentForegroundBorderColor; 8 | border-radius: 1rem; 9 | opacity: 0.8; 10 | padding: 2rem; 11 | margin: 2rem 8rem; 12 | text-align: center; 13 | font-size: 2em; 14 | line-height: 3em; 15 | } 16 | 17 | .myLibPrefixExampleHighlight { 18 | background-color: @sapUiSuccessBG; 19 | } 20 | -------------------------------------------------------------------------------- /src/themes/base/library.source.less: -------------------------------------------------------------------------------- 1 | @import "/resources/sap/ui/core/themes/base/base.less"; 2 | @import "/resources/sap/ui/core/themes/base/global.less"; 3 | 4 | @import "Example.less"; 5 | -------------------------------------------------------------------------------- /src/themes/sap_fiori_3/library.source.less: -------------------------------------------------------------------------------- 1 | @import "../base/library.source.less"; 2 | @import "/resources/sap/ui/core/themes/sap_fiori_3/base.less"; 3 | @import "/resources/sap/ui/core/themes/sap_fiori_3/global.less"; 4 | -------------------------------------------------------------------------------- /src/themes/sap_fiori_3_dark/library.source.less: -------------------------------------------------------------------------------- 1 | @import "../base/library.source.less"; 2 | @import "/resources/sap/ui/core/themes/sap_fiori_3_dark/base.less"; 3 | @import "/resources/sap/ui/core/themes/sap_fiori_3_dark/global.less"; 4 | -------------------------------------------------------------------------------- /src/themes/sap_fiori_3_hcb/library.source.less: -------------------------------------------------------------------------------- 1 | @import "../base/library.source.less"; 2 | @import "/resources/sap/ui/core/themes/sap_fiori_3_hcb/base.less"; 3 | @import "/resources/sap/ui/core/themes/sap_fiori_3_hcb/global.less"; 4 | -------------------------------------------------------------------------------- /src/themes/sap_fiori_3_hcw/library.source.less: -------------------------------------------------------------------------------- 1 | @import "../base/library.source.less"; 2 | @import "/resources/sap/ui/core/themes/sap_fiori_3_hcw/base.less"; 3 | @import "/resources/sap/ui/core/themes/sap_fiori_3_hcw/global.less"; 4 | -------------------------------------------------------------------------------- /src/themes/sap_horizon/library.source.less: -------------------------------------------------------------------------------- 1 | @import "../base/library.source.less"; 2 | @import "/resources/sap/ui/core/themes/sap_horizon/base.less"; 3 | @import "/resources/sap/ui/core/themes/sap_horizon/global.less"; 4 | -------------------------------------------------------------------------------- /src/themes/sap_horizon_dark/library.source.less: -------------------------------------------------------------------------------- 1 | @import "../base/library.source.less"; 2 | @import "/resources/sap/ui/core/themes/sap_horizon_dark/base.less"; 3 | @import "/resources/sap/ui/core/themes/sap_horizon_dark/global.less"; 4 | -------------------------------------------------------------------------------- /src/themes/sap_horizon_hcb/library.source.less: -------------------------------------------------------------------------------- 1 | @import "../base/library.source.less"; 2 | @import "/resources/sap/ui/core/themes/sap_horizon_hcb/base.less"; 3 | @import "/resources/sap/ui/core/themes/sap_horizon_hcb/global.less"; 4 | -------------------------------------------------------------------------------- /src/themes/sap_horizon_hcw/library.source.less: -------------------------------------------------------------------------------- 1 | @import "../base/library.source.less"; 2 | @import "/resources/sap/ui/core/themes/sap_horizon_hcw/base.less"; 3 | @import "/resources/sap/ui/core/themes/sap_horizon_hcw/global.less"; 4 | -------------------------------------------------------------------------------- /test/Example.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Test Page for com.myorg.myui5lib.Example 6 | 7 | 16 | 17 | 18 |

Test Page for com.myorg.myui5lib.Example

19 |
20 | 21 | 22 | -------------------------------------------------------------------------------- /test/Example.ts: -------------------------------------------------------------------------------- 1 | import { ExampleColor } from "com/myorg/myui5lib/library"; 2 | import Example from "com/myorg/myui5lib/Example"; 3 | 4 | // create a new instance of the Example control and 5 | // place it into the DOM element with the id "content" 6 | new Example({ 7 | text: "Example", 8 | color: ExampleColor.Highlight, 9 | press: (event) => { 10 | alert(event.getSource()); 11 | } 12 | }).placeAt("content"); 13 | -------------------------------------------------------------------------------- /test/qunit/Example.qunit.ts: -------------------------------------------------------------------------------- 1 | import { ExampleColor } from "com/myorg/myui5lib/library"; 2 | import Example from "com/myorg/myui5lib/Example"; 3 | 4 | // prepare DOM 5 | const elem = document.createElement("div"); 6 | elem.id = "uiArea1"; 7 | document.body.appendChild(elem); 8 | 9 | // module for basic checks 10 | QUnit.module("Example Tests"); 11 | 12 | // example sync test 13 | QUnit.test("Sync", function (assert) { 14 | assert.expect(1); 15 | assert.ok(true, "ok"); 16 | }); 17 | 18 | // example async test 19 | QUnit.test("Async", function (assert) { 20 | assert.expect(1); 21 | return new Promise(function (resolve /*, reject */) { 22 | assert.ok(true, "ok"); 23 | resolve(); 24 | }); 25 | }); 26 | 27 | // module for basic checks 28 | QUnit.module("Basic Control Checks"); 29 | 30 | // some basic control checks 31 | QUnit.test("Test get properties", function (assert) { 32 | assert.expect(2); 33 | const oExample = new Example({ 34 | text: "Example" 35 | }); 36 | assert.equal(oExample.getText(), "Example", "Check text equals 'Example'"); 37 | assert.equal(oExample.getColor(), ExampleColor.Default, "Check color equals 'Default'"); 38 | }); 39 | 40 | // some basic eventing check 41 | QUnit.test("Test click event", function (assert) { 42 | assert.expect(1); 43 | const oExample = new Example("example", { 44 | text: "Example", 45 | press: function () { 46 | assert.ok(true, "Event has been fired!"); 47 | } 48 | }).placeAt("uiArea1"); 49 | return new Promise(function (resolve /*, reject */) { 50 | setTimeout(function () { 51 | oExample.$().trigger(jQuery.Event("click")); 52 | resolve(); 53 | }, 100); 54 | }); 55 | }); 56 | -------------------------------------------------------------------------------- /test/qunit/testsuite.qunit.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | QUnit TestSuite for com.myorg.myui5lib 7 | 8 | 9 | 10 | 11 | -------------------------------------------------------------------------------- /test/qunit/testsuite.qunit.ts: -------------------------------------------------------------------------------- 1 | export default { 2 | name: "QUnit TestSuite for com.myorg.myui5lib", 3 | defaults: { 4 | bootCore: true, 5 | ui5: { 6 | libs: "sap.ui.core,com.myorg.myui5lib", 7 | theme: "sap_horizon", 8 | noConflict: true, 9 | preload: "auto" 10 | }, 11 | qunit: { 12 | version: 2, 13 | reorder: false 14 | }, 15 | sinon: { 16 | version: 4, 17 | qunitBridge: true, 18 | useFakeTimers: false 19 | }, 20 | module: "./{name}.qunit" 21 | }, 22 | tests: { 23 | // test file for the Example control 24 | Example: { 25 | title: "QUnit Test for Example", 26 | _alternativeTitle: "QUnit tests: com.myorg.myui5lib.Example" 27 | } 28 | } 29 | }; 30 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "module": "es2022", 4 | "moduleResolution": "node", 5 | "skipLibCheck": true, 6 | "allowJs": true, 7 | "strict": true, 8 | "strictNullChecks": false, 9 | "strictPropertyInitialization": false, 10 | "rootDir": "./", 11 | "paths": { 12 | "com/myorg/myui5lib/*": ["./src/*"] 13 | } 14 | }, 15 | "include": ["./src/**/*", "test/**/*"] 16 | } 17 | -------------------------------------------------------------------------------- /ui5-dist.yaml: -------------------------------------------------------------------------------- 1 | specVersion: "3.0" 2 | metadata: 3 | name: "com.myorg.myui5lib" 4 | type: library 5 | resources: 6 | configuration: 7 | paths: 8 | src: dist/resources/com/myorg/myui5lib/ 9 | test: dist/test-resources/com/myorg/myui5lib/ 10 | framework: 11 | name: OpenUI5 12 | version: "1.115.1" 13 | libraries: 14 | - name: sap.ui.core 15 | - name: themelib_sap_fiori_3 16 | - name: themelib_sap_horizon 17 | -------------------------------------------------------------------------------- /ui5-jsdoc.yaml: -------------------------------------------------------------------------------- 1 | specVersion: "3.0" 2 | metadata: 3 | name: "com.myorg.myui5lib" 4 | type: library 5 | builder: 6 | customTasks: 7 | - name: ui5-tooling-transpile-task 8 | afterTask: replaceVersion 9 | -------------------------------------------------------------------------------- /ui5.yaml: -------------------------------------------------------------------------------- 1 | specVersion: "3.0" 2 | metadata: 3 | name: "com.myorg.myui5lib" 4 | type: library 5 | framework: 6 | name: OpenUI5 7 | version: "1.115.1" 8 | libraries: 9 | - name: sap.ui.core 10 | - name: themelib_sap_fiori_3 11 | - name: themelib_sap_horizon 12 | builder: 13 | customTasks: 14 | - name: ui5-tooling-transpile-task 15 | afterTask: replaceVersion 16 | server: 17 | customMiddleware: 18 | - name: ui5-tooling-transpile-middleware 19 | afterMiddleware: compression 20 | - name: ui5-middleware-livereload 21 | afterMiddleware: compression 22 | --------------------------------------------------------------------------------