<loader>

A loader is used to load values into the interface from example files. The example files have the same format as the tool.xml file that they are being loaded into. In fact, they can be generated by running the tool and saving the output run.xml file. In you look in the example files, you'll see that each one also has an <about> section with a label and a description. These show up in the loader control.

  <loader>
    <about>
      <label>Example</label>
      <description>Use this to load examples.</description>
    </about>
    <example>*.xml</example>
  </loader>

The example files sit in a directory named examples in the same directory as the tool.xml file. You can include any number of <example> tags. Each one contains a file name or a glob-style (shell-style) matching pattern for files that should be included in the loader. If there are no <example> tags, the default pattern *.xml is assumed.

You can also store your example files in directories under the examples directory as shown below:

  examples/
    |--> l1/
           |--> first.xml
           |--> second.xml
    |--> l2/
           |--> third.xml
           |--> fourth.xml
    |--> l3/
           |--> first.xml
           |--> second.xml

In this case there are no xml files directly under the examples directory, but the xml files are located in directories named examples/l1, examples/l2, examples/l3. Assuming there are three loaders, one for each directory, you can access the xml files under each directory as follows:

  <loader>
    <about>
      <label>Example 1</label>
      <description>Use this to load examples from directory l1.</description>
    </about>
    <example>l1/*.xml</example>
    <default>first.xml</default>
  </loader>

  <loader>
    <about>
      <label>Example 2</label>
      <description>Use this to load examples from directory l2.</description>
    </about>
    <example>l2/*.xml</example>
    <default>third.xml</default>
  </loader>

  <loader>
    <about>
      <label>Example 3</label>
      <description>Use this to load examples from directory l3.</description>
    </about>
    <example>l3/*.xml</example>
    <default>second.xml</default>
  </loader>

Notice that for the <default> tag, you put the name of the file you want to use as the default option, not the path of the file. The loader named Example 3 will choose the file examples/l3/second.xml because we use the glob pattern l3/*.xml in the <example> tag.

New file

You can designate one of the example files as a New file. This gives the user the option to start from scratch, reseting all values to default values, and perhaps loading a text area with a message such as "Enter your Spice3F4 commands here..." Use the <new> directive to designate one of the examples as the New option:

<input>
  <loader>
    <about>
      <label>Examples</label>
      <description>Choose from one of these example input files, or upload your own file from your desktop.</description>
    </about>
    <new>new.xml</new>
    <example>EE255/*.xml</example>
    <default>new.xml</default>
  </loader>
  ...

Upload / Download

Quite often, the user will want to upload their own data into one of the fields within a Rappture interface. For example, suppose a tool has a string element named input.string(indeck) representing the input file for a simulator such as Spice, Prophet, or Padre. You can allow the user to upload files from their desktop into that field by adding an <upload> section to the tool.xml file as follows:

  <loader>
    <about>
      <label>Example</label>
      <description>Use this to load examples.</description>
    </about>
    <upload>
      <to>input.string(indeck)</to>
      <to>input.string(datafile)</to>
    </upload>
    <download>
      <from>input.string(indeck)</from>
      <from>input.string(datafile)</from>
    </download>
    <new>new.xml</new>
    <example>*.xml</example>
    <default>new.xml</default>
  </loader>

The <to> field says which Rappture element will receive the upload. Note that there can be multiple <to> declarations, and Rappture will prompt for all files at once. In this example, the user is prompted to upload both a Spice3F4 input deck (stored in the Rappture element input.string(indeck)) and a data file (stored in input.string(datafile)).

If you include a <download> section, then the user will also have the option of downloading the current contents of one or more elements--usually the same as the <upload> section. In this case, the user can also download from both input.string(indeck) and input.string(datafile), so the user might select an example file, download it to their desktop, make some changes in their favorite editor, and then upload it again to the tool.

When the <upload> and <download> directives are included in a <loader>, the control looks like this:

Example Files

The loader is fed by data files that have the same format as a Rappture tool.xml file, but with <current> values set to the values that you want to load. For example, the Change both example file looks like this:

<?xml version="1.0"?>
<run>
<about>
  <label>Change both</label>
  <description>This example changes both inputs, #1 to "first" and #2 to "second"</description>
</about>

<tool>
  <title>loader</title>
</tool>
<input>
  <loader>
    <about>
      <label>Example</label>
      <description>Use this to load examples.</description>
    </about>
    <example>*.xml</example>
  </loader>

  <string id="one">
    <about>
      <label>Input #1</label>
    </about>
    <current>first</current>
  </string>
  <string id="two">
    <about>
      <label>Input #2</label>
    </about>
    <current>second</current>
  </string>
</input>
</run>

Note that it has <current> values for each of the <string> inputs.

The Change first example is represented by an XML file that looks like this:

<?xml version="1.0"?>
<run>
<about>
  <label>Change first</label>
  <description>This example changes only the first input to the value "hello"</description>
</about>

<tool>
  <title>loader</title>
</tool>
<input>
  <loader>
    <about>
      <label>Example</label>
      <description>Use this to load examples.</description>
    </about>
    <example>*.xml</example>
  </loader>

  <string id="one">
    <about>
      <label>Input #1</label>
    </about>
    <current>hello</current>
  </string>
</input>
</run>

This is almost the same as the first, but it has only string input. The second one is missing, and therefore the second string is not changed when this example is loaded.

You can see working code in the zoo of example's in the loader example or on the hub in the directory /apps/rappture/examples/zoo/loader.