Field flow Documentation wb-fieldflow v1.1.0

Purpose

Provide an alternative user interface when a page contain a really long list. This plugin have two action phase, the first phase, initiation, is creating a drop down to let the user to select an option. The second phase, action, will provide result to the user like redirecting him, ajax-in content, toggle content, creating a second drop down.

This plugin is highly customizable and work in three phases

1. Generate the user interface
2. Action upon selection
3. Action upon submission

Usage

Working example

• Field flow
• Basic field flow configuration
• Advanced field flow configuration

How to implement

Take also a look of the varieties of working examples.

1. Create an unordered bullet list where each list item is a link to a page

   <ul>
   	<li><a href="http://wet-boew.github.io/v4.0-ci/demos/data-ajax/data-ajax-en.html">Inserting content</a></li>
   	<li><a href="http://wet-boew.github.io/v4.0-ci/demos/lightbox/lightbox-en.html">Photo galery</a></li>
   	<li><a href="http://wet-boew.github.io/v4.0-ci/demos/charts/charts-en.html">Draw charts</a></li>
   	<li><a href="http://wet-boew.github.io/v4.0-ci/demos/details/details-en.html">Expand and collapse content</a></li>
   	<li><a href="http://wet-boew.github.io/v4.0-ci/demos/equalheight/equalheight-en.html">Set a consistant height</a></li>
   	<li><a href="http://wet-boew.github.io/v4.0-ci/demos/overlay/overlay-en.html">Popup content</a></li>
   </ul>

2. Insert a paragraph before that list, it will be used to label the drop down (select).

   <p>Find the plugin for the action you need.</p>
   
   <ul>
   	<li><a href="http://wet-boew.github.io/v4.0-ci/demos/data-ajax/data-ajax-en.html">Inserting content</a></li>
   	<li><a href="http://wet-boew.github.io/v4.0-ci/demos/lightbox/lightbox-en.html">Photo galery</a></li>
   	<li><a href="http://wet-boew.github.io/v4.0-ci/demos/charts/charts-en.html">Draw charts</a></li>
   	<li><a href="http://wet-boew.github.io/v4.0-ci/demos/details/details-en.html">Expand and collapse content</a></li>
   	<li><a href="http://wet-boew.github.io/v4.0-ci/demos/equalheight/equalheight-en.html">Set a consistant height</a></li>
   	<li><a href="http://wet-boew.github.io/v4.0-ci/demos/overlay/overlay-en.html">Popup content</a></li>
   </ul>

3. Wrap your paragraph and the list with a <div> container to call the plugin

   <div class="wb-fieldflow">
   	<p>Find the plugin for the action you need.</p>
   
   	<ul>
   		<li><a href="http://wet-boew.github.io/v4.0-ci/demos/data-ajax/data-ajax-en.html">Inserting content</a></li>
   		<li><a href="http://wet-boew.github.io/v4.0-ci/demos/lightbox/lightbox-en.html">Photo galery</a></li>
   		<li><a href="http://wet-boew.github.io/v4.0-ci/demos/charts/charts-en.html">Draw charts</a></li>
   		<li><a href="http://wet-boew.github.io/v4.0-ci/demos/details/details-en.html">Expand and collapse content</a></li>
   		<li><a href="http://wet-boew.github.io/v4.0-ci/demos/equalheight/equalheight-en.html">Set a consistant height</a></li>
   		<li><a href="http://wet-boew.github.io/v4.0-ci/demos/overlay/overlay-en.html">Popup content</a></li>
   	</ul>
   </div>

Complex example Content preparation step

We recommend to do a content preparation step when your are planning to use the advanced fonctionality of this plugin. Preparation step could look like as the following but not limited to:

• Define what is the main result (business goal) you want, like insert content, redirect the user, filtering tables, ...
• Design a full decission tree that represent all the possible results.
• For each node (item) combination, define actions that should be taken, like:
  • Node 3 - Action 1: Insert content XYZ in the page feature container;
  • Node 3 - Action 2: Insert content ABC that have WET component;
• Review and get approved the logic of your mapping with a web specialist that know and have experience of using this plugin. He should be able to let you know the feasibility and the complexiness.
• Develop an early prototype and finalize feasibility test
• Finalise the content, for the logic and for the content, as per your internal process.
• Do a high fidelity prototype.

Abstract fieldflow event chain

• Upon plugin initialisation
  • [wet-boew plugin] Init: WET core initiate the creation of a fieldflow component. The fieldflow control is registered in the parent form
  • [extension] Ready: Notify the exention that it should init() and get his things ready to execute actions that is support.
