DEV-159 - Getting issue details... STATUS
DEV-178 - Getting issue details... STATUS
Update
The PoCof setup tools has become a new Magnolia project. Here are its coordinates
Jira: https://git.magnolia-cms.com/scm/build/npm-jumpstart.git
GIT: https://git.magnolia-cms.com/projects/BUILD/repos/npm-jumpstart/browse (master [jetty+Magnolia web app ] and tomcat-bundle branches)
Jenkins: https://jenkins.magnolia-cms.com/job/build_npm-jumpstart/
Inspired by Tomáš's presentation at Lunch&Learn about Node.js and its package manager npmjs based module called CLI https://git.magnolia-cms.com/users/tgregovsky/repos/cli/browse.
Rationale
Goals
Provide an npm package for front-end devs to get started fast and develop painlessly (hopefully) with Magnolia and light development.
Benefits
- increased efficiency by automation of daily tasks (creation of page and component templates, assignment of components to pages, creation of dialogs associated with pages or components)
- reduce amount of possible spaces for errors (by generating common structures automatically, thus limiting possible errors to misspellings of component names or dialog fields added by user, but ensuring that structure is correct)
- lower entry barrier for becoming frontend developer using Magnolia (learning couple of commands to generate basic website structure vs. learning whole configuration structure for template definitions just to create first templates)
- additional, secondary benefit are
- further increases in effectivity of development due to reduced number of testing configuration cycles (due to lower number of errors)
- making learning advanced configuration simpler (by allowing frontend developers to inspect generated structures)
- ensuring better understanding of custom work within project teams (generated structures are always same no matter which developer generated them and encourage people to place additions at the same locations)
Constrains
- whatever structures and placements for the resulting artifacts are generated by scripts need to be aligned with the structures generated by npm magnolia-build & distribution scripts
- scripts need to operate correctly also when one chooses to not use npm for distribution (for small and internal projects)
Delivery timeframe
- Final version should be released with Magnolia 5.5 latest.
- Alpha version for the 2016 conference in Basel.
Solution
Scripts described below can be either installed as global and executed without need for npm run
prefix or just locally with it. In case of the local execution only, one need to have scripts defined in his package.json file.
Jumpstart
npm start
to download and start Magnolia initiallystart-magnolia
stop-magnolia
restart-magnolia
As part of start
operation, magnolia.properties
in downloaded and extracted instance are also adapted.
In case of existing installation of Magnolia it is possible to point scripts to it and start such existing installation (for users with custom locally-only available bundles).
Configuration of use of CE or EE instance of Magnolia is also possible by modification of package.json
file.
CLI
- creation of pages e.g.
add-page myHome
- creation of components e.g.
add-component myImage
- adding components availability to pages e.g.
add-component myImage available@sampleModule:pages/myHome@main
- adding autogenerated components to pages e.g.
add-component footer autogenerate@sampleModule:pages/myHome@footer
Future ideas
A custom command might allow users to download additional Magnolia modules as they come in need and place them automatically in
WEB-INF/lib
(well resolving dependencies in that case could be tricky or we need to limit this to downloading bundles that have all dependencies already packed).- short version of parameters for experts:
- availability: create-component textImage -a pages/myHome@main
- autogenerate: create-component textImage -g pages/myHome@main
Decisions
- include jumpstart part of the project
- do not use any other tools such as yeoman or gulp or others to avoid extra complexity
- none of the proposed solutions for install are ideal, explore yet another posibility. The one used by Tomas is closer to how other tools install (e.g. gulp) and should be prefered in absence of better ideas
- use
create-page
andcreate-component
instead ofadd-
add-availability
will stay as is- syntax change for parameters - use
--available
and--autogenerate
instead ofavailable@
- module name is optional (if not provided, current is assumed, when provided we look for other project on the same level where current project is (in the same folder), when not found, simply fail with reasonable message)
- examples of updated syntax:
- create-component image
- Add/create component template (will create component yaml file, component ftl and component dialog)
- create-component textImage --available [sampleModule:]pages/myHome@main
- Same as above plus will set this component available on 'myHome' page in 'main' area (if area or availability configuration doesn't exist's in 'myHome' page, will create it as well)
- create-component footer --autogenerate [sampleModule:]pages/myHome@footer
- Same as above, just will do 'autogeneration' instead of availability
- add-availability [mtk:components/]html [sampleModule:]pages/myHome@main
- Make component 'html' available at 'myHome' in 'main' area
- create-light-module [-p path/to/light-modules-root-folder] myModule
- Create a new light module structure with the standard Magnolia light dev structure
- create-component image
Outstanding
- Which bundle to use for jumpstart custom jetty or standard tomcat?
Next Steps
- Exploratory task for better install of cli jira@DEV-193
- Refactoring for new syntax jira@NPMCLI-8
- Refactoring to remove need for use of "sudo" jira@NPMCLI-5
- Refactoring to remove need for YAML->JSON->YAML conversion jira@NPMCLI-4
Experimenting with Node.js and npm
As I'm a newbie to Node.js I had first to get familiar with the new technology. The result of my trials and errors is the little module at https://git.magnolia-cms.com/users/fgrilli/repos/mgnl-light-dev-poc/browse https://git.magnolia-cms.com/projects/BUILD/repos/npm-jumpstart/browse
There are two flavours of the module on two different branches
- master: a module using Jetty + Magnolia community web app
- tomcat-bundle: a module using Magnolia's CE tomcat bundle
From the module's readme.txt
This is a PoC for a nodejs module (package) which installs and runs a Magnolia instance ready for light development. ... Run: - run "npm start". This will -- connect to Magnolia's public repository on Nexus and download Magnolia (see package.json) -- extract Magnolia -- change some magnolia.properties (again see package.json) -- start up Magnolia Custom commands: - Apart from the standard npm commands corresponding to the phases of a package lifecycle, e.g. install, start, etc. this module provides these additional commands -- start-magnolia, usage "npm run start-magnolia" -- stop-magnolia, usage "npm run stop-magnolia" -- restart-magnolia, usage "npm run restart-magnolia"