uqlibrary-reusable-components

Contents

• Getting started
• Updating IA
• Applications customisations
• Forcing IMS logins
• Elements development
• Testing

The Central Repository contains:

• /elements/ - Common elements, eg header/footer
  • View full demo here.
• /test/ - Tests for elements
• /applications/ - Application customisations such as LibGuides styles/scripts
• /bin/ - Shell scripts for testing and deployment
• /resources/ - Icons, uql-menu.json, etc
• /templates/ - Simple layouts for static pages, used for EZProxy error display etc
• /backup/ - Styles/scripts of applications before reusable components were applied

Overview of how the Polymer components interact (stored in Projects for want of anywhere else to put it).

Getting Started

The project installs its bower dependencies in ONE DIRECTORY LEVEL ABOVE the git root directory, so make sure you clone the repo into an empty folder. For example,

cd ~
## The dir name below can be anything; just remember what it is.
mkdir uql-reusable
cd uql-reusable
git clone git@github.com:uqlibrary/uqlibrary-reusable-components.git

This should result in your local checkout being at ~/uql-reusable/uqlibrary-reusable-components. Make sure you don't put anything else directly under ~/uql-reusable manually; bower will do that for you.

The reason for this seemingly odd location is to allow for easier integration with other projects which use it. All the UQL polymer repos are built this way, so this strategy should be followed for all of them; not just this one.

Project requires the following major dependencies:

• Node.js, used to run JavaScript tools from the command line.
• NPM, the node package manager, installed with Node.js and used to install Node.js packages.
• Gulp, a Node.js-based build tool.
• Bower, a Node.js-based package manager used to install front-end packages (like Polymer).
• Nightwatch, the automated UI testing framework

With Node.js installed, run the following one liner from the root of the repo:

npm i -g gulp-cli bower nightwatch npm@6 && npm install

• IMPORTANT! Before each change, update our saucelab browser versions by using the saucelabs configurator so we are testing against current OS versions (browser versions are mostly automatic). Also check the latest ESR version for firefox. (ESR versions are deployed in our Standard Environment across the Libraries).

Updating IA

UX Services staff are able to make changes to the Mega Menu.

Instructions for UX Services staff

• Make sure your branch is set to ux-services (Using this branch means you can do your change at any time, without impacting other work which might be underway in master. Do, however, liaise with other UX Services staff who might be making other mega menu changes in this branch...)

• Changes can be made either through the GitHub interface or you can use a client like GitHub Client.

• Make your changes to this file:

  https://github.com/uqlibrary/uqlibrary-reusable-components/blob/ux-services/resources/uql-menu.json

If editing on the Github website, your screen should look like this:

• Once you have Committed the changes (and Pushed if using a client), a build will automatically be triggered. You can monitor the status of the build here: Codeship for Reusable Components

  This checks the syntax, runs the tests and then triggers a rebuild of the cache. This can take from 15-20 minutes to complete and the file should then be available for preview at http://assets.library.uq.edu.au/ux-services/reusable-components/elements/demo/index.html.

• update the PT to indicate you have put your required changes in the ux-services branch.

Steps for devs after UX Services staff have pushed their changes

• For uqlibrary-reusable-components
  1. confirm ux-services branch build has passed
  2. Merge to master
• For uqlibrary-pages: start rebuild of production branch (after reusable master passes; it pulls master of reusable, no release necessary) - updates homepage
• For uqlibrary-reusable-components: build of production branch (merge master into prod and push) - updates drupal at web.library.uq.edu.au

