Skip to content
Approach

Interface.js

Approach Interface defines a standard pipeline for interfacing your system. GUI, TUI, API, etc.

Interface gives yuo the option to launch AJAX requests purely in HTML or a use a lot of cool combinations with Autoform and send data intents to the server.

The main functionality of approach.interface.js is wrapped up in the Interface prototype’s $elf.call functions. Most such functions match the document intent, such as: REFRESH, APPEND, PREPEND, REMOVE, etc..

The most important functions of Interface are:

  1. Interface.call.events
  2. Interface.call.Service
  3. Interface.call.Ajax

Primary Attributes

data-action: submit to a specific server object/scope if on a form. if on a control, throws this custom event

data-role: autoform, event or by default service (ajax)

data-trigger: what this control can be triggered by (click, submit, or any native event)

data-intent: use available domain-specific intents based on attached service. common transport wrapper defined. allows for request types beyond GET, POST, PUSH, OPTIONS, etc

data-context: payload of this control

And considerations for:

  • Efficient event bubbling from any control inside a controls, delegated to an ancestor Interface
  • Multiple Interface groups, allowing multiple forms to aggregate according to action within a group or submit distinct payloads in separate groups
  • Include details at time of request describing what to do with the response, with a liiiitle bit more flexibility. We’ve stress tested this set since 2013 to find the most pluggable solution we could. Mainly boils down to append, prepend, refresh/replace, remove, before, after, redirect and trigger
  • Response target can be selector or function

Creating an Interface

Including the approach.interface.js in your project will give you automatically give you access to all of the Interface functions.

To create a new Interface node, you can add a Interface class to your HTML element.

<div class="Interface">
  <h1>stuff</h1>
  <div>...</div>
  ...
  <ul class="controls MyToolbar">
    <li class="control" data-action="up.my_module"> &uarr; </li>
    <li class="control" data-action="down.my_module"> &darr; </li>
    <li class="control" data-action="left.my_module"> &larr; </li>
    <li class="control" data-action="right.my_module"> &rarr; </li>
    <li class="control" data-action="cool_event.my_module"> Click Me </li>
  </ul>
</div>

This initialization will ultimately cause each <li> shown to throw a custom event when clicked, which you may catch with your own module. By controlling a JSON object stored in data-context='{..}' you can coordinate state information between several modules, or simply use Inteface to signal events.

In this example, the div node with class=“Interface” will be equipped with a new property via JS:

[element].Interface = new Interface();

Interface object could be extended to make even more custom behavior, but for now just understand that all events caught be .controls inside a .Interface will be handled by that Interface object. This alone greatly reduces event processing. Additionally, controls will only bind listeners inside themselves to .control elements for specific events — by default click.

Placing .controls near to your actual interface elements, meaning the literal elements which a user or other code interacts with, allows you to have the “best of both worlds” scenario when it comes to Event Bubbling vs Event Delegation. Improper delegation is a major cause of display lag.

Elements that have the .control class will be used to bind event listeners to.

To augment the experience of Interface, you can also use Autoform to automagically gather form data and send it to the server.

Look at the example in the next section to learn how to use Interface.

Breaking down the structure

<div
  class='PickComponent control'
  data-role='Service'
  data-intent='{  "PREFIX":  {  "Component":"Create"  }  }'
  data-context='{
    "_self_id":null,
    "_response_target":"getSelectedLayoutSlot()",
    "which_component": "TextEmbed"
  }'
>
 <div>
    <i class='bi bi-fonts'></i>
    <span>New Text Component</span>
  </label>
</div>

This HTML tells Interface

  1. The role of this control is to launch a Service request call. Generally this means AJAX to a server.
  2. Defines the call intent, which in total requires:
  3. Response Action: one of append, prepend, refresh/replace, remove/delete, before/prefix*, after/affix*, redirect and trigger. custom actions are possible.
  4. Request Command: anything your heart desires. Should always include at least 1 domain indicator followed by a command. This may be {"url/to/scope":"command"}, {"HumanConcept":"Complicated.CommandName"} or an array of these. Interpretted by your service handler. See Approach Service for a utlity implementation and a function registrar implementation. Approach Reflection API uses this as well.
  5. Request Support Payload: also anything your heart desires, but must pair precisely with the number of commands, or else be shared between them
  6. Response Target: What to do with the response? Either one of the the call.ActionName actions baked into Interface(), on a selector, or send the response to an AJAX handling function which well return a reference to a selection after doing whatever it wishes.

*before/after push elements outside of the target. append/prepend push elements inside the target.