You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This generator uses the Yeoman scaffolding tool to let you quickly create a [Mendix widget](https://world.mendix.com/display/public/howto50/Custom+Widget+Development) based on the latest [AppStoreWidgetBoilerPlate](https://github.com/mendix/AppStoreWidgetBoilerplate).
9
+
This generator uses the Yeoman scaffolding tool to let you quickly create a [Mendix widget](https://world.mendix.com/display/public/howto50/Custom+Widget+Development) based on the latest [AppStoreWidgetBoilerPlate](https://github.com/mendix/AppStoreWidgetBoilerplate). You can either use the full boilerplate with example code, or choose to use an empty widget.
10
10
11
-
### Prerequisites (you only have to do this ONCE)
11
+
If you want to see a short demo (this uses the older 1.x widget generator and only Grunt), please look at our [webinar](http://ww2.mendix.com/expert-webinar-developing-widgets.html)
12
12
13
-
First, you need to have NodeJs installed. After that, you need to install Yeoman, Mendix Widget generator and Grunt:
13
+
---
14
+
15
+
## Prerequisites _(you only have to do this once)_
16
+
17
+
First, you need to have [Node.js](https://nodejs.org/en/) installed. (We recommend a 4.x LTS version, the widget is tested against version 4 to 6). After that, you need to install Yeoman and the Mendix Widget generator:
18
+
19
+
Open a command-line window (Press Win+R and type ``cmd`` or use Powershell)
14
20
15
21
```bash
16
-
npm install -g yo generator-mendix grunt-cli
22
+
npm install -g yo generator-mendix
17
23
```
18
24
19
-
Make sure you have the latest version of ``yo``. The version we work with currently is 1.8.3 (which you can check by running ``yo --version``)
25
+
Make sure you have the latest version of ``yo``. The version we work with currently is 1.8.5 (which you can check by running ``yo --version``)
26
+
27
+
Next, based on your preference, you need to install either Gulp (**recommended**) or Grunt. Install this by typing:
20
28
21
-
### Usage
29
+
```bash
30
+
# If you want to use Gulp, run:
31
+
32
+
npm install -g gulp-cli
22
33
23
-
##### 1.) Start the generator in the folder you want to create a widget:
34
+
# If you want to use Grunt, run:
35
+
36
+
npm install -g grunt-cli
37
+
38
+
```
39
+
40
+
---
41
+
42
+
## Scaffold a widget
43
+
44
+
### 1. Start the generator in the folder you want to create a widget
24
45
25
46
```bash
26
47
yo mendix
27
48
```
28
49
29
-
##### 2.) The generator will ask you to provide the following information about your widget:
50
+
### 2. Provide the following information about your widget:
51
+
52
+
The following information needs to be provided about your widget:
30
53
31
54
* name
32
55
* description
@@ -36,72 +59,137 @@ yo mendix
36
59
* author
37
60
* Github username (optional)
38
61
39
-
##### 3.) Your widget will be created using the options and the boilerplate.
62
+
You can press \<Enter\> if you want to use the default values.
40
63
41
-
It will clone the boilerplate, rename your widget according to the options. It also includes a ``Gruntfile.js`` and ``package.json`` for development purposes (see below)
64
+
### 3.1. Which task runner do you want to use?
42
65
43
-
###Grunt
66
+
#### Gulp
44
67
45
-
The generator will include Grunt to automate your widget development. [Make sure you have Grunt installed](http://gruntjs.com/getting-started).
68
+
The widget generator will include a **Gulpfile.js** and the necessary package.json for running Gulp tasks. We recommend using Gulp because of the speed.
46
69
47
-
The following Grunt tasks can be started by typing ``grunt <TASKNAME>``:
70
+
#### Grunt
48
71
49
-
*``start-modeler``
72
+
Earlier versions of the widget generator added Grunt as the default taskrunner. We included this option as well if you want to use this.
50
73
51
-
This will try to open the Modeler using the included test-project. (Older versions of the Gruntfile will use``grunt start-mendix``)
74
+
### 3.2. Which template do you want to use?
52
75
53
-
*``watch`` (this is actually an alias for default, so you can run ``grunt`` without adding this taskname)
76
+
#### AppStoreWidgetBoilerplate
54
77
55
-
This watches for changes in your ``src`` folder. When a file is changed, it copies the change to the deployment-folder (so you do not have to restart your project when changing files **(with the exception of ``.xml`` files)**). It also automatically creates a ``.mpk`` file in your ``/dist``and ``test/widgets`` folder.
78
+
This uses the standard boilerplate which is on Github. This is recommended if you are a beginner. It includes example code with jQuery*and templates.
56
79
57
-
*``version``
80
+
#### Empty widget
58
81
59
-
This will let you set the version of your widget, the ``package.xml``, without editing it yourself.
82
+
The empty widget will use a slim version of the AppStoreWidgetBoilerplate. It only provides the essential methods and setup. Furthermore, it will ask you if you want to use templates and jQuery*.
60
83
61
-
*``folders``
84
+
\***We do not recommend using jQuery in your widgets, please [read this issue](https://github.com/mendix/AppStoreWidgetBoilerplate/issues/38). For simple DOM-manipulation you can use Dojo, which is provided by Mendix. Only use jQuery when you need it for certain external libraries that depend on it.**
85
+
86
+
---
87
+
88
+
## Use a taskrunner for development
89
+
90
+
The widget generator will scaffold a widget for you. It provides a convenient setup to develop you widget and publish it on Github. To make it even more easy, we add files for taskrunners.
91
+
92
+
93
+
### Gulp
94
+
95
+
The following tasks are provided in the **Gulpfile.js** and can be started by running ``gulp <TASKNAME>`` or ``npm run <TASKNAME>``:
96
+
97
+
*``default``
62
98
63
-
Grunt uses the settings in package.json to determine which folders it uses. If, for example, you use this to develop a widget in your project, you can change the folder in package.json:
99
+
You can omit this taskname and just run ``gulp``. This will watch for any changes in your ``src`` directory. If a change occurs, it will automatically create a new **MPK** and copy this to your ``widgets`` directory.
100
+
101
+
It will also copy any changed Javascript files to your deployment folder. This means you do not have to redeploy locally, you can just refresh your browser. For changes in ``XML`` or ``CSS`` you will still need to synchronize your project directory (press F4 in the modeler) and redeploy.
102
+
103
+
*``modeler``
104
+
105
+
This will try to start the test-project that is included in the ``test`` folder. It automatically opens the Modeler with this project. If you have your test-project in a different location, you can change the following options in ``package.json``:
64
106
65
107
```json
66
-
...
108
+
"paths": {
67
109
"testProjectFolder": "./test/",
68
-
...
110
+
"testProjectFileName": "Test.mpr"
111
+
},
69
112
```
70
113
71
-
and then check if the path is correct by running the ``grunt folders`` task
114
+
Note: If you provide a different path to the test-project in Windows, make sure you escape backslashes. So for example: ```C:\Projects\TestFolder``` needs to be properly written in the JSON as:
115
+
116
+
```json
117
+
"testProjectFileName": "C:\\Projects\\TestFolder"
118
+
```
119
+
120
+
*``version``
121
+
122
+
This task will show you the version number of the widget by reading the ``packages.xml`` file. You can set the version number with this task by typing:
123
+
124
+
``gulp version -n=X.X.X`` or ``npm run version -- -n=X.X.X``
125
+
126
+
*``folders``
127
+
128
+
This will tell you which folders Gulp is using. You can change the folder of the test-project folder (See ``modeler`` task)
72
129
73
130
*``build``
74
131
75
-
Cleans old ``.mpk`` files and creates a new one in your ``/dist``and ``test/widgets`` folder
132
+
This will build the widget for you. It will output a new **MPK** file to both your ``dist``folder, as well as the ``widgets`` folder in your test-project directory.
76
133
77
-
*``csslint``
134
+
*``icon``
78
135
79
-
Lints through all CSS files that are in the ``widget/ui`` folder and checks for errors
136
+
This task will read the ``icon.png`` file (or any other image file if you provide the task a filename using ``gulp icon --file=<filename>``) and outputs a base64 string that you can use in your widget.xml.
80
137
81
-
### Using Grunt in a widget respository/project you downloaded.
82
138
83
-
If you download or clone one of our repositories that has a ``Gruntfile.js`` and ``package.json`` included, you need to install the dependencies first to be able to run Grunt:
139
+
### Grunt
84
140
85
-
1. Make sure you open the root folder in your command-line/terminal window
86
-
2. Run ``npm install`` to install the dependencies
87
-
3. Now you can use the Grunt tasks as described in the previous point
141
+
The tasks that are provided by Gulp are also provided in the **Gruntfile.js**. The following tasks are configured:
88
142
89
-
### Grunt can be started from command-line, or used by Grunt-plugins for different IDE's:
* NetBeans (has [built-in support for Grunt](https://blogs.oracle.com/geertjan/entry/grunting_in_netbeans_ide))
150
+
\*This task can only read ``icon.png``, but it will automatically set the base64 string in your widget.xml for you.
96
151
97
-
## TODO:
152
+
---
98
153
99
-
* Gulp integration
100
-
* Add JSHint (Grunt/Gulp)
154
+
## Use a taskrunner in an existing widget
155
+
156
+
*_My widget repository does not have a ``Gruntfile.js`` or ``Gulpfile.js``._
157
+
158
+
We thought about that. Make sure you open a command-line terminal in your widget repository. It needs at least the widget files in the ``src`` folder. By simply running the generator there, it will ask you if you want to install a taskrunner. It also needs two parameters (widget name and version number) that it tries to read from the package.xml and widget.xml
159
+
160
+
*_My widget repository contains a package.json and ``Gruntfile.js`` or ``Gulpfile.js``_
161
+
162
+
Great! If you have made sure you have Grunt/Gulp installed (See above, prerequisites), you can start using it. The only thing you need to do is install the dependencies for the different tasks. Run the same folder:
163
+
164
+
```bash
165
+
npm install
166
+
```
167
+
168
+
Now you can use the Grunt/Gulp tasks as described.
169
+
170
+
---
101
171
102
172
## Troubleshooting
103
173
174
+
*_I get an error that it cannot find a dependency or local Grunt/Gulp._
175
+
176
+
Did you make sure you have the dependencies installed? Run ``npm install`` in your widget folder (it needs to have a package.json and **Gulpfile.js**/**Gruntfile.js**)
177
+
178
+
*_Some of the tasks cannot be found_
104
179
180
+
Check the version of your **Gruntfile.js**/**Gulpfile.js** (stated in the top of the file). The tasks described here are written for the 2.0 version of the widget generator. Any previous versions are outdated. If you run the widget generator in your widget folder again, it will update the file and dependencies for you.
181
+
182
+
*_I am getting weird errors_
183
+
184
+
Please report your issues [here](https://github.com/mendix/generator-mendix/issues). and we'll troubleshoot together with you.
0 commit comments