This page contains technical documentation about the app and other information useful for developers contributing to Terrastories.

1. Overview of the Application
2. Policies - User Permissions
3. Admin Dashboard & Administrate
4. Localization & Translations
5. Dev Environment Common Errors + How to fix them (WIP)

When you load terrastories, the first screen is a welcome screen. From there you can choose to:

• Visit the interactive map anonymously
• Login as a user and visit the interactive map as that user
• Login as an admin and visit the admin dashboard

This brings you to either of the two main sections of the terrastories app:

• Interactive Story Map
• Admin dashboard

The Interactive Story Map is where users can view stories and places on a map with a sidebar. There are cards in a scrollable sidebar which display the story descriptions, the speakers, and the media attachments. There are also points on the map for all the different places with stories. This is powered by the react-rails gem, with our Rails views connected to client side React.

The Admin dashboard is where admin users can create, update, and delete data from the application. This includes: Users, Places, Stories, and Speakers. They can also use an importer to upload bulk data in a CSV format. This is powered by the administrate gem - more information can be found here.

We use a gem called Pundit to manage the different user permission levels.

Only admin level users can create, delete and update other users. In the application seed data, we create a default admin user to start with.

The different user permission levels are as follows:

1. Admin/Editor
2. User
3. Anonymous

This is represented by an integer on the user model as a field called "role". Anonymous is if the user is not logged in (via Devise).

The Enum has two possible values: [:editor, :user]

An editor has the ability to change anything in the admin dashboard. They are considered an Admin.

A user just has a login and can view more stories than an anonymous user.

There is another Enum field on Story model called "permission_level". This has two possible values: [:editor_only, :user_only, :anonymous]

When Stories are rendered, we use the StoryPolicy class to determine which ones to return based on the permission level in the Story and the User's role if the user exists.

Policy class files can be found in rails/app/policies

The admin dashboard in Terrastories is powered by the gem administrate. Each view in administrate can be found in rails/app/dashboards.

For each of our models, there is

• Index view - Displays all of the records that exist for each model.
• Show/Individual view - Displays a single record by ID and all of the fields.
• Edit view - Allows you to edit the fields of a single record.
• Create view - Allows you to create a new record.
• Importer - Allows you to bulk upload records. These are specific and hardcoded for each model (except User) and handled in each Model's file. For example, see Story#import_csv.
• Importer UI exists on the Index view of each Model, which is using a custom administrate view.
• Importer Controllers - Each model has an Adminstrate controller generated where we can override or add additional routes. There is a related import_csv action for each model that handles imports.

Whenever you create a new model, you will need to generate an administrate dashboard for it to appear in the sidebar at /admin. If the model already exists, you can find the dashboard file under rails/app/dashboards and skip ahead to the how to use section.

Generating a dashboard will automatically create the index, show, edit, and create views of the model, and add it to the sidebar in the admin interface. To do so, run this command in the Rails container:

# start the container
docker-compose exec web /bin/bash

# generate dashboard for the new model
rails generate administrate:dashboard <ModelName>

Visit the official administrate documentation on how to read and customize the generated dashboard files.

If you need to add any custom functionality or styling to any of the views, you will need to run a command to reveal the administrate view file. This will allow you to overwrite anything on the generated page. WARNING: Once you run this command, you will not be able to go back to the generated version. Only run this if you're sure it's what you need!

To generate a custom view for a specific resource,

# start the container
docker-compose exec web /bin/bash

# generate custom page view for a model
rails generate administrate:views:<page> <ModelName>

In the example above, <page> represents which page you would like to make custom, i.e. index, edit, show, new. To generate all four at once, omit the page. <ModelName> represents the name of the resource you would like to generate the page for.

To generate a custom view for a layout for ALL resources,

# start the container
docker-compose exec web /bin/bash

# generate a custom view for a layout for all resources
rails generate administrate:views:<layout>

In the example above, <layout> represents which Rails layout you would like to make custom, i.e. navigation, javascript, flashes, etc.

To read how to use a custom Administrate view, visit their documentation here.

To see an example of a generated custom administrate view, you can take a look at the index page. The custom part is a form tag at the end for the importer.

We currently use yml files to display languages. You can change your language in the Welcome page. An extra param is appended to the URL so that the application knows which language to render.

Adding yml files to config/locales/ will automatically add these to Terrastories the next time the application is started.

If you'd like to contribute to translations, please see how to add languages for translations here!

This section is still under construction, you can visit the google doc here for the current draft iteration.