README.md

Tola Activity

The build status of the dev branch is:

TolaActivity extends
the functionality of TolaData to include a
set of forms and reports for managing project activities for a Program. It
includes workflow for approving and completing projects as well as sharing
the output data. TolaActivity functionality is intended to allow importing
and exporting of project-specific data from 3rd party data sources or
excel files.

Creating a local TolaActivity instance

Running a local instance of TolaActivity makes development much faster and
eliminates your dependence on access to any of MC's TolaActivity instances.
These instructions should get you up and running with a minimum of fuss if
you have macOS or one of the many Ubunten. If they do
not, we accept pull requests updating it. :)

Through all of these instructions, it is very important that a plain-text editor is used to edit the text files.
For instance, TextEdit or Notepad are fine, MS Word is emphatically not. Even some plain-text editors default
to a rich text format, so make sure you are saving plain text.

Install software dependencies

TolaActivity requires Python 2. These instructions assume MySQL is being used as Django's datastore.

macOS

On macOS, you can use Homebrew to install much of the software needed for TolaActivity.
To see if you have Homebrew installed, run which brew at the command line. If you don't get a file path,
it is not installed and you should run the following command from the command line.

Now you're ready to [install and configure the source files](#Install the source files).

Windows

For Windows installations, install the Windows Subsystem for Linux using a Ubuntu distribution as the base. Once this has successfully been installed, launch a Powershell window and proceed with the Ubuntu instructions below.

Ubuntu

First check what python version you have installed. Try these commands:

$ python --version
$ python2 --version

If neither of those yield a Python 2 installation, you will need to install Python 2:

$ sudo apt-get update
$ sudo apt-get install python

Now if you try python --version, it should be pointed at Python 2. Assuming it is, install some additional packages.

###Modify the config file
If you have a copy of the settings.secret.yml file, place it in the TolaActivity/config
directory. In Windows, you will need to copy it from where the file is stored on your hard drive. You may want to modify the file per the instructions below (not with an MS Office product!) before moving it to the TolaActivity folder. To move the file, f the file is in your Downloads directory, you could use a command that looks something like this:

Try launching Tola in your browser

In your browser, navigate to localhost:8000. You should see a TolaActivity login screen. You should also be able
login through the Google+ link.

Creating a local user

If you are not logging in through the Google+ link, you will need to create a local user so you can log in.
The following commands will create a local superuser and add the additional data that is required.
When the createsuperuser command asks for an email, you can just hit the Enter key to skip the question.

You should now be able to login using the username and password fields of the login screen. Once you have logged in,
you will be taken to the home page.

For Developers

Front-end development setup and dev server

Tola uses Webpack and npm installed packages in node_modules to build javascript bundles.
During development, you will need to run the webpack development server to have the latest JS
bundles available, and to re-generate the bundles if you modify any JS handled by Webpack.

Directions for installing npm can be found below. It can also be installed via homebrew on macOS

$ brew install npm

Install all node_module package dependencies using npm

$ npm install

Note: You made need to periodiclly run this after doing a git pull if package.json has been
updated with new dependencies. This is similar to running pip install -r requements.txt if
the requirements.txt has been updated.

Start the webpack development server

$ npm run watch

This should be done along side ./manage.py runserver

Run JS unit tests

$ npm test

It's also possible to run the tests in "watch" mode

$ npm test -- --watch

or

$ npm run test:watch

Build bundles for production

When you are ready to deploy to an external server, you will need to build and check-in the
production ready bundles. These are generated with:

npm will compile a single global css file at /path/to/project/tola/static/css/tola.css. This file includes the entire Bootstrap library (previously in bootstrap.min.css and bootstrap-multiselect.min.css), our custom selectors (previously in app.css), and overrides to Bootstrap (previously in bootstrap_overrides.css)

Other tips:

Never edit the compiled css (tola.css) directly. Any manual changes to compiled css files will be overwritten the next time the css is regenerated. They are theoretically retrievable via Git but see #3, below. Remember: you can always bypass the harness by dropping css selectors directly into app.css.

But seriously, you should just put your css into a .scss file & compile it properly. Valid css is also valid scss. If you’re not sure where to write a selector, append it to the end of the master scss file: /path/to/project/scss/tola.scss.

Please commit your compiled css to GitHub, preferably in the same commit as your edits to our scss files.

There is no need to resolve merge conflicts in compiled css. Resolve them in the scss files first, then regenerate your css and accept all changes from the right (HEAD) side.