• When creating a control
  • [Control] Draw: Read the html, standardize the output data
  • [Form component] Create ctrl: Create a component on the page (select, radio, checkbox). This component will be register to the field flow control
• When a selected option have action
  • [Control] Reset: Reset the initial state of the control, as configure
  • [Action] Clean: Cleaning task from the previous executed action
  • [Action] Action: An option has been selected, action need to be executed. Action can be postponed upon form submission.
• When the form is submited
  • [Action] Submit: When an action is postponed, triggered upon form submission. An action could prevent the form submission.
  • [Action] Submited: Triggered after all the submit action has been completed and just before the final form submission happend.

Class delimiter

Use those default class to specify thing inside you template

[class="wb-fieldflow-label"]

Indicate content to use for labeling the control

Configuration options

Document the public configuration options that can be used by implementers or developers.

Set on the plugin <div class="wb-fieldflow" data-wb-fieldflow="{...}">

Set on list item <li data-wb-fieldflow="...">

Kind of value supported:

Text

data-wb-fieldflow="..." URL Location of a file that will inserted (through ajax) in a container that follow the plugin. The data-ajax filter selector are supported. data-wb-fieldflow="MyFragment.html" is equivalent to data-wb-fieldflow='{"action": "ajax", "url": "MyFragment.html", "type": "replace"}'

Object

<li data-wb-fieldflow="{...}"> Define how the action should be performed, see bellow for all the options.

Array

<li data-wb-fieldflow="[{...}, {...}, {...}]"> Allow to set multiple action to perform when one specific item is selected. Some action are incompatible like it make no sense to inserting content through ajax and redirecting the user somewhere else.

The "action" option

Define the action to take upon selection/form submission. Based on the value, some other option could be required, optional or ignored.

• Option: action
• How to configure: data-wb-fieldflow='{"action": "ajax", ...}'

Note about "Append" required options {"action": "append", ...}

The append action act similar as when you initially configure the field flow. But instead of creating the field flow working environment it will simply add the field flow control next to the current one.

You can configure a appended control as you will have it setup the configuration option for <div class="wb-fieldflow" data-wb-fieldflow="{...}">. For example:

{
	"action": "append",
	"srctype": "tblfilter",
	"source": "#MyTableID",
	"csvextract": true,
	"isoptional": true,
	"column": 5,
	"defaultselectedlabel": "View all results",
	"label": "Choose something:"
}

The "append" action will set the srctype to wb-fieldflow by default if not specified and it will throw an error if the source haven't be set.

Configuration options for each action.

<form id="frmActionConfig">
	<div class="wb-fieldflow" data-wb-fieldflow='{
		"noForm": true, 
		"unhideelm": 
		"#frmActionConfig",
		"srctype":"tblfilter", 
		"source":"#actionConfig", 
		"column":1, 
		"defaultselectedlabel": "All the configuration options", 
		"label":"Filter by type of action:", 
		"csvextract": true
	}'></div>
</form>
	
<table id="actionConfig" class="table wb-tables" data-wb-tables='{ 
	"ordering" : false, 
	"paging": false, 
	"columnDefs": [ { "targets": [ 1 ], "visible": false } ] }'>
	<thead>
		<tr>
			<th>Option</th>
			<th>Available for</th>
			<th>Description</th>
			<th>How to configure</th>
			<th>Values</th>
		</tr>
	</thead>
	<tbody>
	
	[...]

	</tbody>
</table>

Events

Document the public events that can be used by implementers or developers. Event that is specific related to an action is scoped to the field flow control that have initiated the action. By default, field flow control do not conflict with other field flow control or subsequent field flow control.

<form id="frmEvents">
	<div class="wb-fieldflow" data-wb-fieldflow='{"noForm": true, "unhideelm": "#frmEvents", "srctype":"tblfilter", "source":"#events", "column":0, "defaultselectedlabel": "All the events", "label":"Filter by type of action:"}'></div>
</form>

<table id="events" class="table wb-tables" data-wb-tables='{ "ordering" : false, "paging": false }'>
	<thead>
		<tr>
			<th>Event</th>
			<th>Trigger</th>
			<th>What it does</th>
		</tr>
	</thead>
	<tbody>
	
	[...]

	</tbody>
</table>

$( document ).on( "wb-ready.wb-fieldflow", ".wb-fieldflow", function( event ) {
});

$( ".wb-fieldflow" ).on( "wb-ready.wb-fieldflow", function( event ) {
});

$( document ).on( "wb-ready.wb", function( event ) {
});

$( document ).on( "draw.wb-fieldflow", ".wb-fieldflow", function( event ) {
});

Source code

wb-fieldflow.js