Data Source
An object from which layers obtain dynamic and/or shared data,
in text or media form. Currently, CW provides ODBC,
XML/JSON, CSV, Key-Value
and BLP data sources.
In a text
layer,
the CWML
data tag, along with the field
attribute, is used to refer to data
items from a data source.
For example, in its default configuration, the XML/JSON
Data Source provides a list of news titles and links from an RSS
source. These can
be referenced in CWML
by specifying <data field="title"/>
and <data
field="link"/>. In the final output, these tags
are replaced
by the actual data items provided by the data source.
Each type of data
source defines its own set of field names. These are usually variable
(and/or
user-definable) and they are dependent on the actual data (e.g. XML
content
for XML/JSON,
or keys for Key-Value). Field names are generally case-sensitive, so
care must be taken when typing or editing CWML
data tags manually.
The contents of a data source are defined and edited using a
specific interface
that is accessed through the Data
Editor view. For example, the data editor view
for an XML/JSON Data Source allows you to retrieve the data, execute a
query and determine which rows of data should be
part of the data source
content. In addition, the data can be edited manually, if
desired. Right-click on any
data source in Attributes
> Data
Sources Box
and select View
in Data Editor to have that data source selected in
the Data
Sources Browser for editing in the Data Editor.
The Data
Editor view is shared between data sources in the project.
Therefore, the data source that is being accessed by the Data
Editor view changes when the selection in the Data
Sources Browser changes. It is also possible to open a dedicated,
dockable data editor view for a particular data source by
right-clicking on the
data source in Attributes
> Data
Sources Box
and selecting Open Dedicated
Data Editor. This makes it much more practical to edit multiple
data sources, especially when dedicated editors for related
data-sources are arranged side-by-side.
To connect
a data
source to the selected layer, do one of the following:
Once a data source is connected to a text
layer,
its
text
data becomes available to the text layer by means of the CWML
data tags that can be entered as part of the
layer content. Similarly, if a data source is connected to an image layer (and
if
that source contains any media
fields, such as images or video), it becomes possible to show the
content of those
fields in the image layer. Footage
parameters of the material and
effect
blocks of that layer will list media fields provided by
the data source as
possible input choices. Incidentally, this means that use of media
fields is not limited to image
layers, in fact they can be used as part of materials in text layers,
too, like the background of a text layer.
It is possible to link a single data source to multiple
layers, which facilitates data sharing among layers. Similarly, a layer
can
have more than one data source connected. Each connected data source is
given an index according
to its location in the data
sources box for the layer. The index is shown in the leftmost
column of the data sources box. In text
layer
content, this index is used as the value of
the source attribute of the CWML data
tag to specify the data source to obtain data from.
Usually, it is not necessary to manually go through the steps
of setting up a data source-layer connection. Dragging any data cell
from the Data
Editor
to the
Graphics
Viewer
will
automatically create a layer (text or image, depending on the type of
data cell), link the data source to it, and set the layer content to
refer to the data cell/field (CWML
tags for text, or footage
input for images). If you drag the data cell to the text content editor
for an
existing text layer instead, the data source will be connected to the
text layer (unless it already is), and the CWML tag will be
inserted at
the drop location in the text.
In addition to the tags and attributes mentioned above,
CWML
provides a number of tags
and attributes that enable using data from data sources in a number of
common scenarios (e.g. capitalization of text, or formatting
of
cell values). For details, consult the
CWML
Reference
Chart.
Besides the data source types listed in the beginning of this section,
CW provides two special data sources, named XQuery Table Source and XQuery Key-Value Source.
These sources do not retrieve data from external sources, instead they
accept data from other data sources as input. The input data is processed by running the given XQuery code and the results are output in table or key-value structure, respectively. To specify
the input data sources, a data
sources box, not unlike the one used by layers, is used. In the
XQuery code, special variables in the form of $dsn are
used to access
the input data, where n
refers to the index of the desired data source
in the data sources box. Depending on the type of the input data
source, such a variable will contain an XML document that may conform
to the table output structure or the key-value output structure.
The XQuery Table Source and XQuery Key-Value Source provide execution
settings and controls that function similarly to their XML/JSON and
Key-Value Data Source counterparts. One notable difference is in how
Input Tracking operates. Instead of changes in a given external
resource (such as the input XML file), changes in the input data
sources are monitored. In other words, when Input Tracking is enabled,
the XQuery is executed (and the data source contents updated) whenever
one of the input data sources is updated.
There are several scenarios in which XQuery Table Source and XQuery Key-Value Source are useful:
- To provide a filtered
and/or sorted version of an input data source.
- Derivation of new data
from existing data, which is especially useful in case the
dimensionality of the derived data is different (One of the sample
projects uses such data sources to automatically generate data points
for X and Y axes of a line chart).
- Conversion of data between
key-value and table structures (Certain specialized data sources are only accessible via regular Key-Value sources).
- Dynamically computing URLs for use with XQuery's own data retrieval facilities (such as those provided
by the HTTP Client module) to facilitate the use of more complex, multi-stage APIs.
To make it easier to navigate the potentially-complex project structure
that can arise from having interlinked data sources, CW provides the By
Connection view. As opposed to the Flat List view, this view presents
the data sources as a tree where dependent data sources are placed as
children of their input data sources. This puts interconnected data
sources in the same tree branches, facilitating traversal.
It should be noted that, since a data source may accept data inputs
from multiple data sources,
the same data source may occur in several positions in the tree. Both
views allow filtering by name, making it easier to locate data sources
in complex projects.
The Data Library contains data presets, which are saved collections of
data source objects,
complete with parameter values and inter-source connections. These are
intended to provide practical, reusable setups for commonly
available data sources as well as sample setups for some commercial
data providers.
See Also: Data
Source Expressions, CWML, ODBC
Data Source,
XML/JSON Data
Source, CSV Data
Source, Key-Value
Data Source. Data Library
