XML Definition

Create Your XML File

In the pre-installed controller folder mentioned on the previous page, you will find many other controllers you can use as examples. Here is a detailed description of the data that can go into an Input Definition XML file.

XML Definition

A single HTML data controller can have several inputs which dictate the variables that are sent to Captivate. Each input needs an XML file to define its properties.

Here is an example of an input behavior:

<?xml version="1.0" encoding="utf-8" ?>

<inputBehavior
  name="Controller Name: Input Name"
  url="exampleSrc/exampleApp.html"
  iconOn="exampleSrc/alien.png"
  UIGroups="General;Sports"
  version="1.0"
  index="0">
  <variable name="Name" type="text"  />
  <variable name="Logo" type="image"  />
  <variable name="HideLogo" type="visible"  />
  <variable name="Background" type="color"  />
  <variable name="Progress" type="graph"  />
  <variable name="Time" type="text">
    <pattern>[0-2][0-9]:[0-5][0-9][ap]m</pattern>
  </variable>
  <controls>
    <button name="Clear All"
        action="clearAllMessages"
        tooltip="Delete all messages from the database" />
  </controls>
</inputBehavior>

Important: The XML files must be UTF-8 encoded.

Input Behavior

The <inputBehavior> tag defines the start and end of the input behavior definition.

<inputBehavior
  name="Folder Name: Input Name. Sub Controller"
  version="1.0"
  url="exampleSrc/exampleApp.html"
  iconOn="exampleSrc/alien.png"
  UIGroups="General;Sports"
  family="Controller Name"
  index="0"
  hasHelpPanel="true"
  hasDataVariablePanel="true"
  InheritUI="false"
  uiName="Folder Name: Input Name">
  <!-- variables and controls go here -->
</inputBehavior>

Parameters:

• name - The name by which this input will be referenced in the UI and in all API calls. This must be unique among all HTML-based controllers since all HTML controllers share the same server.

  • Names should be formatted as "Folder Name: Input Name". The Folder Name portion is sometimes referred to as the Family Name, Service Name, or Controller Name, but it must exactly match the name of the folder on disk where the XML file is found. The rest of the name determines how this controller’s input will be displayed in the data controllers submenus. See the notes below.

  • Periods (“.”) and colons (“:”) can be used to create more subtrees in the UI. For example, if a controller is named "Weather Input: Temperature Inputs. 7 Day Temperature Forecast" and it has no UIGroups attribute, it will appear in the data controllers dropdown menu as:

    • General

      • Weather Input

        • Temperature Inputs

          • 7 Day Temperature Forecast

  • Note: If a controller name has no colon (:), it will show up twice in the controllers dropdown menu. e.g. Name > Name

  • Note 2: If a controller name has a colon (:), the text to the left of the colon must match the folder name where its XML file is stored or else the controller’s settings might fail to save properly when the project is saved.

• version - The version helps Captivate determine which to use if two controllers have the same name. By using a higher version number, a controller in the shared controllers location can override the controller found in the pre-installed location.

• url - The path to the HTML page used to process this input. If this is running in the embedded server, then it should be relative to the XML file. If this is running on an external server, then this should be a fully-formed url, i.e. "https://example.com/example_folder/mycontroller.html"

• iconOn - the icon used for this controller in the UI. This should also be a path relative to the XML file and should point to a square png image file.

• UIGroups - (optional) A semicolon-separated list of the UI group(s) under which this input will appear. If you leave it out, it will default to “General.” Here are some standard groupings that may be included in your edition of Captivate:

  • "API" (Programming Examples)

  • "General"(General Purpose)

  • "Sports"(Scoreboards, Stats, etc.)

  • "Gaming"(Twitch, Streamlabs…)

  • "Productivity"(Spreadsheet, Slides, etc.)

  • "Social"(Social Media)

  • "Worship" (House of Worship)

• InheritUI - (optional) - If you plan to use the same HTML file for more than one input, set this to “true” to ensure that when switching between inputs from the same family, the same browser instance and page will be used without a reload. In this way, the same JavaScript context can be preserved among multiple inputs, but your HTML file and JavaScript code will have to be written to understand the different inputs and not be confused by them.

• uiName - (optional) - When using the same URL for multiple inputs, set this field. All inputs that share the same uiName will use the same URL. Note: if multiple XML files specify different urls but the same uiName the url from the first-parsed XML file will be used.

• helpUrl - The path to an HTML page of help text.

• hasHelpPanel - If this is set, Captivate will expose a help (?) button. When pressed, it will call the global Javascript function showControllerHelp() in the embedded browser. You must implement that function yourself. (Planned for the future. Not enabled yet.)

• hasDataVariablePanel - If this is set, Captivate will expose a DATA button that when pressed will call the global Javascript function showControllerVariables() in the embedded browser. You must implement that function in the global scope. (Planned for the future. Not enabled yet.)

