<data>

The <data> element provides the ability to customize the appearance of the output when rendering the data from grid widgets to a flat text file. (Available as of prod-9)

Description

It is possible to specify options for output rendering at both the <render> level and the <widget> level. When specifying configuration options at the <render> level, specify attributes directly to the <data> element. To specify configuration options at the <widget> level, the attributes must be prefixed with data_.

Syntax

<dynamic>
  <render>
    <data [ATTR1_NAME]="[VALUE]"
          [ATTR2_NAME]="[VALUE]"
           ... />    
  </render>
</dynamic>

Alternate syntax

<dynamic>
    <widget class_="grid" 
            data_[ATTR1_NAME]="[VALUE]"
            data_[ATTR2_NAME]="[VALUE]"
            ... />
</dynamic>

Attributes

The following attributes can be specified to the <data> child element of <render>.

Note: To specify these attributes on the <widget> level, they must be preceded by the prefix data_.
escape_char_
When qe_mode_="escape", this attribute specifies the escape character to use to escape occurrences of the field delimiter, the record delimiter, or the escape character itself. Accepts any single character or any predefined valid value.

For a list of predefined values, see Predefined delimiters.

If a field delimiter, record delimiter, or escape character occurs within a field, it will be preceded by the specified escape character in the resultant output.

The default is backslash.

export_bom_
Appends the byte order marker to CSV files to allow Excel to interpret UTF-8 characters. Accepts a 1 (append byte-order marker) or 0 (do not append byte-order marker).

The default value is 0.

ext_
Specifies the file extension of the downloaded file.

The default extension is .csv if the field delimiter is a comma; otherwise, it is .txt. The ext_ attribute can be used to override the default.

field_del_
Specifies the character that will be used to delimit columns. Accepts any single character or a predefined value.

For a list of predefined values, see Predefined delimiters.

The default is comma.

field_end_
Specifies whether or not to include the field_del_ character after the last data point in each row. Accepts a 1 or 0.

The default is 0.

filename_
Specifies the name of the file that downloads after the QuickApp is rendered as text.

The default is download.

The default extension is .csv if the field delimiter is a comma; otherwise, it is .txt. The ext_ attribute can be used to override the default.

headers_
Specifies what to use as column headers at the top of the text file.

Valid values are:

names
Use the column names from the grid widget for the column headers.
labels
Use the column labels from the grid widget for the column headers.
names,labels
Use the column names for the first row of column headers and the column labels as the second row of column headers.
labels,names
Use the column labels for the first row of column headers and the column names as the second row of column headers.
none
Do not use column headers.
Note: Setting headers_="" has the same effect as headers_="none".

The default is names.

qe_mode_
Specifies the quote/escape mode to use.

Valid values are:

quote
Use the character specified by the quote_char_ attribute to quote fields that contain the field delimiter, the record delimiter, or the quote character itself.
quoteall
Quote all fields regardless of their contents.
escape
Use the character passed to the escape_char_ attribute to escape occurrences of the field delimiter, the record delimiter, or the escape character itself.
none
Never quote or escape columns.
The default is quote.
quote_char_
When qe_mode_="quote", this attribute specifies the quote character to use to surround fields that contain the field delimiter, the record delimiter, or the quote character itself. Accepts any single character or a predefined value. Optionally, a pair of characters can be specified for the beginning and end quote characters.

For a list of predefined values, see Predefined delimiters.

If a field contains the field delimiter, the record delimiter, or the quote character itself:
  • If a single character or predefined value is specified to quote_char_, the field will be surrounded by that character or value in the resultant output.
  • If a pair of characters is specified to quote_char_, the first character is prepended to the field and the second character is appended to it in the resultant output.

In addition, any occurrences of the quote character within a field are doubled in the resultant output.

The default is dquote.

record_del_
Specifies the character that is used as a delimiter for rows in the text file output by the <render> operation. Accepts any single character or a predefined value.

For a list of predefined values, see Predefined delimiters.