If you are doing big changes to Polymer components, make sure you test everything is working on Drupal (https://web.library.uq.edu.au) as well. This can be tested before going live by running the master branch of reusable through codeship and, post-invalidation in AWS Cloudfront, viewing the Drupal staging site, for example, the training page.

(If you want to view the drupal staging site using staging data, you will have to build reusable master calling uqlibrary-api where uqlibrary-api.html has set the variable baseApiUrl to https://api.library.uq.edu.au/staging.)

Applications Customisations

All custom styles/scripts are located in /applications/[app name]/

• load.js - Script contains injection of components for the application
• custom-styles.scss/custom-styles.css - Custom css for the application

Customised applications:

• LibGuides

• LibAnswers

• UQ Drupal

• UQLAPP, FBS, Contacts, Exams, ACDB

• Primo UI

• Shared

• Studenthub

• Omeka

• Rightnow

• Talis

• deprecated: old Primo

Forcing IMS logins

Embed the following if you want to force an IMS login for on campus workstations, as they will be unable to access the assets.library.uq.edu.au domain:

<script src="https://www.library.uq.edu.au/js/ims.js"></script>

Elements Development

Please, read Style Guide before starting development.

All common styles, colours, or mix-ins are located in /elements/common-styles.html

Follow directions here for post-dev steps to make sure that changes from child components make it to this repo.

Development/Deployment process

1. Create/update required component following Style Guide
2. Use common styles/variables/mix-ins from /elements/common-styles.html, customise styling in the element.
3. Create/update demo page for the component in /elements/[component]/demo/index.html
4. Create/update test suite in /test/ directory
5. If new component is a stand alone component - add it to complete demo page /elements/demo/index.html
6. Run gulp syntax to check project passes validations
7. If component is to be included into a specific application, update /applications/[app name]/load.js for this application
8. If styling update is required for a specific application, make sure styles are compiled
9. Commit all changes

Codeship will deploy changes automatically by running deployment task /bin/codeship.sh (if Codeship is configured for deployment, by default it only builds a feature branch):

• Installs all dependencies
• Sets AWS configuration
• Runs checks/tests
• Runs vulcanization task
• Runs gulp publish task which uploads files to S3 bucket and invalidates cache

Distribution package on S3 looks like this:

• [branch_name]/reusable-components/
  • /libapps/libguides/*
  • /libapps/libanswers/*
  • /libwww/*
  • /uqlapp/*
  • /other-uql-apps/*
  • /webcomponents/*
  • elements.vulcanized.html
  • elements.vulcanized.js

Subdirectory [branch_name] only exists for non-production branches, eg master/uat. Demo for feature branches is available at http://assets.library.uq.edu.au/[branch_name]/reusable-components/elements/demo/index.html

Testing

Unit Testing

gulp test

Local testing

1. Run Selenium server. Selenium is required to run tests locally.

   • On Linux, install jdk, then download the Selenium Standalone Server jar file from here and then run the server with:

     java -jar selenium-server-standalone-{VERSION}.jar

     You may want to create a bash alias for this.

   • On OSX, brew install selenium-server-standalone to install, and then run the server with:

     selenium-server -port 4444

2. Run tests

   • To run the default test locally, you will need to download the Firefox WebDriver and put the location in your Path.

   • To run the Chrome tests locally you will need to download the Chromium WebDriver and put the location in your Path.

   • Test commands (run from the bin directory: cd bin):

     • Run all the tests using the default driver (geckodriver)

       nightwatch -c nightwatch.json --tag e2etest

     • Run all the tests using the Chrome driver

       nightwatch -c nightwatch.json --tag e2etest --env chrome

     • Run omeka-specific tests (tag defined in test/e2e/e2e.omeka.js )

       nightwatch -c nightwatch.json --tag omeka

       • Replace 'omeka' with whichever one you want to run, from test/e2e/e2e.*.js except the "minimal" one.
       • The nightwatch e2e tests are setup as one file per project, plus a file of minimal common items which isn't valid to run on its own. To only run the valid tests, use the tag e2etest.

Run Tests Remotely

gulp test:remote

When you run this command, you may get the error:

Missing Sauce credentials. Did you forget to set SAUCE_USERNAME and/or SAUCE_ACCESS_KEY?

To set these fields,

1. Visit the Reusable-components Codeship Environment Variable page

2. Note the values for SAUCE_USERNAME and for SAUCE_ACCESS_KEY

3. Export these as local variables on your box, eg:

   export SAUCE_ACCESS_KEY='XXX'

Then run the gulp test:remote command again

Workflow

Suggested workflow for changing CSS on 3rd party sites

• Open the page that needs restyling
• Assuming Chrome, open the inspect page and tweak settings in the Elements > css pane until you have what you want
• Open the scss file in PhpStorm and make updates
• Run gulp styles
• Open the generated custom-styles.css file and copy all
• On the web page, in the inspector, goto Sources and navigate to the same custom-styles.css file
• Select all and overwrite with css copied from custom-styles.css, above
• Look at the page to check you got what you wanted
• Repeat

This lets you precisely check any changes without having to create a github release.

Gotchas

If you run gulp test and you get the error:

Error: util_1.promisify is not a function

then your node version is too low, eg:

$ npm -v
6.4.1

Solution: update node to the version specified in package.json:

nvm install 11.10.1 # as of 19 Aug 2019

Codeship backup at 03/Jan/2019

Test Setup

jdk_switcher use oraclejdk8
chmod a+x -R bin/*
bin/codeship-setup.sh

Pipelines

Test Commands

export PIPE_NUM=1
bin/codeship-testing.sh

Unit tests

export PIPE_NUM=2
bin/codeship-testing.sh

Saucelabs

export PIPE_NUM=3
bin/codeship-testing.sh

Deployment (master and production)

CUSTOM SCRIPT

jdk_switcher use oraclejdk8
chmod a+x -R bin/*
bin/codeship-setup.sh
bin/codeship-deployment.sh
bin/codeship-prod-testing.sh

Deployment (branches starting with feature- or primo-)

Same as above, except remove the last line.