This is a base branding for new Living Atlas deployments. That is, some ALA header, banner and footer theme with:
- Well integration with ALA modules trying to avoid jquery conflicts and similar
- Well integration with
CAS
Authentication - Multilingual
- Modern javascript code without lost compatibility with old browsers
- Digest usage for skip cache old js/css when we release a new version
This is used as a basis for the Portal of Biodiversity of Chile (PBD) branding.
A LA compatible branding consist (currently) in a Bootstrap v3 footer and header html/css/js files that are loaded by all ALA java modules. But also some resources (like fonts, js/css dependencies, etcetera) are loaded from this branding (like jQuery or Bootstrap).
In other words, we can have our custom html with our custom look & feel, image, css, menus, and still we need to put in our branding some common libs and resources that should be loaded by the ALA modules (like bootstrap, jquery and other js libs).
Our strategy is to keep our brandings in sync with these dependencies easily. For this we just copy all that resources from the ALA current branding that is included in this repository as a git submodule and their resources are copied on each build. With the same strategy the LA branding includes their WP theme as a submodule, so, if they change some css in the WP theme, their branding is also updated.
This base branding ---- uses ---> ALA branding resources ---- uses ----> ALA WP theme resources
For instance, to avoid conflicts, we only load js libs that are not used by ALA (like i18next
js lib) and we use the libs that ALA already include in their branding and software (as the jQuery lib or the Boostrap 3 framework and deps).
The goal is also not to deal with duplicate code and their problems.
So if ALA fix some js error, or if add a new chart lib, or similar, we can include that changes in our build easily.
The branding also create some homepage, some test pages and a error page. But if you need some more complex homepage, and for instance, you need to use a CMS (like Wordpress), our recommendation is that you can use a similar strategy to avoid the need of keep in sync your LA branding and your CMS theme. So you can develop a common header/footer and css styling in your CMS, and include it in a fork of this sample branding. In summary:
Your branding ---- uses ---> ALA branding resources ---- uses ----> ALA WP theme resources
`--- uses ---> you CMS theme resources
So if for instance, you change a logo or a footer link in your CMS you can have the same change in your ALA portal easily.
Also in general we try not to mix libs versions like different Boostrap or jQuery versions.
Other strategy is to have an independent CMS theme with their own js/css and a simpler LA branding with a similar look a feel but using ALA libs (Bootstrap 3 ...).
ALA uses Bootstrap version 3 in most of their modules.
├──app
│ ├── assets # static assets, like index/header/footer/banner.html
│ │ ├── fonts # etc
│ │ ├── locales
│ │ └── images
│ ├── css # put your css here
│ ├── js # put your js code here
├──commonui-bs3-2019 # ALA branding as submodule
│
├──node-modules # 'yarn add module', to install
│ # any node module and use it in your js code
├──pbd-home # Submodule of the PBD home page
│
└──public
├── css # The 'public' directory is what you have to deploy
│ └── images # It's generated by `brunch`
├── fonts
├── locales
├── images
└── js
Brunch compiles in public your js
/css
and make this compatible with older browsers (so you can use node modules or ES6 code without problems).
See and edit app/js/settings.js
there you can select for instance the theme you want to use.
This is using https://brunch.io instead of gulp and using ALA commonui-bs3-2019 as a git submodule to use the same assets used by ALA modules.
# First use:
git clone --recurse-submodule https://github.com/living-atlases/base-branding.git
# if you cloned without the submodules: git submodule update --init --recursive # use --init only the fist time
# install yarn with or similar:
# https://classic.yarnpkg.com/en/docs/install/#debian-stable
yarn install
npm install -g brunch
# During development
brunch watch -s
# or
brunch build
# or
brunch build --production
Test with:
brunch build --production && rsync -a --delete --info=progress2 public/ your-server:/srv/your-server-domain/www/test-skin/
And in your inventories:
header_and_footer_baseurl = https://l-a.site/test-skin
header_and_footer_version = 2
The version = 2
will substitute some ::variables::
like login/logout urls in your head/banner/footer.html
in production. This is also done in index.html
and during development with the app/js/settings.js
values. See ala-bootstrap3 HeaderFotterTagLib.groovy for more details. Use the appropriate skin (see below).
test-skin
is just a directory in your vhost root so you can keep different versions of a skin for testing purposes, for developing, etc. For instance when ALA uses commonui-bs3-2019
directory their modules uses resources like https://www.ala.org.au/commonui-bs3-2019/head.html
.
More information about rsync and scp directories here.
In general you should use main
or generic
skin in your ALA modules. Some coments:
collectory
:ala
skin layout works wellspecies
:ala
skin layout works wellregions
:main
skin layout works wellbie-index
:main
skin layout works welllists
:main
skin layout works wellimages
:main
skin layout works wellbiocache
:ala
skin layout works welluserdetails
:ala-main
skin layout works well
Here you have a table of skin layouts recommended, variables names, layouts used by ALA, links to code, etc.
With brunch.io we can use node modules, ES6 js code, sourcemaps, minimize, development with watch and browser auto reload etc, with a more easy configuration than gulp.
We copy the ALA dependencies (jquery, autocomplete, etc) via a plugin from the ALA submodule, so we can integrate ALA modules well.
See the brunch-config.js
for more details.