The default is lf.

record_end_
Specifies whether or not to include the record_del_ character after the last record (i.e., at the end of the file). Accepts a 1 or 0.

The default is 1.

Example: Using a single-quote character for the quote character

The following example demonstrates how to specify using a single-quote character for the quote character.

<dynamic>
  <render>
    <data quote_char_="squote"/>
  </render>
  <widget class_="grid" base_="pub.doc.retail.product"/>
</dynamic>

When the QuickApp is rendered to a data target, any fields that contain the field delimiter or record delimiter will be surrounded by the quote character specified by quote_char_. Since the default field delimiter is a comma, any fields that contain a comma will be surrounded by single quotes.

For example, in the below output, because the fields HUMMUS, SPINACH & ARTICHOKE and SONY STORY OF DAVID, E - DVD each contain a comma, they are both surrounded by single quotes.

404558,MAIN ST. BSTRO BKD SCALLOPED POTATOES,32,SERVICE DELI,294,PREPARED FOODS - COLD,0,20 OZ,,0
31530,WORLD FOODS SQUASH SEEDS,36,PRODUCE,467,DRIED FRUIT NUTS & SEEDS,0,8.5 OZ,,0
145859,PRIVATE LABEL,33,GM,329,BABY CARE PRODUCTS,1,216 CT,,0
277114,'HUMMUS, SPINACH & ARTICHOKE',32,SERVICE DELI,233,DELI SPECIALTY,0,10 OZ,,0
209008,'SONY STORY OF DAVID, E - DVD',33,GM,293,ELECTRONIC ENTERTAINMENT,0,1 CT,,0
500336,PRIVATE LABEL,36,PRODUCE,341,FRUIT,1,20 OZ,,0
17174,PRIVATE LABEL,36,PRODUCE,368,SALAD,1,5 OZ,,0
170094,BONNY BAR BOTTLE STOPPER SET,33,GM,123,KITCHEN GADGETS,0,2 CT,,0

Example: Using different beginning and end quote characters

The following example demonstrates how to specify different characters for the beginning and end quote characters.

<dynamic>
  <render>
    <data quote_char_="[]"/>
  </render>
  <widget class_="grid" base_="pub.doc.retail.product"/>
</dynamic>

When the QuickApp is rendered to a data target, any fields that contain the field delimiter or record delimiter will be surrounded by the beginning and end quote characters specified by quote_char_. Since the default field delimiter is a comma, any fields that contain a comma will be enclosed between a [ character and ] character.

For example, in the below output, because the fields HUMMUS, SPINACH & ARTICHOKE and SONY STORY OF DAVID, E - DVD each contain a comma, they are each surrounded by [ and ].

404558,MAIN ST. BSTRO BKD SCALLOPED POTATOES,32,SERVICE DELI,294,PREPARED FOODS - COLD,0,20 OZ,,0
31530,WORLD FOODS SQUASH SEEDS,36,PRODUCE,467,DRIED FRUIT NUTS & SEEDS,0,8.5 OZ,,0
145859,PRIVATE LABEL,33,GM,329,BABY CARE PRODUCTS,1,216 CT,,0
277114,[HUMMUS, SPINACH & ARTICHOKE],32,SERVICE DELI,233,DELI SPECIALTY,0,10 OZ,,0
209008,[SONY STORY OF DAVID, E - DVD],33,GM,293,ELECTRONIC ENTERTAINMENT,0,1 CT,,0
500336,PRIVATE LABEL,36,PRODUCE,341,FRUIT,1,20 OZ,,0
17174,PRIVATE LABEL,36,PRODUCE,368,SALAD,1,5 OZ,,0
170094,BONNY BAR BOTTLE STOPPER SET,33,GM,123,KITCHEN GADGETS,0,2 CT,,0

Example: Escaping characters in the resultant output

The following example demonstrates how to escape text in fields that contain the field delimiter, the record delimiter, or the escape character itself.

