generator-stui5 v0.1.2
Super Template for UI5
Generates boilerplate for new UI5 projects.
Yeoman is a Node.js package for generating code projects from pre-defined templates known as generators. This project is a generator for starting UI5 projects.
People have written thousands of yeoman generators, and not just for JavaScript projects. You may find an existing one that suits your needs. See the full list at yeoman.io. There are a few UI5 generators (search UI5 in the search field) but none of them were to my taste, hence this one. Also, feel free to fork this and add your own enhancements, or make pull requests. See the section below on extending this generator.
Installation
- Install node from nodejs.org
- Install yeoman via npm:
npm install -g yo - Install this generator:
npm install -g generator-stui5
Usage
These instructions assume you've installed yo via npm and are running it from the command line.
Quick start
Screenshots below
1. Create a new directory for your project and cd into it
2. If you'd like to change the config from default, run yo stui5:config then edit the resulting .yo-rc.json file. If you're happy with the default settings, skip this step
3. Generate the app with yo stui5
Later you can add views with yo stui5:view <name> and fragments with yo stui5:fragment <name> where <name> is the name of the new view or fragment.
Create a new directory for your project and
cdinto it
Optional: edit default config with
yo stui5:config
Generate the main boilerplate with
yo stui5
Optional: add a view with
yo stui5:view <name>
Prompts
For prompts which offer a list (eg 'Single-Page', 'Master-Detail'), move the cursor onto the line with the selection and press enter.
Commands
Generator argument help: yo stui5 --help or yo stui5:subgen --help where subgen is one of the sub-generators available.
Although you can directly call any sub-generator included in this generator, some of them depend on config that is created by the top-level app generator.
| Sub-generator | Command, options | Description |
|---|---|---|
| stui5:config | yo stui5:config | Generate a default .yo-rc.json configuration file |
| stui5 | yo stui5 [namespace[, title]] | Generate a new UI5 app from scratch. Use namespace and title to avoid those questions in the prompt. |
| stui5:view | yo stui5:view <name> [, controllerName[, webappRoot]] | Add a view to an existing app, where <name> gets prepended to .view.xml for the view name |
| stui5:fragment | yo stui5:fragment <name>[, webappRoot] | Add a view to existing app. prepended to .fragment.xml |
Configuration
Yeoman uses a config file .yo-rc.json at the root directory of the project you're generating. If you find a specific configuration you like, keep a copy of the config file for use in future projects. Yeoman will generate a default config file in the current directory if it can't find one. Any mandatory parameters missing from the config file will be asked for at the command prompt when the generator is run.
Rather than requiring all of the config parameters via prompts, the generator uses the default config parameters defined in stui5:config. If you want to change any of the config parameters from the default values before running the main generator, yo stui5:config will generate a default .yo-rc.json which you can edit before running yo stui5 in the same directory.
| Config key | Default value | Description |
|---|---|---|
| bootstrap | '../../resources/sap-ui-core.js' | path to resource roots in index.html |
| firstViewName | "Initial" | the name of the first view to generate |
| webappRoot | "webapp" | path that will contain UI5 app files and folders, such as index.html, Component.js, view, controller etc |
| baseController | true | include a base controller? |
| baseControllerBody | false | include some commonly used helper functions in base controller? |
| formatter | true | include util/formatter.js? |
| mockserver | true | include a mockserver.js? |
| gitInit | true | initialise a git repository? |
| eslint | true | include .eslintrc? |
Extending
Yeoman
Writing a yeoman generator is pretty straight forward. There's a good tutorial at yeoman.io. You can either write your own generator or enhance this one (fork your own or open a pull request).
The simplest way to modify the generator is to change the files in the templates folders. Placeholder values inside <% tags are swapped out with values passed in from the index.js files of the corresponding sub-generator. For example, in view/templates/template.view.xml is a placeholder <%= viewName %>, which will be replaced by whatever the value of the viewName property in the writing method of view/index.js. These values will come from arguments or config, see the yeoman.io tutorial for more details.
In the index.js files of each sub-generator are methods called in sequence by Yeoman. This sequence is called the run loop and is worth familiarising yourself with if you plan on tinkering with the generator. The run loop methods are:
- initializing
- prompting
- configuring
- default
- writing
- conflicts
- install
- end
Sub-generators
The default sub-generator to be run (when yo stui5 is called) is the app generator, defined in /generators/app/index.js. When a sub-generator is called explicitly, the corresponding index file is used (for example /generators/view/index.js in the case of yo stui5:view). Sub-generators call other sub-generators via the composeWith method. For example, several sub-generators call the config sub-generator via composeWith('stui5:config').
Base generator and helper class
Yeoman generators inherit from yeoman-generator however some of the generators in this project inherit from generator-stui5.base which provide a couple of helper wrappers. There's also a bundle of static helper methods in scb-helper.
Ramda
This project uses Ramda. If you're unfamiliar with Ramda, checkout some of the introductions at ramdajs.com.
Files and templates
Working with the filesystem is implemented using mem-fs-editor which is accessible in the yeoman generator as this.fs.
The mem-fs-editor templating is implemented using ejs. The documentation is pretty concise but the best way to get used to it is to just look at some of the examples here. Search for <% in files to see example use of placeholders. The Base.controller template in stui5:core uses the ejs includes and scripting concepts.
Adding config options
Default parameters go in the defaults object in config/index.js. Mandatory parameters for which there is no default (such as namespace or title) should have a prompt and argument added, if the parameter isn't already available in the config file. Try to keep the number of prompts minimal for speed of use. If users want greater control over their config, they should use yo stui5:config and edit that. See the configuration section, above.
Contributors
- Oli Rogers, Bluefin Solutions (Gruntfile and continuous integration templates)
- Tiago Almeida, Bluefin Solutions (Unit test templates)
- Stuart Bell, Bluefin Solutions