From 2f9e03ec22b9376b098fa6a43dbecc20dcf7343c Mon Sep 17 00:00:00 2001 From: Ingo Schommer Date: Tue, 3 May 2016 08:52:18 +1200 Subject: [PATCH 1/3] Mention ReactJS vs. entwine in docs https://silverstripe.atlassian.net/browse/OSS-1691 --- .../15_Customising_the_Admin_Interface/index.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/index.md b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/index.md index a721db394..d8a36925e 100644 --- a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/index.md +++ b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/index.md @@ -2,12 +2,17 @@ title: Customising the Admin Interface summary: Extend the admin view to provide custom behavior or new features for CMS and admin users. introduction: The Admin interface can be extended to provide additional functionality to users and custom interfaces for managing data. -The Admin interface is bundled within the SilverStripe Framework but is most commonly used in conjunction with the `CMS` +The Admin interface is bundled within the SilverStripe Framework but is most commonly used in conjunction with the `cms` module. The main class for displaying the interface is a specialized [api:Controller] called [api:LeftAndMain], named as it is designed around a left hand navigation and a main edit form. +Starting with SilverStripe 4, the user interface logic is transitioned from +jQuery and [jQuery.entwine](https://github.com/hafriedlander/jquery.entwine), +which is replaced with [ReactJS](http://reactjs.com/). The transition is +done iteratively, starting with `AssetAdmin` and `CampaignAdmin`. + [CHILDREN] ## How to's -[CHILDREN Folder="How_Tos"] \ No newline at end of file +[CHILDREN Folder="How_Tos"] From 32bfc3853a8b4f02a071696df6a9911c6804897b Mon Sep 17 00:00:00 2001 From: David Craig Date: Wed, 4 May 2016 16:02:49 +1200 Subject: [PATCH 2/3] Update client-side build tooling docs --- docs/en/05_Contributing/01_Code.md | 178 +++++++++++++++++++++-------- 1 file changed, 132 insertions(+), 46 deletions(-) diff --git a/docs/en/05_Contributing/01_Code.md b/docs/en/05_Contributing/01_Code.md index d083d5cdc..343e10f0e 100644 --- a/docs/en/05_Contributing/01_Code.md +++ b/docs/en/05_Contributing/01_Code.md @@ -263,97 +263,170 @@ Helpful hint: You can always edit your last commit message by using: $ git commit --amend -## Working with client-side dependencies +## Client-side build tooling -From time to time client-side dependencies like jQuery need to be upgraded, added, or removed. We have some tools for dealing with that. Note this only applies to core SilverStripe dependencies, you're free to to manage dependencies in your project codebase however you like. +Core JavaScript, CSS, and thirdparty dependencies are managed with the build tooling +described below. + +Note this only applies to core SilverStripe dependencies, you're free to manage +dependencies in your project codebase however you like. ### Node.js -The [Node.js](https://nodejs.org) JavaScript runtime is the foundation of our client-side build tool chain. If you want to do things like upgrade, add, or remove libraries, you'll need Node installed on your dev environment. Our build tooling supports the v4.2.x (LTS) version of Node. +The [Node.js](https://nodejs.org) JavaScript runtime is the foundation of our client-side +build tool chain. If you want to do things like upgrade dependencies, make changes to core +JavaScript or SCSS files, you'll need Node installed on your dev environment. Our build +tooling supports the v4.2.x (LTS) version of Node. + +You'll likely want to manage multiple versions of Node, we suggest using +[Node Version Manager](https://github.com/creationix/nvm). ### npm -[npm](https://www.npmjs.com/) is the package manager we use for JavaScript libraries. It comes bundled with Node.js so should already have it installed if you have Node. +[npm](https://www.npmjs.com/) is the package manager we use for JavaScript dependencies. +It comes bundled with Node.js so should already have it installed if you have Node. -The configuration for an npm package goes in `package.json`. You'll see one in the root directory of `framework`. As well as being used for defining dependencies and basic package information, the `package.json` file has some handy scripts. +The configuration for an npm package goes in `package.json`. You'll see one in the root +directory of `framework`. As well as being used for defining dependencies and basic package +information, the `package.json` file has some other handy features. + +#### npm scripts + +The `script` property of a `package.json` file can be used to define command line scripts. +A nice thing about running commands from an npm script is binaries located in +`node_modules/.bin/` are temporally added to your `$PATH`. This means we can use dependencies +defined in `package.json` for things like compiling JavaScript and SCSS, and not require +developers to install these tools globally. This means builds are much more consistent +across development environments. + +For more info on npm scripts see +[https://docs.npmjs.com/misc/scripts](https://docs.npmjs.com/misc/scripts) + +To run an npm script, open up your terminal, change to the directory where `package.json` +is located, and run `$ npm run `. Where `` is the name of the +script you wish to run. + +Here are the scripts which are available in `framework` + +Note you'll need to run an `npm install` to download the dependencies required by these scripts. + +##### build ``` -$ npm run bundle +$ npm run build ``` -`bundle` generates the lib and leftandmain JavaScript bundles. +Runs a Gulp task which builds the core JavaScript files. You will need to run this script +whenever you make changes to a JavaScript file. + +Run this script with the `--development` flag to watch for changes in JavaScript files +and automatically trigger a rebuild. + +##### lint ``` -$ npm run thirdparty +$ npm run lint ``` -`thirdparty` copies JavaScript files from the `node_modules` directory into the `thirdparty` directory. The `node_modules` directory is not part of source control, so you'll need to run this command if you have upgraded, or added a module. +Run `eslint` over JavaScript files reports errors. -``` -$ npm run sanity -``` - -`sanity` makes sure files in `thirdparty` match files copied from `node_modules`. You should never commit custom changes to a library file. This script will catch them if you do :smile: +##### test ``` $ npm run test ``` -This script runs the JavaScript unit tests. +Runs the JavaScript unit tests. + +##### coverage ``` $ npm run coverage ``` -This script generates a coverage report for the JavaScript unit tests. The report is generated in the `coverage` directory. +Generates a coverage report for the JavaScript unit tests. The report is generated +in the `coverage` directory. + +##### css ``` $ npm run css ``` -`css` will compile all of the .scss files into minified .css files. ProTip: run with the `--development` flag to compile non-minified css and watch for every time a .scss file is changed. +Compile all of the .scss files into minified .css files. Run with the `--development` flag to +compile non-minified CSS and watch for every time a .scss file is changed. + +##### sprites ``` $ npm run sprites ``` -`sprites` generates sprites from the individual image files in `admin/images/sprites/src`. +Generates sprites from the individual image files in `admin/images/sprites/src`. + +##### thirdparty + +``` +$ npm run thirdparty +``` + +Copies legacy JavaScript dependencies from `node_modules` into the `thirdparty` directory. +This is only required legacy dependencies which are not written as CommonJS or ES6 modules. +All other modules will be included automatically with the `build` script. + +##### sanity + +``` +$ npm run sanity +``` + +Makes sure files in `thirdparty` match files copied from `node_modules`. You should never commit +custom changes to a library file. This script will catch them if you do :smile: + +##### lock ``` $ npm run lock ``` -`lock` generates a "shrinkwrap" file containing all npm package versions and writes it to `npm-shrinkwrap.json`. -Run this command whenever a new package is added to `package.json`, or when updating packages. -Commit the resulting `npm-shrinkwrap.json`. This uses -a third party [npm-shrinkwrap](https://github.com/uber/npm-shrinkwrap) library +Generates a "shrinkwrap" file containing all npm package versions and writes it to +`npm-shrinkwrap.json`. Run this command whenever a new package is added to `package.json`, +or when updating packages. Commit the resulting `npm-shrinkwrap.json`. This uses a third party +[npm-shrinkwrap](https://github.com/uber/npm-shrinkwrap) library since the built-in `npm shrinkwrap` (without a dash) has proven unreliable. -Of course to run these scripts, you'll need to get the dependencies, so run a `npm install` from the root directory to get started. - ### Gulp -[Gulp](http://gulpjs.com/) is the build system which gets invoked when you run npm scripts in SilverStripe. All npm scripts have a corresponding Gulp task which you can find in `gulpfile.js`. +[Gulp](http://gulpjs.com/) is the build system which gets invoked by most npm scripts +in SilverStripe. The `gulpfile.js` script is where Gulp tasks are defined. -## Working with core JavaScript +Here are the Gulp tasks which are defined in `gulpfile.js` -Core JavaScript is managed by the same build tool chain as [client-side dependencies](#working-with-client-side-dependencies). Source file are located `javascript/src` directories, these are the files you should edit. Source files are input for the build tooling, which outputs distributions files, located in `javascript/dist` directories. +#### build -There are two parts of the build tooling which are important to understand when working with core JavaScript files. +This is where JavaScript files are compiled and bundled. There are two parts to this which +are important to understand when working core JavaScript files. -### Babel +##### Babel -[Babel](https://babeljs.io/) is a JavaScript compiler. It takes JavaScript files as input, performs some transformations, and outputs JavaScript files. In SilverStripe we use Babel to transform our JavaScript in two ways. +[Babel](https://babeljs.io/) is a JavaScript compiler. It takes JavaScript files as input, +performs some transformations, and outputs other JavaScript files. In SilverStripe we use +Babel to transform our JavaScript in two ways. -#### Transforming ES6 +###### Transforming ES6 -ECMAScript 6 (ES6) is the newest version of the ECMAScript standard. It has some great new features, but the browser support is still patchy, so we use Babel to transform ES6 source files back to ES5 files for distribution. +ECMAScript 6 (ES6) is the newest version of the ECMAScript standard. It has some great new +features, but the browser support is still patchy, so we use Babel to transform ES6 source +files back to ES5 files for distribution. -To see some of the new features check out [https://github.com/lukehoban/es6features](https://github.com/lukehoban/es6features) +To see some of the new features check out +[https://github.com/lukehoban/es6features](https://github.com/lukehoban/es6features) -#### Transforming to UMD +###### Transforming to UMD -[Universal Module Definition](https://github.com/umdjs/umd) (UMD) is a pattern for writing JavaScript modules. The advantage of UMD is modules can be 'required' by module loaders (AMD and ES6 / CommonJS) and can also be loaded via `