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