Field flow - Documentation

Purpose

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

This plugin is highly customizable and works in three phases

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

Usage

Working example

English:

• Working example
• Basic configuration
• Advanced
• Alternatives

French:

• Example pratique de déroulement de champs
• Déroulement de champs avec des configurations de base
• Déroulement de champs avancé

How to implement

Also take a look at the various working examples.

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

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

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

   <p>Find the plugin for the action you need.</p>
   
   <ul>
   	<li><a href="https://wet-boew.github.io/v4.0-ci/demos/data-ajax/data-ajax-en.html">Inserting content</a></li>
   	<li><a href="https://wet-boew.github.io/v4.0-ci/demos/lightbox/lightbox-en.html">Photo gallery</a></li>
   	<li><a href="https://wet-boew.github.io/v4.0-ci/demos/charts/charts-en.html">Draw charts</a></li>
   	<li><a href="https://wet-boew.github.io/v4.0-ci/demos/details/details-en.html">Expand and collapse content</a></li>
   	<li><a href="https://wet-boew.github.io/v4.0-ci/demos/equalheight/equalheight-en.html">Set a consistent height</a></li>
   	<li><a href="https://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="https://wet-boew.github.io/v4.0-ci/demos/data-ajax/data-ajax-en.html">Inserting content</a></li>
   		<li><a href="https://wet-boew.github.io/v4.0-ci/demos/lightbox/lightbox-en.html">Photo gallery</a></li>
   		<li><a href="https://wet-boew.github.io/v4.0-ci/demos/charts/charts-en.html">Draw charts</a></li>
   		<li><a href="https://wet-boew.github.io/v4.0-ci/demos/details/details-en.html">Expand and collapse content</a></li>
   		<li><a href="https://wet-boew.github.io/v4.0-ci/demos/equalheight/equalheight-en.html">Set a consistent height</a></li>
   		<li><a href="https://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 you are planning to use the advanced functionality of this plugin. Preparation steps could include, but are not limited to, the following:

• Define what is the main result (business goal) you want, like inserting content, redirecting the user, filtering tables, etc.
• Design a full decision tree that represents 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 approval of the logic of your mapping with a web specialist that knows and has experience with using this plugin. He should be able to let you know the feasibility and the complexity.
• Develop an early prototype and finalize feasibility tests
• 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 initiates 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 its 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 registered to the field flow control
• When a selected option has action
  • [Control] Reset: Reset the initial state of the control, as configured
  • [Action] Clean: Clean the task from the previous executed action
  • [Action] Action: An option was selected and an action needs to be executed. Action can be postponed until form submission.
• When the form is submitted
  • [Action] Submit: When an action is postponed, trigger upon form submission. An action could prevent the form submission.
  • [Action] Submitted: Triggered after all the submit actions have been completed and just before the final form submission happened.

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 actions to perform when one specific item is selected. Some actions are incompatible,since it makes no sense to insert content through ajax and redirect 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 acts similar to 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 an 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 hasn't been 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. Events that are specifically related to an action are scoped to the field flow control that has initiated the action. By default, field flow controls do not conflict with other field flow controls or subsequent field flow controls.

<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

Field flow source code on GitHub