HURUmap Dashboard

Wordpress-powered backend for HURUmap powered applications. Includes chart creation tools, snippets manager, Gutenberg blocks for WYSIWYG editorial interface, and elasticsearch integration. Main site accessible at https://hurumap.wpengine.com/

Development

We use docker-based environment for development making use of wordpress and mysql docker images.

To get started, clone this repository and spin up docker-containers as shown below. Refer to docker-compose.yml file

git clone git@github.com:CodeForAfrica/HURUmap-Dashboard.git
cd Dashboard
docker-compose up

Once containers are up, visit http:localhost and follow instructions for further installation of wordpress.

HURUmap Dashboard uses a custom react javascript plugin called hurumap. HURUmap plugin allows you to define HURUmap charts, Flourish Charts, & Chart Sections and enable you to add charts to post/page content using gutenberg editor.

hurumap build file is enqueued to the admin screen during activation. So we have to build hurumap code before we can activate it on wordpress.

cd wp-content/plugins/hurumap
yarn build

You can now navigate to wordpress dashboard http:localhost/wp-admin and log in.

Once you're logged in,

Activate hurumap theme under Appearance -> Themes from wordpress dashboard menu.
Activate hurumap plugin under Plugins dashboard menu.
Because the plugin URL structures are pretty, make sure your wordpress Permalink Settings is also set to a pretty-link option (wordpress default permalinks is ugly i.e http://example.com/?p=N)
Activate/Install other plugins you will need for your development (i.e custom posts, advance custom fields, ACF to REST API)
All done! You can now add content, use and customize plugins.

Child Theme

To create a child theme with the hurumap as the parent theme;

Create a folder in the wp-content/themes folder with the desired name eg (hurumap-outbreak-africa)
Add styles.css as a subfile which will contain all of the CSS rules and declarations that control the look of your theme. Your stylesheet must contain the below required header comment at the very top of the file. This tells WordPress basic info about the theme, including the fact that it is a child theme with a particular parent.

/*
Theme Name: HURUmap outbreak.AFRICA
Theme URI: https://github.com/CodeForAfrica/HURUmap-Dashboard
Template: hurumap
Author: CodeForAfrica
Author URI: https://github.com/CodeForAfrica/HURUmap-Dashboard
Description: HURUmap Dashboard theme for outbreak.AFRICA
Tags: hurumap, outbreak, covid19
Version:0.0.1 //<your version number>
Updated: 2021-02-23 09:37:33

*/

The following information is required:

Theme Name – needs to be unique to your theme
Template – the name of the parent theme directory. The parent theme in our example is the Hurumap, so the Template will be hurumap.

Add remaining information as applicable. The only required child theme file is style.css.

A add an image, screenshot.png to specify the image of the child theme if needed
To add acf-json files add a folder named acf-json and put in all ACF json files you wish to import. All files saved in the child theme will be saved there too

Storybook

For faster development, storybook is in place to make UI development faster.

cd wp-content/plugins/hurumap/ && yarn start:storybook

WP Engine

To deploy make sure to add your wp engine git remotes for dev and production environments:

git remote add wpprod git@git.wpengine.com:production/hurumap.git
git remote add wpdev < git@git.wpengine.com:staging/hurumap.git | git@git.wpengine.com:production/hurumapdev.git >

We also add two redirects in the redirect rules

Home; source is ^/$ and destination wp-admin
Flourish; source is flourish/(.+[^/])$ and destination ../$1/

Elasticsearch

HURUmap Dashboard uses elasticsearch to enhance wordpress search functionality along with the elasticpress plugin. For local development, we make use of the es server docker container. Once docker containers are up (i.e docker-compose up) you can visit http:localhost:9200

Activate ElasticPress plugin on dashboard
Go to the plugin settings and add your elasticsearch host url i.e http://es:9200 on Third-Party/Self-Hosted menu
Save changes and follow instruction to index your content.
Once content is sync, you're ready to use search.

WP MultiLang

In the multilang plugin, modifications were made to allow multilanguage json in post_content. This supports charts/visual definitions (i.e. hurumap-visual posttype) to have multilanguage language. The change is in plugins/wpm-multilang/includes/wpm-translation-functions.php:

	/**
	 * Karim:
	 *  Allow multilanguage json
	 * 
	 * original => if ( ! is_string( $string ) || $string === '' || is_serialized_string( $string ) || isJSON( $old_value ) )
	 */
	if ( ! is_string( $string ) || $string === '' || is_serialized_string( $string ) ) {

and

	/**
	 * Karim:
	 *  Allow multilanguage json
	 * 
	 * original => if ( is_serialized_string( $old_value ) || isJSON( $old_value ) ) 
	 */
	if ( is_serialized_string( $old_value ) ) {

Additionally, using get_post does not use the filters provided by wp-multilang. The filters allow getting the post in the language requested so instead we do:

get_posts(['numberposts' => 1, 'post_type' => $post->post_type, 'post__in' => [ < THE POST ID > ], 'suppress_filters' => 0])[0]

Deactivating & Uninstalling WP MultiLang

Deactivating the multilang plugin would result to your content being merged to one (i.e title becomes [:en]English title[:fr]French title[:sw]Swahili title). While deleting/unistalling will delete all languages except the site's default language (if you check the box Delete translations when uninstalling plugin on the plugin's general settings).

For local development you may see an error Could not fully remove the plugin wp-multilang/wp-multilang.php when deleting, this could be caused by the file & directory permission that limits PHP to write to the necessary folder/file. However, the uninstalling would have been completed.

Deployment

Follow instructions at WP Engine Git documentation site to setup your git push access for our different environments:

Development: hurumaptech
Production: hurumap

Deploy

Auto deploy using command:

Development: yarn deploy:dev
Production: yarn deploy:prod

Manual deployment:

git checkout -b <branch name>
git subtree add --prefix package <wp remote> master --squash
yarn build
yarn pack:dashboard
git add package && git commit -m <commit message>
git subtree push --prefix package <wp remote> master
git checkout master
git branch -D <branch name>

License

Wordpress-powered backend for hurumap.org.
Copyright (C) 2019 africapractice, Code for Africa

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.