Difference between revisions of "ARK2/Frontend"

From ARK
Jump to: navigation, search
(Build Tooling)
(Frontend)
Line 9: Line 9:
 
* admin - A minimal Web Admin front-end for configuring an API-only server
 
* admin - A minimal Web Admin front-end for configuring an API-only server
 
* flat - A simple, non-js, read-only front-end designed for scraping, e.g. for static archiving or web-bots
 
* flat - A simple, non-js, read-only front-end designed for scraping, e.g. for static archiving or web-bots
* core - The default front-end supporting the full ARK2 feature set
+
* ark2 - The default front-end supporting the full ARK2 feature set
 +
* bootstrap3 - A minimal Bootstrap 3 frontend designed as a base for custom frontends
 +
* bootstrap4 - A minimal Bootstrap 4 frontend designed as a base for custom frontends
 +
 
 +
== Build Tooling ==
 +
 
 +
Build tooling for frontend assets is required for a number of reasons:
 +
* Bootstrap can be customised most easily by changing variables used in the Sass templates, which then requires a build step to compile them into CSS
 +
* Production deployment is more efficient if CSS and JS is stripped, merged and minified, while development is easier if a map is generated for the original code
 +
* NPM library management downloads the entire package, not just the assets required, an extra step is required to copy just the required assets into the web root folder
 +
* All the steps required for packaging and release management can be automated, e.g. clean, compile, tag, package, etc
 +
* The build tooling for the default ARK bootstrap and twig theme can be generalised to allow clients to build and deploy their own customised themes with minimal effort
 +
 
 +
The build tooling works as follows:
 +
* All build tooling is isolated in the /build folder and will be excluded from any release packages or production deployments
 +
* Nothing in the /build folder may be depended on by any code outside the /build folder or required for running ARK itself
 +
