Repository files navigation

A web-appPeople Affected can use to lookup useful organizations and information.

⚠️
To quickly create a new instance, follow the Guide:How to set up an instance (quickly)

Latest releases and notable changes are in theCHANGELOG.

The Helpful Information App (HIA) is a web-app that can show a list of 1 or more "regions", each of which is a separate dataset of structured content. This consists of "Offers", sorted in "Categories" and (optional) "Sub-Categories".

The web-app is a pre-build, static web-app that lists links to "regions", which are all separate data-sources contained in Google Sheets 'files'.

The different sheets within these 'files' each have a different data-model. So that their content can be used to display in the web-app.

The contents of these sheets is loaded at runtime by the visitor's browser from the "Google Sheets API".

Once the web-app is configured (SeeConfiguration) and deployed (SeeDeployment) its content can be managed via theGoogle Sheets interface.

⚠️All content of the web-app can be controlled by the contents of the Google Sheet in use.

So take appropriate precautions regarding file-ownership and "edit"-permissions of these files and the related Google Accounts.

• Limit the amount of users/Google Accounts that have "edit"-permissions to the 'least possible'
• Don't share the credentials/passwords of these accounts with multiple people
• Use a strong password on these Google Accounts
• Use all possible extra security-features on these Google Accounts, like 2-factor-authentication etc.

⚠️Everything is visible on the website onevery 'save' (so, immediately, most of the times).

• Don't change thename of any sheet.
• Don't change the#tags in the columns-headers in any sheet, the name/label/heading can be changed/translated.
• Don't use formatting-tools in Google Sheets (bold/italic/underline/fonts/colors); It will not be used.
• Don't use the "insert link"-feature.
  The plain text in a cell should be the full URL.

Optional:

• All columns can be reordered, as long as their#tags remain in their header-cell.
• You can use the toggle in the "Visible?"-column to prepare a 'draft' of a row and finally 'publish' by setting it to "Show".
• You can use background-colors to mark/highlight any changes or 'flag issues'; These styles will not be used in the web-app.

To support (some) formatting and structuring in some (multi-line) fields, theMarkdown-syntax can be used.

An explanation of (a lot of) the features of this syntax can be found in theMarkdown Guide Cheat Sheet. Noteverything beyond the "Basic Syntax" is supported in all fields.

• Install environment requirements:

  Install the Node.js version specified in the.node-version-file.
  To prevent conflicts it is recommended to use a 'version manager'.

  • fnm (for Windows/macOS/Linux)After installing, run in this directory:

    fnm use

• Install dependencies (from this directory):

  npm install

• To finish you local set-up, run (required only once):

  npm run setup

• Start in development-mode:

  npm start

• Start in production-mode:

  npm run start:production

Some specific information needs to be configured before use:

• For use in development:
  Set these different properties in theenvironment.ts-file.

• For use in production:
  These values need to be set in the.env-file. Or as ENV-variables via other means.

• For deployments:
  The ENV-variables defined in the.env.example-file need to be defined in the build-environment according to the specific deployment-tool/service.
  See for example theGitHub Action workflow (production).

• To be able to use theGoogle Sheets API a 'credential' in the shape of an API-key is required.
• To get an API-key, follow the instructions:Guide: How to set-up an instance / Create a Google Sheets API-key
• Configure the restrictions on the API-key following:
  https://cloud.google.com/docs/authentication/api-keys#adding_http_restrictions
  Make sure to includeonly the domains/referrers that will be used.
  Also includehttp://localhost:4200/* andhttp://localhost:8080/* to be able to load data during local development. (Or even better; create a separate API-key for that)

As part of the installed dev-dependencies, we usePrettier to format our code.
To use these settings without a local setup, use thePrettier Playground in your browser.

When installing locally, we usehusky to automate the formatting and testing (when not already handled by your editor).

To use a local API, without the need for any Google account/credentials:

1. Update the localenvironment.ts-file with:

       regions:'test-local-1',regionsLabels:'Test Local 1',regionsSheetIds:'test-sheet-id-1',google_sheets_api_key:'<can be anything, will be ignored>';google_sheets_api_url:'http://localhost:3001',

2. Run (in a separate process/terminal):

   npm run serve:local-data

3. Adjust the JSON-files in thedata-directory to try out different content.

Automated tests are configured and can be run (once) with:

npm test

During development, an automated watch-process can be run with:

npm run test:watch

• Workspace recommendations for VS CodeWhen you useVS Code and go to: "Extensions" and use the filter: "Recommended";A list should be shown and each extension can be installed individually.

• Ionic v8

  ⚠️ TheIonicons icon-set is NOT included in the final build, so cannot be used 'by default'. Icons can be added manually.

• Angular v18
• ngx-markdown is used to process Markdown-content into HTML.No optional dependencies are included/used.

Most (development-)dependencies in this repository are monitored by the GitHubDependabot service, to keep them up-to-date.
Unfortunately most individual dependencies are 'linked' to related dependencies that need to stay 'in sync'.

To update all Angular and ESLint related dependencies, run:

npm run upgrade:angular

Based on the data fetched from the Google Sheets, an internal data-structure is build. This is used to render the interface.

The following areillustrations only, to help get an overview, it might not be up-to-date with the actual code.

The code below can be easily edited/previewed using theMermaid.live editor.

