|
| 1 | + |
| 2 | + |
| 3 | +# UI5 Build Extensibility |
| 4 | + |
| 5 | +The UI5 Tooling enables it to define a custom build for your UI5 project by adding additional tasks to the [standard task list](https://github.com/SAP/ui5-builder/blob/master/README.md#tasks). |
| 6 | + |
| 7 | +## Configuration |
| 8 | + |
| 9 | +The additional build tasks can be defined in the project configuration within the `ui5.yaml` file. |
| 10 | + |
| 11 | +### Example: Configuration of project 'my.library' |
| 12 | + |
| 13 | +````yaml |
| 14 | +--- |
| 15 | +# In this example configuration two custom tasks are defined: 'babel' and 'generateMarkdownFiles'. |
| 16 | +specVersion: "0.1" |
| 17 | +type: library |
| 18 | +metadata: |
| 19 | + name: my.library |
| 20 | +builder: |
| 21 | + customTasks: |
| 22 | + - name: babel |
| 23 | + beforeTask: generateComponentPreload |
| 24 | + - name: generateMarkdownFiles |
| 25 | + afterTask: uglify |
| 26 | + configuration: |
| 27 | + color: blue |
| 28 | +```` |
| 29 | + |
| 30 | +In the above example, when building the library `my.library` the `babel` task will be executed before the standard task `generateComponentPreload`. Another custom task called `generateMarkdownFiles` is then executed immediatly after the standard task `ugilfy`. |
| 31 | + |
| 32 | +### Example: Connect multiple custom tasks |
| 33 | + |
| 34 | +You can also connect multiple custom task with eachother. If you do, please be aware that the order of your definitions is important. You have to make sure that the task is defined before you set it as `beforeTask` or `afterTask`. |
| 35 | + |
| 36 | +````yaml |
| 37 | +--- |
| 38 | +# In this example 'myCustomTask2' gets executed after 'myCustomTask1'. |
| 39 | +specVersion: "0.1" |
| 40 | +type: library |
| 41 | +metadata: |
| 42 | + name: my.library |
| 43 | +builder: |
| 44 | + customTasks: |
| 45 | + - name: myCustomTask1 |
| 46 | + beforeTask: generateComponentPreload |
| 47 | + - name: myCustomTask2 |
| 48 | + afterTask: myCustomTask1 |
| 49 | +```` |
| 50 | + |
| 51 | +## Custom Task Extension |
| 52 | + |
| 53 | +A custom task extension consists of a `ui5.yaml` and a task implementation. |
| 54 | + |
| 55 | +### ui5.yaml |
| 56 | + |
| 57 | +````yaml |
| 58 | +--- |
| 59 | +specVersion: "0.1" |
| 60 | +kind: extension |
| 61 | +type: task |
| 62 | +metadata: |
| 63 | + name: generateMarkdownFiles |
| 64 | +task: |
| 65 | + path: lib/tasks/generateMarkdownFiles.js |
| 66 | +```` |
| 67 | + |
| 68 | +### lib/tasks/generateMarkdownFiles.js |
| 69 | + |
| 70 | +````javascript |
| 71 | +// Task implementation |
| 72 | +const markdownGenerator = require("./markdownGenerator"); |
| 73 | + |
| 74 | +module.exports = function({workspace, options}) { |
| 75 | + return workspace.byGlob("**/*.txt") |
| 76 | + .then((textResources) => { |
| 77 | + return markdownGenerator({ |
| 78 | + resources: textResources |
| 79 | + }); |
| 80 | + }) |
| 81 | + .then((markdownResources) => { |
| 82 | + return Promise.all(markdownResources.map((resource) => { |
| 83 | + return workspace.write(resource); |
| 84 | + })); |
| 85 | + }); |
| 86 | +}; |
| 87 | +```` |
| 88 | + |
| 89 | +Task extensions can be **standalone modules** which are then handled as dependencies. |
| 90 | + |
| 91 | +On the other hand you can implement a task extension as **part of your project** itself. In that case, the configuration of the extension is part of your project configuration inside the `ui5.yaml` as shown below. |
| 92 | + |
| 93 | +The task extension will then be automatically collected and processed during the processing of the project. |
| 94 | + |
| 95 | +### Example |
| 96 | + |
| 97 | +````yaml |
| 98 | +# ui5.yaml configuration for the above example |
| 99 | + |
| 100 | +specVersion: "0.1" |
| 101 | +kind: project |
| 102 | +type: library |
| 103 | +metadata: |
| 104 | + name: my.library |
| 105 | +builder: |
| 106 | + customTasks: |
| 107 | + - name: generateMarkdownFiles |
| 108 | + afterTask: uglify |
| 109 | + configuration: |
| 110 | + color: blue |
| 111 | +--- |
| 112 | +# Task extension as part of your project |
| 113 | +specVersion: "0.1" |
| 114 | +kind: extension |
| 115 | +type: task |
| 116 | +metadata: |
| 117 | + name: generateMarkdownFiles |
| 118 | +task: |
| 119 | + path: lib/tasks/generateMarkdownFiles.js |
| 120 | +```` |
| 121 | + |
| 122 | +## Task Implementation |
| 123 | + |
| 124 | +A custom task implementation needs to return a function with the following signature: |
| 125 | + |
| 126 | +````javascript |
| 127 | +/** |
| 128 | + * Custom task example |
| 129 | + * |
| 130 | + * @param {Object} parameters Parameters |
| 131 | + * @param {DuplexCollection} parameters.workspace DuplexCollection to read and write files |
| 132 | + * @param {AbstractReader} parameters.dependencies Reader or Collection to read dependency files |
| 133 | + * @param {Object} parameters.options Options |
| 134 | + * @param {string} parameters.options.projectName Project name |
| 135 | + * @param {string} [parameters.options.configuration] Task configuration if given in ui5.yaml |
| 136 | + * @returns {Promise<undefined>} Promise resolving with undefined once data has been written |
| 137 | + */ |
| 138 | +module.exports = function({workspace, options}) { |
| 139 | + // [...] |
| 140 | +}; |
| 141 | +```` |
0 commit comments