webEditors

This module contains a number of modules and libraries, built on bajaScript
and bajaux, that allow interaction with a Niagara station using HTML5,
JavaScript, and CSS technologies.

webEditors contains a large number of different libraries, but the public
interface is centered around one primary use case: enabling you to create your
own HTML5 field editors for use in the HTML5 Property Sheet and other next-gen
Niagara 4 web applications.

Creating a Field Editor

Before beginning the process of writing a field editor, please consult the
documentation for
BajaScript and
bajaux.

In order for Baja values to be editable in the Property Sheet, Field Editors
must be implemented that are capable of displaying those values and saving
changes to them. In Niagara AX, these Field Editors were created for the AX
Property Sheet by extending BWbFieldEditor and implementing them in Java. In
Niagara 4, the Property Sheet has been reimagined using HTML5, and the field
editors are implemented using the new bajaux JavaScript framework.

Writing and Testing Your Code

In Niagara 4, modules have been split into parts: an RT part for runtime code, a
WB part for Workbench code, etc. HTML5 application code goes into a UX module
part. When beginning development on a new UX module part, we highly recommend
that you use some of the open source tools Tridium has created to get up and
running. Please see the help section on Building JavaScript
Applications
for info on getting
your development environment set up, and for a preliminary tutorial.

In particular, the section on implementing BIJavaScript and registering as an
agent on your Type will be a requirement.

Different Form Factors, and Pop-Out Editors

As part of the bajaux
documentation, you learned about the role of Form Factors in the bajaux
framework.

In most cases, as in Workbench, a field editor will be used to edit a Baja value
on the Property Sheet. To enable this, you'll want your BIJavaScript class to
implement BIFormFactorMini, thereby marking it as a "mini" widget that is
well-suited to fit inside a row on the Property Sheet. If this is sufficient for
your use case, then you're finished - the Property Sheet will pick up on the
agent registration and automatically show the correct Mini widget for your Type.

But sometimes you might want to edit a widget in more detail than could
comfortably fit inside a Property Sheet row. An example of this is a Facets
instance - the Property Sheet row contains a small amount of information, but a
button allows you to pop up a dialog with more controls, allowing you to add and
remove Facets tags and edit their values.

The editor that appears in the dialog will have a form factor of Compact:
something in between Mini and Max. By also implementing BIFormFactorCompact,
you will cause an "edit" button to appear in the Property Sheet row for your
value. When clicked, this button will pop out the Compact editor in a dialog for
more detailed editing of that value.

(Note that you can do this by creating two completely separate editors, one Mini
and one Compact, both registered as agents on your Type. Or, you can create just
one editor, whose JavaScript implementation behaves differently based on the
Widget's form factor, and whose BIJavaScript class implements both
BIFormFactorMini and BIFormFactorCompact. Either solution will work.)

On Field Editors and doRead()

Although bajaux does not place a restriction on what type of value doRead()
can resolve, it's recommended that field editors intended for use in the
Property Sheet have doRead() resolve a value of the same Type that was
originally loaded in. This helps to ensure proper behavior of the pop-out Edit
button and validating individual rows.

Public Modules in webEditors

The webEditors module contains dozens of JavaScript modules and utilities.
However, webEditors is new for Niagara 4 and under constant improvement, so
only the modules described in this section are considered public. Tridium will
make its best effort to keep these APIs as stable as possible moving forward
into new versions of Niagara 4; breaking changes will be kept to a minimum and
documented with release notes. Consider these modules analogous to javax.baja
packages in the Niagara Framework.

You are welcome to explore and make use of the other JavaScript modules in
webEditors, but any not listed here may be removed or drastically changed in
future versions.

BaseEditor

BaseEditor is a
subclass of bajaux/Widget. While a vanilla Widget can load in values of any
type, BaseEditors are more specialized for loading in Baja values.

The set of field editors provided in the webEditors module (like
StringEditor, AbsTimeEditor, etc.) all extend from BaseEditor for
Baja-specific functionality. When implementing a field editor to hold a Baja
value, extending BaseEditor will simplify your implementation and help it
integrate more cleanly with fe.

fe

fe is a module that allows you to
instantiate widgets for particular Baja values. Essentially, you hand it a
value, and it handles the work of deciding what kind of editor to create for
that value, dynamically retrieving the code for that editor, and building it
into your page.

fe is short for "field editors" because it's very common to use it to
instantiate a field editor for a particular Baja value, but it is not limited to
this case.

For example, say I have a Component, and I want the user to be able to edit
its string slot. By using fe, I don't have to worry about going out to find
code for StringEditor and the like - I just pass fe some configuration and
it does the work.

var component = baja.$('baja:Component', { string: 'enter a string' });

// i want to edit this slot, on this Complex, and put the editor in this DOM
// element. i want a Mini form factor for my editor, and set the multiLine
// property to true so i can type line breaks.
fe.buildFor({
  slot: 'string',
  complex: component,
  dom: $('#myStringEditorGoesHere'),
  formFactor: 'mini',
  properties: { multiLine: true }
})
  .then(function (stringEditor) {
    //an editor that can edit baja:String values is now loaded into my page. 

    //user types in a new string and clicks Save...

    $('#saveButton').on('click', function () {
      stringEditor.save().then(function () {
        //the string has been saved to the component!
        console.log(component.get('string'));
      });
    });
  });

feDialogs

feDialogs handles a number
of cases where you might want to show a field editor in a modal dialog, such as
prompting the user for a value or for invoking an Action on a Component.

feDialogs.showFor({
  title: 'Enter a number between 0 and 5',
  value: 0,
  properties: { min: 0, max: 5 }
})
  .then(function (result) {
    if (result === null) {
      console.log('The user clicked Cancel');
    } else {
      console.log('Result: ' + result);
    }
  });