Difference between revisions of "Optional Embed Arguments"

Revision as of 09:44, 9 September 2016

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.

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

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

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: 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.

Argument: FR (Float)

Meaning: Framing Options

Purpose: Allows for condensing an embed's framing when screen space is limited.

Supported By: Tables, LatestValues, Charts

Details & Notes:

A value of 1.0 means that the embed should display as "normal" with all aspects of the embed visible (same as not providing this argument). A value of 2.0 means that the footer section (footnotes, citation, attribution, watermark, tools) is hidden. A value of 3.0 implies the same as a value of 2.0 but with a handle to display/hide the footer (overlaid on top of or instead of the embed).

Argument: PW (Float)

Meaning: Parent Viewport Width

Purpose: Tells dataZoa the dimensions of the viewport in which the embed has been placed. If the embed in question has the Dynamic Size Settings feature turned on then dataZoa can use this information to apply appropriate preset size restrictions (NC and FR type modifications set when building the embed).

Supported By: Tables, LatestValues, Charts

Details & Notes:

Between the PW and PH arguments, PW is more pivotal in making size based decisions.

Argument: PH (Float)

Meaning: Parent Viewport Height

Purpose: Tells dataZoa the dimensions of the viewport in which the embed has been placed. If the embed in question has the Dynamic Size Settings feature turned on then dataZoa can use this information to apply appropriate preset size restrictions (NC and FR type modifications set when building the embed).

Supported By: Tables, LatestValues, Charts

Details & Notes:

Between the PW and PH arguments, PW is more pivotal in making size based decisions.

Argument: WD (Float)

Meaning: Width

Purpose: Tells dataZoa what the desired or target width of the embed is.

Supported By: Tables, LatestValues, Charts

Details & Notes:

Reserved, not yet implemented

Argument: WN (Float)

Meaning: Minimum Width

Purpose: Tells dataZoa what the minimum width of the embed is.

Supported By: Tables, LatestValues, Charts

Details & Notes:

Reserved, not yet implemented

Argument: WX (Float)

Meaning: Maximum Width

Purpose: Tells dataZoa what the maximum width of the embed is.

Supported By: Tables, LatestValues, Charts

Details & Notes:

Reserved, not yet implemented

Argument: HE (Float)

Meaning: Height

Purpose: Tells dataZoa what the desired or target height of the embed is.

Supported By: Tables, LatestValues, Charts

Details & Notes:

Reserved, not yet implemented

Argument: HN (Float)

Meaning: Minimum Height

Purpose: Tells dataZoa what the minimum height of the embed is.

Supported By: Tables, LatestValues, Charts

Details & Notes:

Reserved, not yet implemented

Argument: HX (Float)

Meaning: Maximum Height

Purpose: Tells dataZoa what the maximum height of the embed is.

Supported By: Tables, LatestValues, Charts

Details & Notes:

Reserved, not yet implemented