Key-Value Data Source
A collection of variables organized in a Key=Value
structure.
The Key-Value
Data Source editor displays data in alternating
columns containing keys (variables) and their
respective value. This is in contrast to most other data source types
which present multiple rows
for a set of fields, like a spreadsheet. For example, a basketball game
score can be represented in a key-value
data source
by two entries like Home=80 and Visitor=92.
The key
corresponds to
the field name and in CWML,
<data
field="key"/> refers to
the value
of the key.
So, in the basketball example, for a text layer that
contains <data
field="Home">, 80 will be
shown
on screen (the text layer must have the data source assigned).
Instead
of text or numeric data, key-value cells may contain media (images,
video or audio). CW automatically determines the type of a
cell by
checking if it contains a media filename or URL. A single cell cannot
include both text and media at the same time.
When attempting to retrieve a media file for a cell, CW will look for
the media file in the list specified in
Footage
Search Paths/URLs, if the cell contains a relative
path, or
just a
filename. If the cell contains an absolute path, the
footage search paths setting is ignored. Semicolons can be
used to
separate multiple
path/URL entries in the
list.
A key-value source
can be created from scratch
using the editor, by adding rows
and columns (functions available in the right-click menu) and entering
keys and values in the source
table cells. The layout of the table
cells can be rearranged at any time using drag’n-drop.
Keys and values can also be
loaded from a key-value
file,
making it
possible to integrate data directly from most sources that work with
LiveText. A key-value
file is a very simple plain-text file that contains a list
of variables
in Key=Value
format. Each variable entry resides on a separate line. Here is an
example:
key1=value1
home=82
visitor=90
homepic=hometeam.png
For
each key-value line
in the
file, CW checks to see if the data source
table already has a cell with the same key. If so, the value of the
existing cell is updated. Otherwise, a new cell is created with the key
and value from the file. This effectively means that the new data from
the file is merged with the existing data in the source. In other
words, the existing data in the source is either updated or kept as-is,
but never deleted.
It is also possible to extract keys and values from local or web-based
XML or JSON
resources. For processing of
the XML or JSON
content, XQuery is used. XQuery
is a standardized
language
for finding and extracting elements and
attributes from XML documents. The power of the XQuery language makes
it possible to perform a wide-range of filtering, sorting and
preprocessing
operations on the input data.
Results of
query execution are
returned by the XQuery engine
in XML format. CW parses these query results to fill
the data source cells. Keys and values are extracted from the
lowest-level (leaf) tags in the XQuery output. For example:
<A>
<column1>value1</column1>
<column2 column3="value3">value2</column2>
<B>
<column4>value4</column4>
</B>
</A>
From the output above, CW will extract three keys column1,
column2, column3, and column4,
with values value1,
value2, value3, and value4,
respectively. The Extract setting determines whether
data will be extracted from tag (element) content (e.g. value1,
value2, value4
above), attributes (e.g. value3
above), or both.
Certain data sources provide their data in HTML-encoded
format, where
special characters are replaced with their escaped versions (e.g. >
replaced with <). To decode these properly, the
Processing
setting can be set to "HTML Decode". It must be noted that this setting
also performs space normalization.
The Input
Format setting specifies the expected format for the input
data. If set to Auto, CW tries to determine the format from the
filename extension or the Content-Type response header returned by the
server. If the input data
format is specified (or auto-detected) to be XML or
JSON, clicking on the Retrieve
From Source Now button will retrieve XML (or JSON) input data
from the File
/ URL,
execute the XQuery
on the input data and update the data
source cells
with the extracted key-value pairs. In the case of JSON input, JSON
to XML conversion is performed before XQuery execution.
When retrieving input
data from the web, any special headers for the
HTTP request (e.g. Accept
for content negotiation,
Authorization
for HTTP authentication)
can be specified in the Request
Headers section.
The Query
Processing section contains three sub-tabs that show
inputs and outputs corresponding to
each stage of query execution. The contents of each of these tabs
are updated each time the XQuery for the selected data source is
executed.
- Reply displays
the data that was received from File
/ URL
as a result of the initial data retrieval
stage of query execution.
- XQuery
Input displays
the XML data that is fed as
input to XQuery processing. In the
case of XML input data, the contents of this tab are the same as those
of the Reply tab. For JSON input data, this tab contains the automatic
conversion of the JSON data to XML format. Any problems with
the
JSON-to-XML conversion process can be identified through this tab.
- XQuery
Output displays
the results of the XQuery
processing. Any errors related to
the XQuery code itself, or any errors that occur during the execution
of the XQuery are also shown here.
To refresh the data
source edit set
automatically whenever the
input file changes, enable File
Tracking. With file tracking enabled, the edit set update
will take
place in the background
even when the data source is not displayed in the data editor.
In addition, use the Auto-Update
button to update the active set as changes occur.
When Retrieve
Periodically
is enabled, key-value retrieval is executed periodically, at specified
regular
intervals. The execution will continuously take place in the
background even when the data source is not selected in the data
editor. This setting is useful when retrieving data from web URLs,
since file
tracking
is not available for these.
A data source must be updated
once
editing or query execution is complete. The update can be performed
manually or automatically. See Updating
Data Sources for more information on how the update process
works.
A
key-value source can also
directly interface
with Daktronics
scoreboards, via All
Sport CG TV Feed serial connection. Select a serial
port in the connection
line,
then select the TV
Feed type (Baseball,
Football, Soccer, Basketball, Volleyball, Hockey protocols are
available). The data source table will be populated with data from the
TV Feed and it will be updated in real-time as new data is received
over the serial line.
Similarly, a key-value
source can receive data from Kazo Vision Ultra Score scoreboards.
Select UDP as the connection,
then select Kazo Vision
Ultra Score Data Out as the protocol.
It is also possible to
interface to FinishLynx Sports Photo-Finish and Timing Systems with a
key-value source. COM (serial; 9600,8,N,1) or UDP (network) are
both
supported as
the connection.
Select FinishLynx/ResultTV
as the protocol,
and in the case of UDP, also enter the port
number (corresponding to the port number in
FinishLynx scoreboard settings). The ResulTV_ALL_Fields.lss
file must
be selected in FinishLynx scoreboard settings. The running
time, as well as all result fields will be shown in the
key-value source, and they will be updated in real-time.
When receiving data into a key-value source from external scoreboards,
it is recommended to enable Auto-Update to
instantly update CW layers with real-time data. Alternatively, more
complex setups are possible by means of CW behaviours for building
animated scorebugs.
Another possibility is
to receive keys and
values over the network, via TCP connections or UDP datagrams. This is
mainly useful for very fast and frequent real-time updates from sources
like external clocks and timers. Select a TCP or UDP connection type in
the connection
line, then enter the port
and server
IP (in TCP Client mode). CW can act in server or client roles
with TCP connections. The data source cells will be refreshed
with new data from the connection in real-time, and Auto-Update
may be enabled to instantly update CW layers.
The data protocol for
key-value network
connections is almost exactly the same as the format of the key-value
text files. The data is expected to be received from the
network as
UTF-8 encoded text, organized in Key=Value
entries,
delimited by newline characters.
Key-value network connections can also be used to complement the CW remote control
protocol
for updating layer content in real-time. Instead of sending set_text
commands to update layer content directly, layers can be referenced to
a key-value data source which receives the content intented for the
layers via the network.
The key-value data source supports expressions
for
dynamic modification of values using behaviours.
For
the basketball example, one can define a simple expression that
increments the score value. Then, a grid controller
button
(i.e. a behaviour) can be
created to activate this expression each time a goal is scored. See the section on
Data
Source
Expressions
for details.
In addition to the above, key-value cells can be turned into
fully-customizable timers.
It is possible to execute CW actions whenever the value of a
key-value cell changes. See the FieldChanged
event.
The CW installation comes with several sample projects
demonstrating different use cases for key-value sources.
Sample Project: NBA_Score_Bug_Tutorial_Project_DS_Timer_external_txt
Videos:
An
Introduction to Key-Value Source, Key-Value
Data Source Expressions
See also: Data Source,
Updating
Data Sources,
Data
Source
Expressions,
Timer
Cells.