Notes

You might see other attributes in the <inputBehavior> tag. These are used by NewBlue for internal purposes. They may be safely ignored and won’t be of any use in a custom controller. Specifically, you might see any of the following: family, index, qaUrl, betaUrl, requiresNodeJs, wantsUniqueNodeJsInstance, and nodeJsClientUrlPath.

Although it’s possible to load controller UI from the web, if the controller is loaded from an HTTPS server you might receive Mixed Content warnings. This is because all communication with Captivate happens over an unsecured websocket connection and browsers don’t like mixing secure content with insecure content. Our current ServiceHandler library gets around this by using WebRTC connections and/or tunneled connections through a secure proxy if it can. See the Controller API Reference for more on that.

Control Definitions

<control> elements allow you to create buttons in the main Captivate UI that will call functions in the JavaScript context. This works exactly like hasDataVariablePanel and hasHelpPanel. The buttons will be placed at the bottom of the data controller panel next to the Open in Browser button. When the user clicks on the button, Captivate will attempt to call a JavaScript function identified by the action attribute in the context of the controller’s global JavaScript environment.

For example:

<controls>
  <button name="Clear All"
      action="clearAllMessages"
      tooltip="Delete all messages from the database"
  />
</controls>

When the user clicks on the “Clear All” button, Captivate will attempt to call window.clearAllMessages() in that controller’s JavaScript environment.

Variable Definitions

<variable> elements describe the names and types of the variables which the input will send to Captivate.

Example:

<variable name="Name" type="text" />
<variable name="Logo" type="image" />
<variable name="HideLogo" type="visible" />
<variable name="Background" type="color">
  <value>#ff00ff00</value>
  <value>#ff0000ff</value>
</variable>
<variable name="Progress" type="graph" />
<variable name="Time" type="">
  <pattern>[0-2][0-9]:[0-5][0-9][ap]m</pattern>
</variable>
<variable name="Time 2" type="" pattern="[0-2][0-9]:[0-5][0-9][ap]m" />

Variable Attributes:

• name - the variable’s name by which it will be referenced in the UI and JavaScript calls. If you put a . in the variable name, it will display in the Link Data panel as an expandable tree format. This allows you to categorize your variables.

  • For example: Day1.Temperature and Day1.WindSpeed will show up as Temperature and WindSpeed under the expandable Day1 item, but you still need to use the full name when updating their values. (This behavior doesn’t happen if the . is the last character in the variable name.)

• type - (optional) attribute specifies the variable type. This declaration works like a filter. When specified, Captivate will only allow this variable to connect to graphic variables that match the type. When omitted or when specified as the empty string, Captivate will allow the variable to connect to any graphic variable regardless of type. Current options include:

  • text - Text. Captivate will only allow variables of this type to connect to graphic text boxes.

  • visible - Controls graphic visibility. Captivate will allow this variable to connect to “visibility” variables in the graphics.

  • image - File path or URL to an image (jpg, png, tiff). Captivate will expect this variable to contain the full file path with extension.

    • Note: Some servers on the Internet identify images by sending image type data in Header fields only and older versions of Captivate will not be able to use those images directly. If the url to the image doesn’t work, first download them locally. See the getFileContent command in the All Commands documentation.

  • graph - Captivate will expect this variable to contain a string representing a value between 0 and 1 (with a minimum step size of 0.001) and will use it to drive a data graph field in a title. Example values will be 0, 0.5, 0.9 1

  • color - Captivate will expect this variable to contain a string value describing a color in #AARRGGBB format. A fully transparent color will start with #00... and a fully opaque color will start with #FF.... A partially transparent green will be #A000FF00.

  • Note: in most cases, you should just leave the type value out. An untyped variable can be linked to anything in the graphic and provides the most flexibility for connecting your controller to different graphic designs.

• pattern - (optional) specifies the pattern Captivate will use to pre-render possible values. See more on the next page.

Notes:

When an input sends variable values to Captivate, they should always be sent as strings. When using the JavaScript API, numbers will be automatically converted to strings. Since that behavior can be unpredictable, we recommend sending everything as a string.

When an input first loads, Captivate will automatically match variables defined by the controller to variables defined in the graphic if they share the same name.

When a graphic exposes a “visibility” variable, Captivate will display it in the UI of the Properties panel as a checkbox. Internally, these variables are represented as strings that are either empty for false or non-empty for true. In other words, to turn a visibility variable on, send any non-empty string value ('1'), and to turn it off, send the empty string (''). This technique allows the visibility of a graphic to be controlled by any variable, not just those with type visible.

HTML

If the HTML file is to be served by Captivate’s built-in server, then it should be placed, with all related files, in the same folder as the XML definition or optionally in a subfolder of that folder.

See Setup Your Folders