Share Flow Technical Info

A technical overview and how to add new panel types

#Important: this is currently a work in progress!

Overview

Modules

List of the main modules

Blog Post Data Object

The Share Flow process builds a blog post JSON object that is submitted to Nationbuilder using the API. The blog post object structure is defined in the Nationbuilder API documentation:

https://nationbuilder.com/blog_posts_api

This is an example of the blog post JSON object from the NB documentation. 

{
  "blog_post": {
    "slug": "perspective_misalignments",
    "status": "published",
    "author_id": 5,
    "site_slug": "foobar",
    "name": "Perspective Misalignments",
    "headline": "Perspective Misalignments",
    "title": "Perspective Misalignments - Foobar Softwares",
    "excerpt": null,
    "id": 11,
    "content_before_flip": "<p>Some people just don't see eye to eye</p>",
    "content_after_flip": "<p>Lorem ipsum dolor sit amet</p>",
    "external_id": nil,
    "tags": ["funny"],
    "published_at": "2013-04-25T10:47:06-07:00"
  }
}

As we do not have control over the allowed fields in a blog post object then additional data is added to the post using blog post tags, usually in a prefix:value format. See the Data and Testing page for more information on these tags.

Panels - Content and Form

The core of the system is showing the relevant panels at each step.

The system scans the page on load and will automatically show or hide the relevant panels. Not code changes are needed, just follow these rules:

Example of simple Content Panel that will show on steps 2 and 3:

<div data-step-no="2,3" class="share-content-panel">
  Hello, I am a content panel
</div>

Share Form Modules

Share Form Module List

Each step in the share flow is handled by a specific share form module. The current modules are:

Share Module Interface

Why this module interface?

Module Interface Functions

Signup Module Structure

Each step in the sign up flow is handled by a specific module. The current modules are:

var module_share_form_example = function(config) {
// returns an object with the interface functions...
return {
load: function(data) { /* TODO */ },
validate: function() { return true; /* TODO */},
save: function(data) { return data; /* TODO */ }
}
}

Slightly more advanced notes

(This is not an issue right now, so you can ignore this bit if you are not interested)

The above code will work, but to future proof it, the current modules do one more step. The problem with the above code is that it will not work if there ever is more than one of the same kind of module needed in the share flow.

The extra code change is:

...
var module_share_form_example = function(config) {
config = config || {}; // config optional
const module = config.module || $('.module-share-form-example');
return { ...etc \

When running the init function, the parent passes the jquery element in as a module config parameter. Then the code can use this module variable to target the exact module on the page.

Automatically loading modules

A parent page can automatically load modules with the following steps:

  1. Find all the share modules loaded into the page by finding all elements with the class: $(".module-share-form").each(..)
  2. For each $module..
  3. Use the data-module-init attribute to get the init function name: const module_init_function_name = $module.data("module-init");
  4. Get the function from the globals window object: const module_init_function = window[module_init_function_name]
  5. Call the init function to create the module functions (passing in the $module as config) : const module_helper = module_init_function({ module: $module});
  6. It's then possible to call the module interface functions, ie: module_helper.validate()

TLDR

There is a working test code that automatically loads modules in _z_z_phase_4_test_api.html - https://www.reomaori.co.nz/z_test_phase_4_api_calls?preview=true