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

[[rpimage(zoo_loader.gif)]]
{{{
  <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:[[BR]]
[[rpimage(zoo_loader2.gif)]]

== 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 [browser:trunk/examples/zoo zoo of examples] in the [browser:trunk/examples/zoo/loader loader example] or on the hub in the directory /apps/rappture/examples/zoo/loader.