idemsinternational / open-app-builder

PLH App Frontend

Open App Builder

Online Documentation

Quickstart

Prequisites

1. Download and install Git
   This will be used to download the repository

2. Download and install Git LFS
   This will be used to download any required binary assets, such as images or pdfs

3. Download and install Node
   This is the programming lanugage required to run the project

4. Download and Install Yarn
   This manages all 3rd-party code dependencies

Installation

Download the repo with binary assets

$ git lfs clone https://github.com/IDEMSInternational/open-app-builder.git

Note - if you do a regular git clone, you can always run git lfs fetch --all later to sync assets

Install required dependencies

$ cd open-app-builder
$ yarn install

Note - you may have to do this from time to time when content is updated)

Configuration

Set Deployment

The app supports using different workspace or deployment configurations. These are stored in .idems_app/deployments

To use an existing deployment, run the following script:

yarn workflow deployment set

This will present an interactive list of deployments to select from.

See Deployment Documentation for information about creating and configuring deployments.

Running locally

Start the local server

yarn start

This will start a local server and serve the app in your browser on http://localhost:4200

For Content Coders

Please see Quickstart Authors

For Developers

Please see Quickstart Developers

open-app-builder's Issues

Fix plh-demo1.idems.international URL's when deep linking

The link https://plh-demo1.idems.international/ currently shows master.

However deep linking like https://plh-demo1.idems.international/chat/flow/:flowName do not work.

This needs to be fixed urgently.

Home Page - styles update

General Notes

Not all the sections are perfectly defined at this point, but see mapping below for how I understand things currently. Suggest for now to keep URLs and feature names unchanged when renaming home buttons (as could change again in future). Unsure exactly how it should work in the skinning system, but if looks reasonable with a single base colour and color-rotate implement that way or otherwise perhaps create an individual scss variable that can be used for each module (e.g. $toolbox-main/base/button(?)-colour that could also follow into module-specific code)