* [https://nodejs.org/en/ Node], [https://www.npmjs.com/ npm] and [http://gulpjs.com/ Gulp] will be used to run the tooling
 +
* NPM is used to manage the vendor libraries which are installed into /build/node_packages
 +
* Gulp is used to ensure the tooling runs cross-platform
 +
* Running tasks will only work inside the /build folder, trying to run outside the build folder will fail
  
 
== Build ==
 
== Build ==
Line 66: Line 85:
 
  /
 
  /
 
  |- build/
 
  |- build/
   |- .bowerrc
+
   |- .jsbeautifyrc
   |- bower.json
+
   |- .jshintrc
   |- console
+
   |- build
 
   |- gulpfile.js
 
   |- gulpfile.js
 
   |- packages.json
 
   |- packages.json
Line 133: Line 152:
 
           |- styles/
 
           |- styles/
  
== Notes ==
+
== Useful References ==
 
 
Bootstrap 3 supports both [http://lesscss.org/ Less] and [http://sass-lang.com/ Sass] templates to generate the Bootstrap CSS. Customising the appearance of Bootstrap (such as colour) usually requires modifying template variables and rebuilding the CSS. Bootstrap 4 (currently in alpha) switches to only using SASS for its templates. We should therefore choose to use the SASS version of Bootstrap 3 when building our own custom version of Bootstrap. Build tools will be provided to automate the customisation process.
 
 
 
The use of Twig templates for page layout will help separate the model and view code and allow third parties to easily modify the layout without having to alter the core code. Each Twig template will document the API contract it has with the data model, i.e. what variables are available to be used in the template.
 
 
 
The use of the Silex/Symfony Forms module will be considered. This provides dynamic form generation and validation with a Bootstrap theme.
 
 
 
There will be separation between the ARK Admin frontend and the ARK Web frontend. The required ARK Admin frontend will be static and consistent across all ARKs, but can be modified for site specific requirements if needed (i.e. adding extra user data fields). The optional ARK Web frontend will be the dynamic generated data-driven side, configurable for every ARK. This separation will allow for ARK to run as a pure database/API backend server with basic admin and auth frontend provided without the user having to configure or enable any of the web frontend.
 
 
 
The ARK Admin frontend will provide the core UI elements for the site, i.e. the Nav Bar and Nav Menu. An initial template will be inspired by [http://startbootstrap.com/template-overviews/sb-admin-2/ SB Admin 2] (Test [http://blackrockdigital.github.io/startbootstrap-sb-admin-2/pages/index.html here]) and [https://almsaeedstudio.com/ AdminLTE] (Test [https://almsaeedstudio.com/preview here]), but greatly simplified and converted to Twig templates.
 
  
 
* http://www.helloerik.com/the-subtle-magic-behind-why-the-bootstrap-3-grid-works
 
* http://www.helloerik.com/the-subtle-magic-behind-why-the-bootstrap-3-grid-works

Revision as of 13:51, 12 April 2018

Frontend

ARK2 has imposed a clear separation between the backend and front-end, allowing the front-end to operate completely independently. ARK2 provides a number of standard front-end implementations, but sites can adapt or implement their own.

The standard frontends are implemented in Bootstrap, jQuery, and Twig, the most popular and well-supported front-end ui component and template systems. This allows for easier customisation of ARK's appearance by third party designers.

The standard front-ends shipped with ARK2 are:

  • api - The absolute minimal front-end required to run an API-only server, all admin is performed via the admin console.
  • admin - A minimal Web Admin front-end for configuring an API-only server
  • flat - A simple, non-js, read-only front-end designed for scraping, e.g. for static archiving or web-bots
  • ark2 - The default front-end supporting the full ARK2 feature set
  • bootstrap3 - A minimal Bootstrap 3 frontend designed as a base for custom frontends
  • bootstrap4 - A minimal Bootstrap 4 frontend designed as a base for custom frontends

Build Tooling

Build tooling for frontend assets is required for a number of reasons:

  • Bootstrap can be customised most easily by changing variables used in the Sass templates, which then requires a build step to compile them into CSS
  • Production deployment is more efficient if CSS and JS is stripped, merged and minified, while development is easier if a map is generated for the original code
  • NPM library management downloads the entire package, not just the assets required, an extra step is required to copy just the required assets into the web root folder
  • All the steps required for packaging and release management can be automated, e.g. clean, compile, tag, package, etc
  • The build tooling for the default ARK bootstrap and twig theme can be generalised to allow clients to build and deploy their own customised themes with minimal effort

The build tooling works as follows:

  • All build tooling is isolated in the /build folder and will be excluded from any release packages or production deployments
  • Nothing in the /build folder may be depended on by any code outside the /build folder or required for running ARK itself
  • Node, npm and Gulp will be used to run the tooling
  • NPM is used to manage the vendor libraries which are installed into /build/node_packages
  • Gulp is used to ensure the tooling runs cross-platform
  • Running tasks will only work inside the /build folder, trying to run outside the build folder will fail

Build

The front-end is built from the source assets files in the 'build/' folder and installed in the 'src/' folder. The individual site folders then symlink to the required front-end in 'src/', or copy if they wish to edit in place. (See the FileLayout section below for more on this).

The front end build and install is managed by the Build and System Consoles. The Build console is in the 'build/' folder and is used to build/rebuild/install a front-end if required. The System Console is in the 'build/' folder and is used to link the installed front end to a site.

To build a front end you first need to install the build environment (see Environment for installing the prerequisites):

 cd build
 npm update

You may occasionally need to re-run this command to update the build environment, especially after an ARK upgrade.

To see details of the build environment (including available updates), run:

 ./build env:status

To clone the build assets for a new front end from the Core front-end, run the create command. You must provide a name for your new front end, and the source code Namespace it will use, e.g. ARK, Wibble, or Foo. Only use the ARK namespace if the front end is intended for the main ARK project. This Namespace will be remembered by the system.

 ./build frontend:create <namespace> <frontend>

To build and install a front-end run the front-end command. You can supply a front end name to install or default to the 'core' front end.

 ./console frontend:all <frontend=core>

This will install the built front end into 'src/<namespace>/frontend/<frontend>'.

You can also choose to build just one type of asset to save time, e.g. if you only changed a template and don't want to wait for the js to be rebuilt as well:

 ./build frontend:css <frontend=core>
 ./build frontend:js <frontend=core>
 ./build frontend:twig <frontend=core>

To use a front end for a site, run the System Console in the '<install>/bin' folder.

To create an entirely new site, use the create command. This will create a new database, site folder, config and web subfolders, and link/copy the chosen front-end.

 cd ../bin
 ./sysadmin database:server:add <server>
 ./sysadmin site:create <site> <frontend=core>

You will be asked if you want to link or copy the front-end. It is recommended to use the default link option as you will not need to update the site folder when the front-end changes. Only copy the front-end if you want to make small changes to the front-end without having to build a new namespaced front-end. This however is discouraged, you should build a namespaced front-end instead.

To enable a front-end other than core, you will need to edit the '<site>/config/site.json' file to set the name of the front-end. [TODO: Write a command for this!]

To add another front-end to a site, or to refresh a copied front-end:

 site:frontend <site> <frontend>

File Layout

Build:

/
|- build/
  |- .jsbeautifyrc
  |- .jshintrc
  |- build
  |- gulpfile.js
  |- packages.json
  |- assets/
    |- <name>/
      |- bin/
      |- config/
      |- css/
      |- fonts/
      |- img/
      |- js/
      |- less/
      |- scss/
      |- twig/
      |- xliff/
  |- node_packages/
  |- vendor/

Source:

/
|- src/
  |- ARK/
    |- web/
      |- <frontend>/
        |- .htaccess
        |- index.html
        |- templates/
        |- translations/
        |- assets/
          |- fonts/
          |- images/
          |- scripts/
          |- styles/
      |- api/
      |- admin/
      |- core/
  |- <project>/
    |- web/
      |- <frontend>/
        |- ...

Sites:

/
|- sites/
  |- <site>/
    |- config/
    |- files/
    |- schema/
    |- src/
      |- <frontend>/
        |- php/
        |- templates/
        |- translations/
    |- web/
      |- .htaccess
      |- index.php
      |- assets/
        |- <frontend>/
          |- fonts/
          |- images/
          |- scripts/
          |- styles/

Useful References