%%{ init:{ 'theme':'base', 'themeVariables':{'lineColor':'blue'} }}%%classDiagram  class App {    ENV    regions    regionLabels    regionSheetIds  }  class Region {    slug    label    googleSheetId  }  class Category {    int categoryID    slug    bool isVisible    icon    description  }  class SubCategory {    int subCategoryID    slug    bool isVisible    icon    description  }  class Offer {    int categoryID    int subCategoryID    chapterName    chapterSlug    bool isVisible    int offerId    slug    offerName    icon    + ...many more properties  }  class QASet {    int categoryID    int subCategoryID    bool isVisible    int id    slug    parentSlug    question    answer    Date updated    bool isHighlight    array~QASet~ children  }  direction LR    App -- "1..*" Region    Region -- "1..*" Category    Category -- "0..*" SubCategory    SubCategory -- "0..*" Offer    SubCategory -- "0..*" QASet    QASet -- "0..*" QASet : children

The code below can be easily edited/previewed using theMermaid.live editor.

%%{ init:{ 'theme':'base', 'themeVariables':{'lineColor':'blue'} }}%%classDiagram  class GoogleSheet {    string id  }  class ReferralPage {    Key-Value rows [];  }  class Help {    Documentation only  }  class Options {    Only for uses in the Sheet itself  }  direction TB    GoogleSheet -- "1" ReferralPage    GoogleSheet .. "1" Help    GoogleSheet .. "1" Options    GoogleSheet -- "1" Categories    GoogleSheet -- "1" SubCategories    GoogleSheet -- "1" Offers    GoogleSheet -- "1" Q_As    Categories : rows []    SubCategories : rows []    Offers : rows []    Q_As : rows []

See the options in the.env.example-file.

Each Instance:

• can have 1 or multiple Sheet(s), each:

  • has a unique URL-slug ([a-z0-9._-])
  • has a human-readable (short) label (can contain capitals, spaces, numbers, emoji, etc.)
  • has aGoogle Spreadsheet ID, a 44-character string (from:https://docs.google.com/spreadsheets/d/___SPREADSHEET_ID___/edit?usp=sharing)

• can have a customized 'color scheme' (and other CSS), by adjusting the contents of theoverrides.scss-file.
  This needs to be donebefore building the web-app. (See for example:[.github/workflows/deploy-staging.yml](.github/workflows/deploy-staging.yml#L50)).

See the options in the "Referral Page"-sheet:

• it has a#KEY-column with all available properties(Using#tag.sub-tags, fromRegionDataKey) and#VALUE-column with their current value.

Each (Sub-)Category:

• can have a (single line) name
• can have a URL-slug ([a-z0-9._-]);
  Thisneeds to be unique within all Categories; For each Sub-Category it needs to be unique within its parent Categoryonly.
• can have a multi-line description,Markdown syntax can be used for structure/formatting.
• can have an (absolute/relative/data-) URL for an icon
• can be hidden by setting the "Visible?"-column toHide.

Each Offer

• needs to have aCategory ID and aSub-Category ID set.
• can have a URL-slug ([a-z0-9._-]);
  Thisneeds to be unique within its parent Sub-Categoryonly.
• can be hidden by setting the "Visible?"-column toHide.
• can have a Chapter-name (in plain/normal text);
  This will be used to group Offers within their parent Sub-Category.
• can have some multi-line fields,Markdown syntax can be used for structure/formatting in those.

Each Q&A-set

• needs to have aCategory ID and aSub-Category ID set.
• needs to have anAnswer value
• can have a URL-slug ([a-z0-9._-]);
  Thisneeds to be unique within all Q&A-sets.
• can be hidden by setting the "Visible?"-column toHide.
• can be shown as a Sub-Question by setting theParent-column to the Slug of another Question.
• can have a "(last) updated"-date set, to indicate its 'freshness'
• can have a multi-lineAnswer,Markdown syntax can be used for structure/formatting.

• Each Q&A-set can be shown in the Highlighted-overview by setting the "Highlighted?"-column toYes.
• All these sets will be shown with their Category/Sub-Category-context (with links).
• Their "(last) updated"-date is shown prominently, for easy scanning/spotting "what's new?"
• The sets with a "(last) updated"-date will be shown with the "most recent"-date first, thosewithout a date are shown after, in the order they appear in the sheet.

Using the search-input Q&A-sets can be filtered to match 1 or more keywords to theQuestion OR theAnswer values of a Q&A-set.

• Keywords are case-insensitive, soHelp will matchhelp,HELP orHeLp
• Some special characters will be ignored, like+,*,[,],(,), etc. Periods (.) can be included in keywords to match URLs
• Each keyword needs to be separated by spaces (not, or;, etc.)
• To include spaces in a keyword, surround with:" (double quotes)
  For example:help "Red Cross" will matchhelp orRed Cross

The web-app can be deployed as a static single-page-app or PWA.

• Make sure the.env-configuration is prepared. See:.env.example

• To generate a directory(www) with all HTML, JS, JSON and SVG assets, run:

  npm run build:production

• This directory can be deployed to any hosting-solution (supporting HTTPS), usingthe recommended server configuration.

To deploy the web-app usingAzure Static Web App service:

• A GitHub-Actions workflow needs to be defined,
  See:.github/workflows/deploy-production.yml
• The configuration of URLs, Headers for the web-app is defined,
  in:staticwebapp.config.json
  See documentation about the format inthis example configuration file

To deploy the web-app using or a static-files web-host, see options at:https://jamstack-deploy.vercel.app/ or articles like:https://www.hostingadvice.com/how-to/best-static-web-hosting/.

Configure and build a 'production'-build of the web-app following the stepsdefined at "Deployment".

Follow one of these'guides' from Surge.

Released under the Apache 2.0 License. SeeLICENSE.