Chat: Remove button, keep module (will trigger specific chats via tasks)
Toolbox: -> parenting toolbox (keep URLs and unchanged)
Activities: Deprecate (if time allows should move all code and assets to single feature/activities folder, otherwise just remove button)
Gallery: -> parenting moments
Goals: -> my plans
Guide: -> my journey
??? <- Help me now (tbc, I'm guessing it will launch a chat flow but will seek clarification. Until then create button but disable)

Design Docs

Latest Figmas (?)

old

new

Tasks - Add regular tasks

There will be 8 tasks always available (regular/habit-building) alongside one-off tasks. Should implement from spreadsheet and add simple checkbox tracking mechanism (with timing system to limit how often completed)

Lists with additional content need to be distinguished from lists without additional content

In https://plh-demo1.idems.international/toolbox/topic/ONE_ON_ONE_TIME/1on1_Ideas we have list with accordion style arrows. Could they be changed to dots instead?

Without text:

List with text where accordion is correct:

Scripts - Improve workflow for xlsx authors

My Immediate thought would be a page where an xlsx file can be dropped and run through the same conversion pipeline as app data and incorporated into the app (requires #122)

Additionally anything that pulls data from the hardcoded data folder should instead use the shared data service (which can be updated dynamically)

Scripts - Automate downloading of gdrive scripts

Woudl be good if part of the current plh-xlsx-to-json pipeline that there be an option to download files from google drive. Initially this can be an interactive request (using existing gdrive node auth utils), but future may also want to run in ci environment via service worker or other oauth credentials

Tasks - Define requirements data structures

A few minor adjustments required for tasks system, particularly requirements which now should include a possible delay/offset in either days and app days (consecutive counter for each day the app has been used, e.g. day 1).

Will need to propose and implement a syntax for this for requirements, e.g.

[taskWord]_[value]_[quantifier]

or

[taskWord]_[quantifier] 

(where a default value can be inferred)

So for offsetting unlock it might be -
delay_2_day
delay_3_appDay

We could then in the future think of more keywords, and chaining multiple together, e.g. to wait at least 7 calendar days and apply on the first upcoming weekend it could be:
some_task | delay_7_day | on_weekend

In the context of multiple requirements this could look like

requires: "task_1a | delay_2_appDay; task_1b; task_1c | delay_7_day"} 

This could also have chaining of piped modifiers

meaning

• task_1a would need to be completed, and if completed on day 1 of using the app would unlock on day 3 of using the app.
• task_1b would need to be completed
• task_1c would need to be completed, and if completed on a Monday would unlock the following Monday (7 days later)

Show module summary when selecting module from modules list

Chat - add message loading animation

Whilst waiting for delay to show next message a simple (...) or similar could be shown at the bottom to mimic the bot typing. Design guidelines to come from Orli

Notes for QA:
Should show up below messages for (1, 3 or 5 seconds depending on Chat delay setting)

Tasks- Add requirements evaluation

Will move away from goals defining tasks to tasks relying on requirement fields for what can/should be displayed. Once tasks implemented to self-evaluate whether they can show, should remove goals interface

Add systems to interpret module_page and module_list flows

E.g. https://docs.google.com/spreadsheets/d/1otUVKSJA_XZ4BUnfW9_wgpWJtbqcr-g7WrHV-AJ5zEs/edit#gid=1956552062

Lots of components, which will need to render entire pages, bindings, skins etc.
Need a system that supports strict typings to ensure all components listed can be rendered in a functional way

Toolbox - Make tip lists collapsible

Tip content includes list items via List_intro and List_item types. List items should use simple angular animation to adjust height on click to show/hide list item content on click of the list intro element.

An open/close animation already exists that can be used for this (just need to add a variable to track which are expanded), should be refactored out of goals module first.

Needs more 80's songs

Perhaps the hit "I wanna dance with somebody" or "You're the one I want"

Show steps to progress through a module

Home - minor style updates

From Orli:

I just wanted to say that I made some changes to the "my journey" menu. I forgot a module "Positive Instructions" and only realised it now. Then I have changed two icons and one title on Ohad's request. The "Family Budgeting" and "Risk Mapping & Dealing with Crisis" which is now "Keeping My Teen Safe" icon have changed. I have to add a new colour which has shifted all the colours. I hope this is ok.

@KingMike100 - I'll assign to you to see if you can figure out how to update to match the new figma (below)
https://www.figma.com/file/lRC6J2blgshWl6yPwxtX9h/Icons?node-id=86%3A0

Home Page - Get latest specifications and mockups

Mentioned plans to create new figmas for how the home screen should work which will need implementing in a fairly short turnaround. These could potentially be replacing other module screens, such as my journey and reminders. Once received should create new issue to better outline exactly what is required.

At the same time we will want to look to moving page definitions to excel-style data structures, at least extracting ids of clickable elements, their triggers and text.

DB - Start process of adding offline-online database sync

We will want to implement: https://dexie.org/docs/Syncable/Dexie.Syncable.js.html
I think we will likely want to convert our existing repo into a monorepo so that we can maintain the db-scripts codebase in the same location as the place as the frontend application. For this I will be recommending we refactor to use nx.dev

To start I suggest you go through the tutorial docs and create a demo/testing project that has a node API that can connect to a postgres db (installed locally). From there we can work together to migrate the existing codebase to a monorepo, and add server deployment and bindings

Enable chat flow to be loaded by id from goals task-action

Need to refactor chat so that a flow id can be passed as an input prop and launched. Ideally should also run in a modal so that on completion user returns to goals page.

Add redirects to staging site

Currently direct navigation breaks because all urls should be served via the main index.html. I'm not sure if the load balancer supports a rewrite to correctly handle a single-page-app, or if we will need to fall back to firebase or netlify for hosting (still building on github actions) as mentioned in #110.

Might be of use: https://cloud.google.com/load-balancing/docs/https/setting-up-url-rewrite

Add reward animation component

As discussed, we need a general component that can be opened either from a model or included in any other template as part of a rewards system.

Specific requirements:

• Accepts id as @input property for specifying the reward id
• Accepts animate prop which will be used to trigger animation on create
• Reads animation json from assets folder (given by reward id)
• When mounted (using either onInit or ionViewDidEnter lifecycle) should load the animation json from assets and play (if animate specified from prop)

Nice-to-haves

• Display mode that can be used statically (possibly the last frame of the animation, or maybe a standalone image - tbc)
• Could possibly also include a text input property to also display a message (not currently requested, but could be useful)
• Provide fallback animation if the specific id isn't found

General info

• A couple starting ids can be seen in the AwardsList tab at: https://docs.google.com/spreadsheets/d/1x8hluzT4IwEPapyNsknciKdv1Bc9z8WiF7ZxTCrnoPY/edit?usp=sharing
• Recommend just using whatever stock animations can reasonably be found for now.
• It's not sure exactly how we will be calling it yet, likely via a modal but that should behave mostly the same way as if included in HTML template, e.g. `
• The component should sit in the features/goals folder, and can use any existing services or create a new one there if required (or can just handle logic from component ts)

Launch a section of the app when clicking on a section in the module steps

When clicking on one of the steps in a module, open a chat flow, toolbox or other section of the app

Auto-populate all data from gsheets

A few things that we need to consider before implementing:

1. What's the best way to download the source sheets? Manual? Script?
   I'm guessing as we might want multiple sources as parts of different build pipelines at some point will want to use google sheets API to download an entire folder, and then convert/populate

2. What about assets?
   I'm guessing we will want to allow assets to be included in same google folder, so that any assets available automatically overwrite default build assets. Will need to decide whether to handle as part of nested folder structures, or tidy up naming and go for a flatter folder structure.

3. What file format's best for outputs?
   Up till now have been using JSONs, although it might actually be easier to convert to .ts with the json content as a default export so that we can also use linting to check if data has been defined correctly. It also means we can use data directly without awaiting HTTP imports and can implement tree-shaking.

4. What should be checked into source control?
   There are trade-offs of having all data within source control to avoid surprises of changing data, vs keeping a cleaner git history and conflict management. I'm leaning towards keeping converted data within git, as I have a feeling that future build pipelines will likely opt for a common core of data and then custom overrides (e.g. a country-specific deployment may want to only change some data but keep aligned with main updates)

5. How can we make it easier for authors to see updates in the app or different build variants (e.g. country-specific deployment)?
   Short term I'm leaning towards a simple page/button in the app where a user can drop an xlsx file, automatically run the existing conversion script and updating the current data service (or whatever is storing a master copy of all data read into the app) with the new data. Open to suggestions

It would be good to get your thoughts on these points @michaelclapham, I don't think it will be on the roadmap for this upcoming release (v0.5.0) but likely shortly after.

Swap over staging site host and build cloud

Currently using netlify however this doesn't provide easy ways to share the project across multiple users and also quickly reaches limits of free build minutes.

Suggest either:

• Use github actions for build scripts and just deploy to netlify
• Use github actions for build scripts and deploy to firebase
• Use circle-ci for build scripts and deploy to netlify or firebase

For all cases we will likely want to keep existing URLs pointed at the staging demo site

Any thoughts @michaelclapham ?

Improve how goals service and components share data updates

Currently, the data structures are too top-down - all data is loaded on intialisation and everything has to be fully refreshed when a task is marked as complete. Ideally want to be able to apply incremental updates and see component changes without heavy reload or re-rendering

Upgrade to angular 11

https://blog.angular.io/version-11-of-angular-now-available-74721b7952f7
https://github.com/angular/angular/blob/master/CHANGELOG.md

A few features from latest update would be particularly good to have in

• Faster build times
• Improved hot reloading
• i18n improvements

Upgrade guide: https://update.angular.io/

Recommended postinstall

• Add --hmr to serve scripts and test if working as intended
• Add ngcc as a postinstall script in package.json to remove compile step during serve

Future todos

• migrate tslint to eslint (low priority)

Core - Add 'development' page and test flow bindings

We continue to add features which are designed to be mostly just used for development. Most currently sit in the settings page, I suggest we add a new module with pages for development, from which we can do things like launch specific flow, enable the theme editor etc.

Additionally, we should add another button to launch a new Demo Flow, which will be created by the content team as a main feature test and demo (walking through one-by-one core features of the chat, such as questions with user inputs, launching other flows etc.). This flow can also form a backbone for our own e2e testing of the chat module.

We will still want to keep the settings page with things we actually want the users to configure.

Chat - Make chats resumable

Likely through some sort of local storage or session storage (or service), we have a mechanism to warn on exit (#134) but would be good to have an option and way of resuming

Needs more 80's songs

I'm thinking the hits "I Wanna Dance With Somebody" or "You're the one that I want".

Once I get some time I'll try adding them myself and submitting a PR.

Implement new home system designs

https://prezi.com/erjdqfbhtz-t/new-app-design/?utm_campaign=share&utm_medium=copy
Slides 9-15

Huge task, to be further broken down during planning meeting

Needs more 80's songs

I'm thinking the app needs more songs from the 80's.

How about the classic hit "You're the one that I want".

If I get time I'll do this myself and submit a pull request.

Chat - UI improvements

Should try to implement more closely latest figmas. A few specifics:

• Button/image sizing
• Multiple select styling (possible alternate interfaces, such as floating above content)
• Story mode styling and transition speed

Notes for QA:

• Go to Settings page via top left menu button, in order to test chat responses coming up in modal

Toolbox - Update routing to show 1 sheet per route

Currenlty http://localhost:4200/toolbox/topic/ONE_ON_ONE_TIME shows multiple tips.

Should rework routing to use params for toolbox module and name, e.g.. /toolbox/:module/:flow_name to display content defined in https://docs.google.com/spreadsheets/d/1Bqo1_oHqe0DjoxxhjASQJsMptlFuT8sQnH85LCMzSts/edit?usp=sharing.

e.g. /toolbox/ONE_ON_ONE_TIME/1on1_Ideas will render just the specific 1on1_ideas content

Open Welcome Flow is not opening Open Welcome Flow

https://plh-demo1.idems.international/settings

Chat - Dynamic speech bubbles for stories

It's clear that at some point we will need to put speech bubbles in story content with dynamic sizing (or possibly just scrollable?), with some reference to image background and speech bubble placement.

Remove parts of app that are no longer wanted

• Fun Activities
• Songs
• Stories

Hide use button home screen setting

Hide use button home screen setting

Add developer only setting for showing current flow name

In settings have option to turn on showing of flow name in the UI.

This will be for QA testing.

Triage QA issues

We should give a once-over to the feedback doc and assign git issues for things we plan to fix for 0.6.0.
https://docs.google.com/spreadsheets/d/1gxlIX4cqe_YhsdLo4Cw-aF_ZwHjFw90quldjDKl3sU8/edit?usp=sharing

Bug - When screen is full of messages, you can't see bot typing animation

When screen is full of messages, you can't see bot typing animation at the bottom.

Dev Notes
This appears to be due to the auto scrolling not scrolling to where the bot typing dots are.

Toolbox - refactor folder and data structures

Currently things are a bit spread out, should try to isolate toolbox code in a way similar to chat and reminders module, with all code sitting in src/app/feature/toolbox. Noteably:

• Move services to feature folder
• Add data folder and write data from xlsx files
• Remove hardcoded data and instead import from migrated xlsx data within components and services

Bug: Audio not working on Android and playing twice on web

When opening "Help me now", "Take a pause", "Stories" on Android no audio plays.

When opening on web for the second time two versions of the same audio file play at the same time.

Chat - Add user option to specify default message delay

For a first instance could just have a simple slider for read speed or similar (available in settings) which sets the default variable used for message delays. Maybe we can include a few hardcoded options [slower 1 2 3 faster] that correspond to a few fixed values (5000ms 3000ms 1000ms) or similar. Probably best not to expose direct numbers to avoid confusion

Notes for QA:

• Open settings page via top right menu button.
• The option Chat Delay let's you pick Slow, Medium or Fast
• Slow means the bot will spend 5 seconds typing the message before sending it to you
• Medium means a 3 second delay
• Fast means a 1 second delay

Chat - show warning message if exiting abruptly

Can hopefully be linked in simply enough with component lifecycles or route guards - a simple alert prompt to confirm the user wants to leave would be sufficient for now

Notes for QA:

• Test this by going to the My Journey Screen and trying to click the home button or the back button on your device.

Chat - fix live chat triggers

Hardcoded triggers have been removed, will need to find a way to launch live chats having read local json (are the triggers defined there?) or agreeing with content team alternate system (e.g. all chats triggered by their own id/name)

Can you get rid of the word today in my plans?

https://plh-demo1.idems.international/goals

Tasks - Redefine way routeable task actions work

Currently tasks launch flows that can navigate to things like a toolbox section. Ideally should work with content team to define syntax for direct routing. As URLs are dynamic, the action will simply receive the corresponding xlsx that defines the page (e.g. toolbox_1_on_1_tips and app will need to be smart enough to know where that will be located and whether it is a chat or static page (or anything else)

Right hand side module circles

Enable user to open any flow from dropdown in developer page

should be simple enough as all flows can be navigated to directly now via their flow_name, or similarly opened in a model passing that as a component prop as was done in the tasks module)

Handle end of flows

Update 2020-12-12

There are a few different ways a flow can end which should be handled in specific ways:

1. Links to another flow (currently handled correctly)
2. Links to a specific content page (need to fix handling, ideally presenting a button like Take me to tips if a tips page.
3. No links (needs fixing, ideally presenting a button like Return to Content to take the user back to the previous page (if exists, otherwise home).

I didn't see this button at all in some cases when testing, so added a message to say 'end of content'. Once this is resolved that message should be resolved also also.

Original Issue

At the end of a conversation flow when I click on the "Take me to homescreen" button, it does not work.

When I click on the button I get an error in the console

This is also causing an issue where it warns you about losing progress incorrectly when you try to exit the chat screen at the end of a flow.

Reminders - Define latest data structures for implementation

Ongoing work to specify. Once defined should make issues to implement.