`<declare>`

<declare> can be included within a block or block definition to specify metadata about the block.

Description

<declare> is optional within a block. <declare> can contain multiple sections. It is ignored during block expansion, but may be used to specify metadata about the block, which can be used for various purposes. For example, metadata within <declare> can be used by TRS to build a timeline panel for the block. <declare> may contain one or more optional <param name="name" label="label" type="type"> elements and/or a <trs_gui> element that contains <layout>, <widget>, and/or <do> ops.

To create your own user panel within TRS, use <declare> to set up the metadata for the panel, including label, description, and the icon to be used for the panel. See the syntax below.

Syntax

<declare>
      <trs
         role="op"     
         label="[LABEL_NAME]"
         header="[HEADER_NAME]"
         desc="[SHORT_DESCRIPTION]"
         icon="[ICON_NAME]">
      </trs>
</declare>

Example

The following example shows how the <declare> tag specifies the metadata for a user-defined panel called "Flip" in TRS.

<declare>
      <trs
        role="op"
        label="Flip"
        header="{if(@trs_open;'';'Edit')} Transpose Table"
        desc="Exchange the horizontal and vertical axes of a table."
        icon="fa-ruler-combined"
      /trs>
      <trs_gui>
        <do>
          <set trs_ready="{(@n<>'')&(@l<>'')}"/>
        </do>

        <layout arrange_="v">
          <!-- our user interface --> 
          <widget class_="text" text_="Choose columns in the current table which will provide names and labels for the transposed table:"/>
          <layout arrange_="v" web_htmlclass_="transpose-cols">
            <widget class_="dropdown" label_="Names" deflabel_="Choose a Column..." value_="@n">
              <issue xml_="{@trs_query}"/>
              <columns/>
              <sel value="type='a'"/>
              <colord cols="name"/>
            </widget>
            <widget class_="dropdown" label_="Labels" deflabel_="Choose a column..." value_="@l">
              <issue xml_="{@trs_query}"/>
              <columns/>
              <sel value="type='a'"/>
              <colord cols="name"/>
            </widget>
          </layout>

          <widget class_="text">
            <code language_="css">
              .transpose-cols {
                background: #ddd;
                border: 1px solid #ccc;
                border-radius: 4px;
                padding: 10px;
                margin-top: 10px;
              }
              .transpose-cols .hc-dropdown .hm-widget-element {
                padding-left: 60px!important;
              }
              .transpose-cols .hm-label-left {
                top: 5px;
              }
            </code>
          </widget>
        </layout>

      </trs_gui>
    </declare>

In this example, the <declare> statement provides metadata about the <block>, which can control how the <block> is edited. Within <declare> we can provide a <trs> tag, which provides basic information about the panel, such as the name, description, and its icon in the panel. In addition, the <trs_gui> tag contains a QuickApp that will be used as a user interface for editing the <block>'s arguments. The <trs_gui> tag behaves in this context like a <dynamic>, with several dynamic variables that are pre-defined by the Trillion-Row Spreadsheet with information about the timeline. The variable trs_query contains a query value representing the preceding timeline steps. The above example uses trs_query to populate drop-down lists with a selection of string columns in the current table.

The added <layout> tags are used to customize the parameter fields in the operation panel.