<dynamic>
  <render>
    <data qe_mode_="escape"/>
  </render>
  <widget class_="grid" base_="pub.doc.retail.product"/>
</dynamic>

When the QuickApp is rendered to a data target, any occurrences of the field delimiter, record delimiter, or escape character within a field will be escaped with the escape character. Since escape_char_ is not specified, the default escape character, which is a backslash, is used. Since the default field delimiter is a comma, any occurrences of a comma will be escaped with a backslash.

For example, in the below output, because the fields HUMMUS, SPINACH & ARTICHOKE and SONY STORY OF DAVID, E - DVD each contain a comma, the comma in each field is escaped with a backslash.

404558,MAIN ST. BSTRO BKD SCALLOPED POTATOES,32,SERVICE DELI,294,PREPARED FOODS - COLD,0,20 OZ,,0
31530,WORLD FOODS SQUASH SEEDS,36,PRODUCE,467,DRIED FRUIT NUTS & SEEDS,0,8.5 OZ,,0
145859,PRIVATE LABEL,33,GM,329,BABY CARE PRODUCTS,1,216 CT,,0
277114,HUMMUS\, SPINACH & ARTICHOKE,32,SERVICE DELI,233,DELI SPECIALTY,0,10 OZ,,0
209008,SONY STORY OF DAVID\, E - DVD,33,GM,293,ELECTRONIC ENTERTAINMENT,0,1 CT,,0
500336,PRIVATE LABEL,36,PRODUCE,341,FRUIT,1,20 OZ,,0
17174,PRIVATE LABEL,36,PRODUCE,368,SALAD,1,5 OZ,,0
170094,BONNY BAR BOTTLE STOPPER SET,33,GM,123,KITCHEN GADGETS,0,2 CT,,0

Example: Specifying render options on the <widget> level

The follow example demonstrates how to specify render options on the <widget> level. When the render button is clicked, the two grid widgets are rendered to separate text files using the render options specified to each widget.

Note: When specified on the <widget> level, the render options for a data target must be prefixed with data_ (e.g., data_headers_, not headers_).
<dynamic>
  <widget class_="grid" base_="pub.demo.retail.item" 
   data_filename_="item" data_ext_="txt"
   data_headers_="labels,names"/>
  <widget class_="grid" base_="pub.demo.retail.store" 
   data_filename_="store"/>
  <widget class_="button" type_="render" target_="data"/>
</dynamic>

The first grid widget is rendered as a text file with the name item.txt, as specified by the data_filename_ and data_ext_ attributes. The first line of headers in that file will consist of the column labels, and the second will consist of the column names, as specified by the data_headers_ attribute.

The resultant output file item.txt looks like:

Transaction ID,Account,Store,Date,Item SKU,Units,Sales,Cost
transid,account,store,date,sku,units,sales,cost
531,957,1,05/15/12,366,-1,-5,-1.84
532,478,1,05/15/12,98A,1,0.5,0.25
532,478,1,05/15/12,3B7,1,1.1,0.56
534,738,1,05/16/12,A96,2,6,2.9
534,738,1,05/16/12,65B,1,2.25,1.35
535,709,2,05/15/12,CB7,1,1.65,1.1
535,709,2,05/15/12,96A,1,1.1,1

The second grid widget is rendered as a text file with the name store.csv, as specified by the data_filename_ attribute. The default extension .csv is used since data_ext_ is not specified, and a comma is the default field delimiter. The header line in that file will consist of the column names, which is the default since data_headers_ is not specified.

The resultant output file store.csv looks like:

store_id,store,addr,city,state,zip,sdiv,sqft,type
1,2136,2016 N WAYNE ST.,ANGOLA,IN,46703,5,5346,SHOPPING CENTER
2,1894,N96 W18515 COUNTY LINE ROAD,MENOMONEE FALLS,WI,53051,6,7128,STAND ALONE
3,1889,231 BLUEBELL DR N.W.,NEW PHILADELPHIA,OH,44663,5,7789,STAND ALONE