View source for ARK2/Frontend

= Frontend =

ARK2 has imposed a clear separation between the backend and frontend, allowing the frontend 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 [http://getbootstrap.com/ Bootstrap], [https://jquery.com/ jQuery], and [http://twig.sensiolabs.org/ Twig], the most popular and well-supported frontend ui component and template systems. This allows for easier customisation of ARK's appearance by third party designers.

The standard frontends 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 frontend for configuring an API-only server
* flat - A simple, non-js, read-only frontend designed for scraping, e.g. for static archiving or web-bots
* core - The default frontend supporting the full ARK2 feature set

== File Layout ==

Build:

 /
 |- build/
   |- .bowerrc
   |- bower.json
   |- console
   |- gulpfile.js
   |- packages.json
   |- assets/
     |- <name>/
       |- 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/

== Build Tooling ==

Build tooling 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
* Bower component 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 will be as follows:
* All build tooling will be 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], [http://bower.io/ Bower] and [http://gulpjs.com/ Gulp] will be used to run the tooling (Bower requires Node/npm to be installed, so we may as well use its full power)
* Tooling should be cross-platform (Gulp provides this as opposed to bash scripts)
* Gulp will not be required as a global install, instead tasks will be aliased through Node scripts, e.g. 'npm run build' will call 'gulp build'
* Running tasks will only work inside the /build/ folder, trying to run outside the build folder should fail gracefully
* NPM installs Node packages into /build/node_packages/
* Bower will be configured to install external packages into /build/vendor/

== Notes ==

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

== View Tables/Classes ==

ark_view_element_type

- Event
- Field
- Layout
- Link
- Subform

ark_view_element
ark_view_field
ark_view_group
ark_view_layout
ark_view_option

 Element
 - Event
 - Field
 - Link
 - Group
   - Subform
   - Layout
     - Grid
     - Tabbed
     - Table
 Alias
 Condition
 Option
 Rule