@strategies/henshu-app

Henshu App

A dashboard workflow that provides services to an app that uses Henshu. The backend for Henshu App is Firebase, using Google for authentication, Firestore for storing the content collections, and Storage for keeping the uploaded images from the <henshu.img> tag.

Henshu App is just a workflow wrapper around Henshu itself, meaning that you would just write your Henshu site how you normally would while letting Henshu App do the heavier lifting to manage the data lifecycle.

Documentation

Install

yarn add @strategies/henshu-app @strategies/henshu firebase

then

import { HenshuApp, useHenshuApp } from '@strategies/henshu-app';

Add environment variable to your build command

In order for Henshu App to show the published version and disable the dashboard, you must add the following environment variable to your build command:

// if using create-react-app
"scripts": {
	"build": "REACT_APP_HENSHU_ENV=production react-scripts build",
}

Usage

There is more to it, if you need, but the only requirement to setup Henshu App is to provide your Firebase config to the provider component.

const App = () => {
	return (
		<HenshuApp config={firebaseConfig}>
			{/* App */}
		</HenshuApp>
	)
};

Workflow: Using the dashboard

To enter the dashboard, use Shift+'~'.

Once in the dashboard, you can start editing content. After making edits, you should press that 'save' button in the bottom panel. Once you are comfortable with how the draft copy has come along, you can press the 'publish' button to snapshot the draft into a separate Firestore collection, which is loaded by the production build.

API

The Provider

Langs: string[]

Adds a language selection dropdown to the dashboard. The selector allows the editor to switch between languages, which is kept in Firestore as separate documents. The languages provided in the array should be ISO-639-1. Each language is saved and published independently If no langs are provided, the default language is 'default'.

Seeds: {[string]: {[string]: string}}

Adds a seed button to your dashboard in the development environment. Useful for keeping a known good copy of your key/value terms to reseed the database during development. The first key/value is the language associated with it's key/value set of terms.

Example

const seeds = {
	'en': {
		'intro.header': 'Welcome',
		'intro.body': 'This is an application'
	},
	'es': {
		'intro.header': 'Bienvenidos',
		'intro.body': 'Esta es una aplicación',
	}
};

The Context

The shared context can be access through the useHenshuApp() hook. Through this hook, you can access just about all of the functionality behind Henshu App that you might need to augment how Henshu App works or how your website can become more customized depending on the current state of the dashboard.

Top Level

const { 
   isProductionBuild // boolean: Whether the REACT_APP_HENSHU_ENV env variable has been set to 'production'
	isEditing,        // boolean: Whether the user is logged in and the app is in edit mode
	setEditing,       // (isEditing: boolean) => void: Set whether editing is enabled (user must be logged in for the set value to matter)
	lang,             // string: The current language
   langs,            // string[]: Specified languages
	setLang,          // (lang: string) => void: Set the current language
	content,          // {[string]: string}: A key/value map of the current language's content
	setContent,       // (content: {[string]: string}) => void: Update the content object
	persist,          // PersistStore: The layer that handles loading and saving content
	user,             // UserStore: The layer that manages the user state in the dashboard
} = useHenshuApp();

Persist Store

const { persist: {
	save,    // () => Promise<void>: Snapshots the current content object to its Firestore document
	publish, // () => Promise<void>: Snapshots the current content object to the 'publish' Firestore collection
	upload,  // (blog: string) => Promise<string>: Stores a data URI string in Firebase storage and returns the public URL to load the asset.
}} = useHenshuApp(); 

User Store

const = { user: {
	login,       // () => Promise<void>: Launches a Google sign-in popup
	logout,      // () => Promise<void>: Deauthorizes the current session
	user,        // User|null: A Firebase User object or null
	setUser,     // (user: User|null) => void: Sets the user instance
	displayName, // string: The users displayName, derived from the user object
	isLoggedIn,  // boolean: Whether the user is present or not
}} = useHenshuApp();