DataLink inputParam PARAM/@value

[Carlos Rodrigo]

Hi again

In practice, trying to define how to build a meaningful interface (let's say, a form) just using a
"metadata" response has several subleties when we really think of real cases.

The first one is this one pointed by Mark. If a non-empty VALUE is provided for a param, how it must
be understood? Does it make sense to provide a non-empty VALUE and also a VALUES element? if it
does, which is the meaning?

But you can think of some others. For instance, does the service allow for a range or a list of
values for a given parameter? or even, for a text field, can I use wildcards for that field?

You can think of simpler alternatives for all that. But, when we defined S3 (that tried to deal with
these problems) we thought of a way to specify these options (you can take a look to a summary at
http://svo2.cab.inta-csic.es/theory/docs2/index.php?pname=S3/Interface just for some ideas)

The main idea was to write param names not just as "INPUT:param" but "INPUT:param[:options]" where
the :options part was optional and could specify some restricted list of possible options for that
param to understand how to handle it.

for instance,

<param name="INPUT:COLLECTION:fixed" value="ALL">
would work as "the value for "COLLECTION is "ALL", and you must pass it like that to the service,
not ask the user for a value.

but, instead:
<param name="INPUT:COLLECTION" value="ALL">
would mean that the default value for COLLECTION is "ALL", but you can ask the user to input a
different value. If there is a VALUES element you can use it to build a better form.

This was a simple way to allow for machine client to distinguish when a param should be filled or
not. And it allowed for other options.

We allowed for {range,list,fixed} as possible properties after the ":". And "wildcards" could we
another one.

If you don't like to introduce such syntax/flexibility (I would bet that Markus would hate it ;) I
would say that, for the current question:

if a non empty VALUE is provided:
- if there is a VALUES child element, this field should be filled in a form.
- if there is not a VALUES child element, this param is fixed and it must be passed by the form with
that value fixed (let's say, as a hidden field)

what's more, if VALUES provide real information:
- if VALUES->MIN/MAX you just, for instance, include some text giving information of the MIN/MAX
values allowed.
- if VALUES type="actual" and there are non-empty OPTIONs as childs, you make some select field with
all the possible options
- if VALUES type="actual" and there are NOT non-empty OPTIONs as childs, it must be understood that
the param should be filled (because there is a VALUES child element) but its content is free
(because you don't have options to show)

That's my understanding of all this

Carlos

On 17/11/17 08:58, Markus Demleitner wrote:
> Hi Mark,
> 
> On Wed, Nov 15, 2017 at 11:15:26PM +0000, Mark Taylor wrote:
>> On Wed, 15 Nov 2017, Markus Demleitner wrote:
>>> Essentially, PARAMs that can or must be filled (there's no way for a
>>> machine client to distinguish between the two cases yet; I am hoping
>>> for a VO-DML-based annotation there) have value=""; the rationale is
>>> that PARAM/@value is, in effect, TABLEDATA-encoded[1] and in TABLEDATA,
>>> an empty string is always NULL since VOTable 1.3.
>>>
>>> If, on the other hand, @value is non-empty, then this value should be
>>> included in the query literally (or after parsing and
>>> TABLEDATA-serialisation, which should end up with an equivalent
>>> result).
>>
>> Thanks.  This response makes perfect sense.  However, unless I'm
>> missing something (possible - is there a bit of text you can point at?)
>> it's not spelled out or even really suggested in the DataLink text.
>>
>> I don't think I'm the only one to fail to divine this intent;
>> Carlos Rodrigo responded (in a message which may show up on-list
>> at some point) that he thought that non-blank @value represented
>> a default.
>>
>> Also, some of the examples look a bit weird to me in the light of your
>> interpretation.  For instance, section 4.3 has this:
>>
>>    <PARAM name="COLLECTION" datatype="char" arraysize="*" value="ALL">
>>      <VALUES>
>>        <OPTION value="ALL" />
>>        <OPTION value="FOO" />
>>        <OPTION value="BAR" />
>>      </VALUES>
>>    </PARAM>
>>
>> I don't understand the point of specifying all the options if the
>> client is required to pass COLLECTION=ALL when invoking the service.
>> Given your explanation, I would not in general expect a PARAM
>> with a non-blank @value to have a VALUES child.
> 
> Right -- I eat my words, and this certainly goes to show that we need
> to be more explicit.  As to wording (place TBD) I would propose:
> 
>   [something on @value="" meaning "pass something in"]  If a PARAM
>   within the inputParams GROUP has a non-empty value attribute, a
>   value must be passed to the corresponding service parameter.  While
>   a client may optionally allow user interaction to change that
>   parameter value, its default must be the value of the PARAM's
>   value attribute.
> 
> That sounds almost like a parody.  Hm.  Improvements welcome, but
> apart from surface form, I think that's sensible behaviour, and at
> least the one I had in mind way back when.
> 
> One thing I'd consider given my implementation experience is whether
> to disallow changing the parameter value absent a VALUES child of the
> PARAM.  I think without VALUES it's hard to present an actually
> usable UI in the first place, and, for instance, in the
> datalink-for-one-dataset example, letting the user change the pubDID
> is an invitation to produce breakage while not enabling any sort of
> useful behaviour I could imagine.
> 
> But on the other hand, I expect we'll have a better design overall if
> we keep all the information about what parameters are changable,
> required, mutually exclusive, or whatever, to future VO-DML-based
> annotation.
> 
> Hm.
> 
>          -- Markus
>