== How to pass parameters to Rappture tools ==

This document describes how Rappture will handle tool parameters that might be passed in from the HUBzero middleware.  Rappture detects this upon startup, when the {{{$TOOL_PARAMETERS}}} environment variable is set.  Right now, Rappture interprets only "file" parameters.  The name associated with a file parameter determines how Rappture will treat the file:

'''{{{file(load):/path/to/run.xml}}}'''
> Load the given file into the runtime environment.  There can be one or more, to load one or more results.  This is equivalent to the command line invocation {{{rappture -load /path/to/run.xml}}}.

[[BR]]
'''{{{file(execute):/path/to/driver.xml}}}'''
> Execute the given driver file without the interactive GUI.  Store status information (progress during the run) in the file {{{rappture.status}}}.  This is equivalent to the command line invocation {{{rappture -execute /path/to/driver.xml}}}.

[[BR]]
'''{{{file(input):/path/to/driver.xml}}}'''
> Load the given driver file into the runtime environment as the initial set of input values.  This is similar to {{{file(load)}}}, but ignores anything in the output section and instead looks only for input values.

[[BR]]
'''{{{file(into:input.string(indeck)):/path/to/textfile}}}'''
> Load the contents of the given file into the Rappture element identified by the text following {{{into:}}}.  In this example, the text within /path/to/textfile is loaded into a Rappture string control at {{{input.string(indeck)}}}.


[[BR]]
=== ~~Bigger step: Extend the parameter passing syntax to include "''string''" parameters.~~ ===

~~This will let you inline the values in the URL. Example:~~
~~{{{
string(input.number(temperature).default):300K
string(input.choice(model).default):boltzman
}}}~~
~~The real advantage of the inline ''string'' is you can then override any tag in Rappture.~~
~~{{{
number(input.number(temperature).min):3K
number(input.number(temperature).max):10000K
}}}~~

We may yet reach the point of adding things like {{{number}}} and {{{string}}} as parameters, but this would push lots of Rappture-specific info into the middleware system, which validates all of these parameters as they pass in through the URL.  Instead, we'll stick with using driver files for now as a means of passing input values.  Note that a driver doesn't have to be a complete set of inputs.  You can specify a driver with a single parameter and current value, as you might for the loader.