Difference between revisions of "Optional Embed Arguments"

Latest revision as of 07:37, 10 September 2018

When you build and save a dataZoa embed display like a chart or table, we generate a unique URL for it so you can use it in documents, web pages, etc. Generally speaking, you can simply copy and paste the URL, but if you are interested in extending or fine tuning the display, these are arguments you can add to the URL.

All arguments are optional and values should be URL encoded if provided.
Because these are overrides, default behaviors are simply what is seen in the embed editor when the display is created.
Each unique combination of arguments will become a server cached variation of the underlying embed.

1 Argument: GLName (String)
2 Argument: AltTitle (String)
3 Argument: AltExtSrc (String)
4 Argument: XSectDate (Date)
5 Argument: RF (String)
6 Argument: NC (Integer)
7 Argument: FR (Float)
8 Argument: PW (Float)
9 Argument: PH (Float)
10 Argument: WD (Float)
11 Argument: WN (Float)
12 Argument: WX (Float)
13 Argument: HE (Float)
14 Argument: HN (Float)
15 Argument: HX (Float)

Argument: GLName (String)

Meaning: GroupList Name indicating a set of series to show in the display

Purpose: This lets a display be re-used as a template by replacing its contents dynamically. You could, for example, build a table showing several series for a particular county, and re-use the table by providing a GroupList with corresponding data for a different county.

Supported By: Tables, LatestValues, Charts, Widgets

Details & Notes:

GroupList names provided in this way will be matched against those in the account owning the embed in question. If a provided GroupList name doesn't exist or is invalid (typo) then the default data (that which the embed was built with) is displayed. In the case of LatestValues displays, multiple GroupLists can be passed (delimited by "##SPLIT##") to generate a cross-sectional display.

Argument: AltTitle (String)

Meaning: Alternate Title

Purpose: A string to be used as an alternate title, replacing the one the embed was built with.

Supported By: Tables, LatestValues, Charts, Widgets

Details & Notes:

The text may optionally include HTML/CSS markup to help stylize the new title.

Argument: AltExtSrc (String)

Meaning: Alternate External Sources

Purpose: Allows LatestValues displays to be used as templates with varying columns (rather than rows) of data. Specifies a positional list of GroupList names used to replace data for any columns marked as External Data.

Supported By: LatestValues

Details & Notes:

GroupList names provided in this way will be matched against those in the account owning the embed in question. Multiple GroupList names should be delimited by the string "##SPLIT##". GroupList names are positional relative to only columns marked as External Data (e.g. 2nd GroupList name matches with 2nd External Data column even if this is 5th column in LatestValue). An empty string or the value "SKIP" will result in no overrides for that position (the associated External Data column will use the data the embed was built with). Any other non-valid or non-existent GroupList name will be used, resulting in no data shown for the associated column. Extra GroupLists names (beyond the last External Data column, position wise) will be ignored (but will still factor into a cached variant of the embed). Future expansion may allow for providing names of alternate external sources which aren't specifically GroupList names.

Argument: XSectDate (Date)

Meaning: Cross-sectional Date

Purpose: To show a slice in time other than the latest in simple LatestValues displays. To enhance a LatestValues display to become a cross-sectional.

Supported By: LatestValues

Details & Notes:

Cross-sectional displays are special case of LatestValues in which an XSectDate and multiple GLNames are provided, resulting in a matrix view of data (each column represents series from one of the GroupLists). A valid XSectDate is required in order to form a cross-sectional display. If a valid data is provided for a cross-sectional display but there is no data then cells will be displayed as empty. When used with a non cross-sectional display it allows all rows for any Latest Value column to display data for the given date (instead of row specific dates). This will affect External Data columns which display data for the same date as the Latest Value column. This will also affect Prior Value columns which display data for a date relative to that in the Latest Value column. If the keyword "LATEST" is provided instead of a date then dataZoa will automatically determine and set the most recent date in use by any row or cell. Generally using the keyword "LATEST" with non cross-sectional displays is not recommended; the only benefit is to force all rows to the same date but at the cost of some speed.

Argument: RF (String)

Meaning: Row Filter

Purpose: Allows for filtering (hiding) rows in which all the values match 1 or more of the provided filters.

Supported By: Tables, LatestValues

Details & Notes:

Value should be a pipe (|) delimited list of regular expression matches to test for. Additionally, there are two special keywords which can be used: NNV (non-numeric value) and ND (no data).

Argument: NC (Integer)

Meaning: Number of Columns

Purpose: Allows for specific content decisions to be implemented for responsive designs. For example, if a LatestValues display normally shows six columns, but should only show two when space is limited, this argument will supply that information.

Supported By: Tables, LatestValues

Details & Notes:

Non-integer values as well as integer values outside the range of 1-50 for Tables or 1-9 for LatestValues are ignored.