Skip to content

Latest commit

 

History

History
311 lines (263 loc) · 9.92 KB

README.md

File metadata and controls

311 lines (263 loc) · 9.92 KB
Raw

generator-exist

NPM version Node.js CI semantic-release Codacy Badge

exist app scaffolding

Let Yeoman take care of creating directory and file scaffolds for different types of exist-db EXpath packages. Just answer the prompts about what you want to build, and a sensible directory structure with fully configured readmes, buildfiles, etc will be set up for you.

No more manual closing of html5 tags, inserting app names into config files, or wondering if you actually increase the version number in all the places.

Installation

First, install Yeoman and generator-exist using npm (we assume you have pre-installed node.js).

From GitHub

To install a pre-release version:

npm i -g yo@4
npm i -g git://github.com/eXist-db/generator-exist.git

Official release

To install a version published to npm:

npm i -g yo@4
npm i -g @existdb/generator-exist

From Source

Alternatively, if you have cloned this repo from GitHub. You can symlink your local clone into your global node environment. This is particularly useful during development. From inside the folder with the cloned repo:

npm install -g yo@4
npm i
npm link

In case the above doesn't work use:

yo PATH/TO/generator-exist

from inside the directory where you want to run the local copy of the generator.

Using the Generator

Then generate your new project: Create a new project folder and navigate to it in you CLI.

mkdir myApp
cd myApp

Then run the generator:

  • If you installed from a fork or from GitHub.

    yo exist

  • If you installed from npm or from a clone of this repo.

    yo @existdb/exist

If you are unsure about which command is right simply run yo to see the list of currently installed generators.

asciicast

Note: If you told yeoman to use Github for your new project, your project will start initialized with all files added, out of the box.

Some of the answers, such as username will be stored after the initial run of the generator. So you only have to type them once.

The Scaffold

The generator creates sensible default structures for expath packages for exist-db, which includes default folders for xquery code, meta-data files, html, etc. modelled on eXide's package generation scripts. In addition there are optional features such as dockerfile, CI scripts, github templates, secure area, … depending on the options selected by the user. The idea is that if you select e.g. to include a secure area in your application from the start, the files will contain the necessary parts, after the intial run of the generator. Saving you from having to manualy add sections, or repeatedly providing the same information over and over agian. There are 4 basic app types.

  • exist-design
  • plain
  • empty
  • xquery library

Since if would be impractical to go through all possible combinations of option here are some sample scaffolds created with the generator.

exist-design (with. secure area selected)

├── Dockerfile
├── LICENSE
├── README.md
├── admin
│   ├── controller.xq
│   ├── index.html
│   └── security.html
├── build
│   ├── exide_demo-1.0.0-dev.xar
│   └── exide_demo-1.0.0.xar
├── build.xml
├── collection.xconf
├── controller.xq
├── cypress.config.js
├── error-page.html
├── expath-pkg.xml
├── icon.png
├── index.html
├── modules
│   ├── app.xqm
│   ├── config.xqm
│   └── view.xql
├── node_modules
│   └── pruned …
├── package-lock.json
├── package.json
├── post-install.xq
├── pre-install.xq
├── repo.xml
├── reports
│   ├── screenshots
│   └── videos
├── resources
│   ├── css
│   │   └── style.css
│   └── images
│       ├── bgmenu.gif
│       ├── bgmenuhi.gif
│       ├── body-base.gif
│       ├── body.gif
│       ├── bold.gif
│       ├── code.gif
│       ├── delete-icon.png
│       ├── existdb.png
│       ├── glyphicons-halflings.png
│       ├── grey-box-bot.gif
│       ├── grey-box-rpt.gif
│       ├── grey-box-top.gif
│       ├── header.gif
│       ├── horizontal.gif
│       ├── italic.gif
│       ├── nav-dropdown.gif
│       ├── nav-dropdown.png
│       ├── nav.gif
│       └── page-edit-icon.png
├── templates
│   ├── login-panel.html
│   └── page.html
└── test
    ├── cypress
    │   ├── fixtures
    │   │   └── example.json
    │   ├── e2e
    │   │   ├── landing.cy.js
    │   │   ├── login-fail_spec.js
    │   │   └── login-ok_spec.js
    │   └── support
    │       ├── commands.js
    │       └── e2e.js
    ├── mocha
    │   ├── app_spec.js
    │   └── rest_spec.js
    └── xqs
        ├── test-runner.xq
        ├── test-suite.xqm
        └── xqSuite.js

plain (with most options)

├── LICENSE
├── README.md
├── build
│   ├── plain_demo-1.0.0-dev.xar
│   └── plain_demo-1.0.0.xar
├── build.xml
├── collection.xconf
├── controller.xq
├── cypress.config.js
├── error-page.html
├── expath-pkg.xml
├── icon.png
├── index.html
├── modules
│   ├── app.xqm
│   ├── config.xqm
│   └── view.xql
├── node_modules
│   └── pruned …
├── package-lock.json
├── package.json
├── post-install.xq
├── pre-install.xq
├── repo.xml
├── reports
│   ├── screenshots
│   └── videos
├── resources
│   └── css
│       └── style.css
├── templates
│   └── page.html
└── test
    ├── cypress
    │   ├── fixtures
    │   │   └── example.json
    │   ├── e2e
    │   │   └── landing.cy.js
    │   └── support
    │       ├── commands.js
    │       └── e2e.js
    ├── mocha
    │   ├── app_spec.js
    │   └── rest_spec.js
    └── xqs
        ├── test-runner.xq
        ├── test-suite.xqm
        └── xqSuite.js

empty (without extras)

├── LICENSE
├── build
│   ├── empty_demo-1.0.0-dev.xar
│   └── empty_demo-1.0.0.xar
├── build.xml
├── cypress.config.js
├── expath-pkg.xml
├── icon.png
├── node_modules
│   └── pruned …
├── package-lock.json
├── package.json
├── repo.xml
├── reports
│   ├── screenshots
│   └── videos
└── test
    ├── cypress
    │   ├── fixtures
    │   │   └── example.json
    │   ├── e2e
    │   │   └── landing.cy.js
    │   └── support
    │       ├── commands.js
    │       └── e2e.js
    ├── mocha
    │   ├── app_spec.js
    │   └── rest_spec.js
    └── xqs
        ├── test-runner.xq
        ├── test-suite.xqm
        └── xqSuite.js

xquery library

├── LICENSE
├── README.md
├── build
│   ├── lib_demo-1.0.0-dev.xar
│   └── lib_demo-1.0.0.xar
├── build.xml
├── expath-pkg.xml
├── node_modules
│   └── pruned …
├── package-lock.json
├── package.json
├── post-install.xq
├── pre-install.xq
├── repo.xml
└── test
    ├── mocha
    │   ├── app_spec.js
    │   └── rest_spec.js
    └── xqs
        ├── test-runner.xq
        ├── test-suite.xqm
        └── xqSuite.js

Development

If you want to contribute another template or option, please take a look at the issue tracker. Pull request are always welcome. This generator uses mocha for unit testing. Please make sure to add tests when opening a PR.

This application uses Angular Commit Message Conventions to determine semantic versioning of releases, please adhere to these conventions, like so:

Commit message Release type
fix(pencil): stop graphite breaking when too much pressure applied Patch Release
feat(pencil): add 'graphiteWidth' option Minor Feature Release
perf(pencil): remove graphiteWidth option

BREAKING CHANGE: The graphiteWidth option has been removed.
The default graphite width of 10mm is always used for performance reasons.		 Major Breaking Release

License

MIT © Duncan Paterson