• Super Template for UI5
• Installation
• Usage
  • Quick start
  • Prompts
  • Commands
  • Configuration
• Extending
  • Yeoman
  • Sub-generators
  • Base class and helper class
  • Ramda
  • Files and templates
  • Adding config options
• Contributors:

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

1. 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.

1. Create a new directory for your project and cd into it

2. Optional: edit default config with yo stui5:config

3. Generate the main boilerplate with yo stui5

4. 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