SQL Scripts Manager 2

Types of control

SQL Scripts Manager enables you to define a graphical user interface for a script. You specify the interface design in the XML script file (extension .rgtool), using <control> elements.

This page describes how to use <control> elements in detail, covering each possible control type, sub-controls, and other attributes of <control> elements.

For more information about the structure of a complete XML script file, including how to place <control> elements in blocks, see The SQL Scripts Manager XML schema.

XML is case sensitive; you must use the exact text shown when creating your own XML script files.

 

<control> attributes

Every instance of a <control> element can have the following attributes:

  • type [required]

    Describes the type of the control. See the following sections for more information about each control type. Possible values are:

    Control type

    Description

    Control type

    Description

    check

    Check box

    list

    Selectable list box control (single or multi selection)

    combo

    Combo box (fixed or editable)

    openfile

    File browser dialog box

    createdatabase

    Combo boxes for selecting an instance and specifying a new database

    password

    Text box for password entry

    createtable

    Combo boxes for selecting an instance and database, and specifying a new table

    radio

    Group of option buttons

    database

    Combo boxes for selecting an instance and database

    savefile

    Save file dialog box

    folderbrowser

    Text box and browse button, for folder selection

    server

    Combo box for selecting an instance, and text boxes for connection credentials

    header

    A UI heading label

    table

    Combo boxes for selecting an instance, database, and table

    integer

    Text box that accepts only integers

    text

    Text box

  • id [optional]

    The control id is used to read the value of the control in your script code.

    See the " class="conf-macro output-inline" data-hasbody="true" data-macro-name="sp-plaintextbody-link"><script> element for information about how to use control id's in script code.

    If you don't provide a value for the id attribute, SQL Scripts Manager will generate an identifier automatically. These identifiers can then be used to refer to the control in preset files.

  • label [optional]

    A string placed to the left side of the control on the user interface.

    For the controls of type check (check box), the label string is placed to the right of the check box.

Default sub-controls

The following sub-controls (elements) can be specified as children of any type of control:

  • <font> [optional]

    This element changes the font used to render the parent control. This setting will not affect any other controls.

    Attributes:

    • name: font name (default is 'Tahoma')
    • size: the point size of the font (default is 8.25)
    • style: the font style (bold, italic, regular, strikethrough, underline) (default is 'regular')
  • <help>

    Adds an interactive help button (  ) to the control. When a user clicks a help button, a help window is displayed.

    Use help buttons to help explain how a particular control should be used.

    Sub-elements:

    • <title>: the title of the help window
    • <text>: the help text displayed. The help text can include simple HTML tags (for example, <i>, <b>, <p>, <ul>, <li>, <h1>, h2>, <pre>) for formatting the text in the help window.

      In most cases, you will want to identify your help text as CDATA (unparsed character data), by placing it between <![CDATA[ and ]]> tags.

      Example:

 

<control type="check" id="rememberpassword" label="Remember password">
      <help>
        <title>Remember password</title>
        <text><![CDATA[
          <p>If you select this check box, your <i>password</i> is
          persisted in the registry in <b>encrypted form</b>. On
          subsequent runs of the script, the password is completed
          automatically. See <a href="http://localhost/index.htm>
          this document</a> for more information.</p>
          ]]>
        </text>
      </help>
    </control>


check

Creates a check box.

The label for a check box is positioned to the right of the control.

Example

<control type="check" id="rememberpassword" label="Remember password" />

combo

Creates a combo box; you can choose whether the combo box is editable, or fixed.

Sub-elements

  • width: the width of the control in pixels (default is 200)
  • editable: if 'true', the combo box includes a text box that the user can type into (default is 'false')
  • list / item: each item listed in the combo box

Example

<control type="combo" id="Databases">
  <width>220</width>
  <editable>true</editable>
  <list>
    <item>SYSTEM_DATABASES</item>
    <item>USER_DATABASES</item>
    <item>ALL_DATABASES</item>
  </list>
</control>

 

createdatabase

Creates a SQL Server instance-selection control that includes a combo box for selecting a database on the specified SQL Server instance.

Use this control when you need to specify a name for a database that does not have to exist on the instance (for example, when the database will be created when the script is run).

Example

<control type="createdatabase" id="connection" />

createtable

Creates a SQL Server instance-selection control that includes combo boxes for selecting a database and a table.

