Table of Contents
Data sources are used to create dynamic content that is updated from external data sources as described in the overview in Section 6.4, “Data Source”.
Data sources are shown in the Demorize Editor under the Data Sources category in the Project view. A data source in the Project view means a connection to the source from which to collect data. The data source definition itself does not collect any data, it just specifies how the connection shall be established. A data item, which is added to a data source, is needed in order to specify what data to extract from the data source. A data source may contain many data items in order to access different data chunks from the data source. To make an example, a data source may be a connection to a database while the data items that are added to the data source definition specifies which SQL queries to make against the database. Each of these data items are given a name that can be referenced by for example text or graph objects in a scene in order to present the data that is retrieved from the database. Some data sources, such as the RSS data source, have implicit data items that are defined by the RSS feed itself. In these cases the user will not need to add the data items herself.
A new data source is added from the context menu for the Data Sources category item in the Project view or from the Insert tab in the application menu. The properties for the new data source item must be edited before it can be used. A data source contains the following properties:
- Interval - This property is only valid if the Cache Mode is set to INTERVAL. It tells the interval, in seconds, at which the data source shall be polled for new data. For example, if this value is set to 10, the data source will execute all of its data items' queries every ten seconds and store the result for use by scene objects.
- Cache Mode - This property determines how the data is locally stored and accessed. The property can be set to DIRECT_ACCESS, STREAM_CACHE or INTERVAL_CACHE. Setting it to DIRECT_ACCESS means that the data item queries are made at the moment that someone requests the data. This may be a bad choice for data that may require some time to execute the query, such as when accessing a database or RSS feed since the data will then not be immediately available for presentation when it is needed. For these types of high latency data sources it is better to use a cached mode. Cached data items always keeps a storage of the last retrieved value. The mode STREAM_CACHE means that the data is retrieved at the beginning of a stream and when a stream is recreated. This mode is a good option if you do not want the data shown by a scene to change while the scene is shown on a screen. If for example an RSS feed is displayed, you might not want a news entry to suddenly change its text other than between appearances of the scene. The mode INTERVAL_CACHE means that data is retrieved and stored in the background at regular time intervals. The interval is specified in the Interval property. Using this mode means that data may change while it is presented on a screen.
- Type - Specifies the type of data source connection to use for this data source. This can be one of ODBC, ACCESS, TEXT, SCRIPT or RSS. This is a read only property since you specify the data source type when you first create it.
- ODBC - This is a connection to an ODBC data source. ODBC data sources are managed in the control panel in Windows. The Connection property for this type of connection can be set to the ODBC connection name (as specified in the ODBC Data Source Administrator user interface in Windows) or it can be set to an ODBC connection string.
- ODATA - Let you access data from an Open Data Protocol (OData) service. The URL property shall be set to the root URL for the OData service.
- REST - Let you access data from a REST service. The URL property shall be set to the root URL for the REST service.
- TEXT - Text data sources reference text files in your file system. The File property for a text data source shall be the text file location. Text data sources access text files depending on a schema information file named Schema.ini that must be stored in the same directory as your text file. The schema file tells how the data is formatted in your text file and can be accessed via the Schema property. Please consult the official Microsoft text driver specification for information on the content of this file.
- ACCESS - This is a connection to a MS Access data file. The File property for this type of connection shall be set to the ACCDB or MDB file path.
- EXCEL - This is a connection to a MS Excel data file. The File property for this type of connection shall be set to the XLSX file path.
- XML - Let you access data in an XML document. The Location property shall be the URL or file path to the XML document.
- RSS - Connects to an RSS feed. The URL property shall be set to the RSS feed URL.
- TWITTER - Performs a Twitter search for the given hashtag or user. The Tag property shall be the #hashname or the @user to follow.
- SCRIPT - Script data sources reference Lua script files in your file system. The Script property contains the location of the script file.
Example 16.2. Example of a Lua data source script
-- Example script data source written in the Lua language (http://www.lua.org) function Update() end function GetFieldNames() return { "Increase", "Square" } end function GetRecordCount() return 10 end function GetValue(record, field) if field == "Increase" then return tostring(record + 1) elseif field == "Square" then return tostring(record * record) end return "" end - GPX - GPS exchange format (GPX) data sources reference GPX files in your file system. The File property shall be the GPX file location.
- PACKAGE - This is a resource package that is used to bundle a number of embedded resource files. The embedded files will be distributed with the data source and can easily be referenced via the data source.
- FOLDER - A file folder is a directory in your file system. Individual files can be referenced relative to this folder by using the data source. The files in the folder are also listed in a data item named files as a table with the column File. The Folder property shall be the folder location. Remember to use a network path if distributed players need to access the files. The Filter property can be used to filter out which files to list. If it is empty, all files will be included. Otherwise the files matching the filter will be listed. Use semi-colon to separate patterns. Example: *.jpg;*.png
- Username - If the data source requires authentication, you can enter the username to use here. The username will be scrambled when stored.
- Password - If the data source requires authentication, you can enter the password to use here. The password will be scrambled when stored.
Data Items are added to Data Sources from the context menu of a data source. The data item define what data to retrieve from the data source. There can be many data items added to a single data source, which each can collect different data from the source. The data items works differently for each of the data source types and the Query property of the data item for the different data source types shall be defined as follows:
- ODBC, ACCESS and EXCEL - The Query property for each data item shall be a SQL select query in the form of a string. For Excel, the table name is [SheetName$] or any of the defined cell area names in the workbook. The first row of the sheet or cell area must be the column names for the table.
- ODATA - OData data sources will append the resource path from the data item to the service root URL. The complete URL is then used for fetching data from the service.
- REST - REST data sources will append the resource path from the data item to the service root URL. The complete URL is then used for fetching data from the service.
- TEXT - Text data sources have an internal data item named "data" that represents the data table from the text file. This data item is handled internally and is therefore not shown in the Project View.
- XML - The XPath property for each data item selects the node or nodes to extract data from. The result is a table where each node forms a row and each attribute is a field. The node text is stored in a special field named "$".
Example 16.5. Example of the XPath property for an XML data item
For an XML file looking like this:
<?xml version="1.0" encoding="UTF-8"?> <catalog> <book id="bk101"> <author>Right, Ronald</author> <title>The ways of my life</title> <genre>Bibliography</genre> <price>74.95</price> <publish_date>2014-10-01</publish_date> <description> An in-depth look at how I succeeded in life. </description> </book> <book id="bk102"> <author>Thrall, Kim</author> <title>Layers of Shields</title> <genre>Fantasy</genre> <price>5.95</price> <publish_date>2010-12-16</publish_date> <description> A weapon smith meets a powerful wizard and forms an alliance. </description> </book> <book id="bk103"> <author>Merit, Eva</author> <title>Elves Ascending</title> <genre>Fantasy</genre> <price>4.95</price> <publish_date>2015-03-16</publish_date> <description> On her tenth birthday, a young girl starts to experience something strange with her closet. </description> </book> </catalog>Extract data from the XML by typing one of the following examples into the XPath property:
- /book/author
- /book[genre=Fantasy]/title
- /book[@id=bk101]/title
- RSS - RSS feeds always contains two internal data items; "channel" and "items". These data items are handled internally and are therefore not shown in the Project View.
- TWITTER - Twitter data sources have an internal data item named "statuses" that represents the fetched Twitter statuses. This data item is handled internally and is therefore not shown in the Project View.
- SCRIPT - Script data sources have an internal data item named "data" that represents the data table produced by the script. This data item is handled internally and is therefore not shown in the Project View.
- GPX - GPX data sources have a few internal data items; "latitude", "longitude", "heading" and "direction". These data items are handled internally and are therefore not shown in the Project View.
- PACKAGE - A resource package use the file name to reference as the data item. There is also an internal data item named "files" which lists all embedded files. This data item is handled internally and is therefore not shown in the Project View.
- FOLDER - A file folder use the file name to reference the data item. There is also an internal data item named "files" which lists all files. This data item is handled internally and is therefore not shown in the Project View.
Example 16.6. Example of a direct file reference from a folder data source
A file named MyPicture.jpg can be referenced from a folder data source named MyFileFolderSource using the following data reference string:
@{MyFileFolderSource:MyPicture.jpg}