FirstVoices Dictionary Prototype

This is a responsive dictionary web-application for the FirstVoices language assets that uses Nuxeo ECM as a back-end.

Stack

This web app is built using the following:

• ReactJS
• Webpack
• Material-UI
• Nuxeo-js-client

And interfaces with a Nuxeo server, at the moment using custom schemas and configruation specific to FirstVoices.

For additional dependencies see package.json.

This app has been scaffolded using gulp-starter.

Getting Started

There are several version dependency requirements to properly build and run the project:

• NodeJS>=v8.10
• Gulp CLI v3.9.1
• Yarn v1.5.1

Instructions to install specific project dependencies and running the application are described in the Setting Up and Running section.

Mac OS X is the ideal environment for running and developing the FirstVoices Web Application. The steps below are instructions for downloading project dependencies and building the project using Terminal on Mac OS X.

Setting Up and Running

Perform the steps below to setup your environment and run the FirstVoices Web Application on Mac OS X.

1. Install Homebrew by following the instructions found on the Homebrew home page.

2. Use Homebrew to install NVM by running:

$ brew update
$ brew install nvm
$ mkdir ~/.nvm

Configure NVM by adding the following entry to your ~/.bash_profile file:

export NVM_DIR=~/.nvm
source $(brew --prefix nvm)/nvm.sh

Activate and verify your new ~/.bash_profile entry by running:

$ source ~/.bash_profile
$ echo $NVM_DIR

3. Clone this repository and navigate into the fv-web-ui directory:

$ git clone https://github.com/First-Peoples-Cultural-Council/fv-web-ui.git
$ cd fv-web-ui

4. Initialize and recursively clone required Git SubModules by running:

$ git submodule update --init --recursive
$ git submodule foreach git pull origin master

5. Install NodeJS v8.10.0 and set it as the active version of NodeJS by running:

$ nvm install 8.10.0
$ nvm use 8.10.0

6. Install GULP CLI v3.9.1 by running:

$ npm install -g [email protected]

7. Install Yarn v1.5.1 by running:

$ npm install -g [email protected]

8. To successfully run Yarn, you need to configure your ~/.ssh/config file so that Yarn knows which RSA Key to use when cloning GitHub repositories. Create a ~/.ssh/config file if it does not already exist. Add the following entry to your ~/.ssh/config file while replacing <mykey> as needed:

# Github RSA Key
Host github.com
    UseKeychain yes
    AddKeysToAgent yes
    IdentityFile ~/.ssh/<mykey>_rsa

9. Run Yarn to download node_modules dependencies by running:

$ yarn

Important Note: when running Yarn for the first time you will be silently prompted to enter the Key Phrase for the RSA Key you added to the ~/.ssh/config file. If progress halts and a small lock icon appears, enter your RSA Key Phrase to proceed.

10. Run GULP build the project and start the Node server by running:

$ gulp

11. Visit localhost:3001 in your web browser to view the FirstVoices Dictionary Prototype app.

Building for Production

You can build for production after completing the steps found in the Setting Up and Running section above.

1. Run the following command to build for production:

$ gulp build:production

2. Copy the generated files in /public folder to your webserver.

Note: Remember to configure your web application to rewrite all requests to the root path, in order for Push State to work.

Contributing

Adding New Dependencies

Install dependencies using yarn add package or yarn add package --dev

Tips

• Learn how to work with React.js
• Get familiar with ES2015 syntax

Testing

We use BroswerStack in order to ensure our UI functions in the latest version of all major browsers, and at least 1 version back depending on demand from our users. We will be posting a more detailed and up-to-date compatibility status in the future.

To run functional tests use:

$ gulp karma

Licensing

The data and code in this repository is licensed under multiple licenses.

• All code in the /app directory is licensed under the Apache License 2.0. See LICENSE.

• All gulp-starter code in /gulpfile.js directory is licensed under MIT License (MIT). See gulpfile.js/LICENSE.