Use this control when you need to specify a name for a table that may not exist in the specified database (for example, if the table will be created when the script runs).

<control type="createtable" id="connection" />

database

Creates a SQL Server instance-selection control that includes a combo box for selecting an existing database from the specified SQL Server instance.

This control checks that the selected database exists on the server, before running the script.

Example

<control type="database" id="connection" />

folderbrowser

Creates a control that enables the user to select a folder.

The control comprises a text box and a browse button: the browse button launches a folder browser dialog box, and the text box enables the user to type a folder path rather than using the browser dialog box.

Sub-elements

  • title: the title of the folder browser dialog box

Example

<control type="folderbrowser" id="folder">
  <title>Select a destination folder</title>
</control>

header

Creates a label on the user interface.

Use this control to create headings between other controls on the user interface. This may be useful if you have created a large number of controls, and need to organize them more clearly.

Use the font sub-control to change the font used to render the heading.

Example

<control type="header" label="Database location">
  <font name="Arial" size="12" style="bold" />
</control>

integer

Creates a text box control that accepts only integer numbers.

Sub-elements

  • min: the lower bound for accepted values
  • max: the upper bound for accepted values

Example

<control type="integer" id="percentage" label="Fill factor (%):">
  <min>0</min>
  <max>100</max>
</control>

list

Creates a selectable list box control. You can choose between single and multi selection.

Sub-elements

  • mode: specifies the selection behavior for the list box. Possible values are:
    • none: no items can be selected
    • one: only one item can be selected
    • multisimple: multiple items can be selected
    • multiextended: multiple items can be selected, optionally while using the SHIFT, CTRL, and arrow keys
  • height: the height of the list box control in pixels (default is 20)
  • width: the width of the list box control in pixels (default is 200)
  • list / item: a list of items that are shown in the combo box

Example

<control type="list" id="options">
  <height>100</height>
  <width>220</width>
  <mode>one</mode>
  <list>
    <item>SYSTEM_DATABASES</item>
    <item>USER_DATABASES</item>
    <item>ALL_DATABASES</item>
  </list>
</control>

openfile

Launches a file browser dialog box.

Sub-elements

  • title: the title of file browser dialog box (default is 'Title')
  • filter: the filter pattern for the file browser dialog box (default is 'All Files (*.*)|*.*')

    Write filter patterns using the format: <text1>|<file pattern1>|<text2>|<file pattern2>[...]

Example

<control type="openfile" id="file">
  <title>Source file...</title>
  <filter>CSV Files (*.csv)|*.csv|All Files (*.*)|*.*</filter>
</control>

password

Creates a password entry text box.

Example

<control type="password" id="password" label="Password:" />

radio

Creates a group of option buttons (also known as radio buttons).

Sub-elements

  • list / item: a list of option button items

Example

<control type="radio" id="Options">
  <list>
    <item>Physical only</item>
    <item>Physical and data purity</item>
    <item>Physical, data purity, and extended checks</item>
  </list>
</control>

savefile

Launches a Save File dialog box.

Sub-elements

  • title: the title of the dialog box (default is 'Title')
  • filter: the filter pattern for the dialog box (default is 'All Files (*.*)|*.*')

    Write filter patterns using the format: <text1>|<file pattern1>|<text2>|<file pattern2>[...]

Example

<control type="savefile" id="file">
  <filter>CSV Files (*.csv)|*.csv|All Files (*.*)|*.*</filter>
  <title>Destination file...</title>
</control>

server

Creates a composite control for selecting a SQL Server instance and providing the connection credentials.

Example

<control type="server" id="connection" />

table

Creates a SQL Server instance-selection control that includes combo boxes for selecting a database and a table.

Use this control to select an existing database table.

Example

<control type="table" id="connection" />

text

Creates a text box.

Sub-elements

  • height: the height of the text box, in lines. This setting is only used if multiline is set to 'true' (default is 1)
  • width: the width of the text box in pixels
  • maxlength: the maximum text length in characters (default is 20)
  • multiline: specifies whether the text box will accept multiple lines of text ('true' or 'false') (default is false)
  • allowEmpty: specifies whether an empty text box is considered valid ('true' or 'false')

Example

<control type="text" id="note" label="Note:">
  <height>10</height>
  <width>220</width>
  <maxlength>2048</maxlength>
  <multiline>true</multiline>
  <allowEmpty>true</allowEmpty>
</control>

Didn't find what you were looking for?