Re: Parameters: let's keep it simple

Alessandro Vernet wrote:
> We can do the same when we define the XSLT component. For instance, we
> can say that the XSLT component take two parameters initial-mode and
> initial-template, plus any parameter that starts with "param-"; any of
> those parameter will be passed to the stylesheet without the "param-".

The trouble with relying on naming conventions is that it restricts the 
names that people can use. For example, if the convention is that the 
substring before the first hyphen gives the name of the parameter, then 
having 'initial-mode' and 'initial-template' implies that there's 
similarly a parameter called 'initial' which has two subparts 'mode' and 
'template'. So you'd really want to avoid using a hyphen in names...

I think the problem we have is in handling data that is neither simple 
enough to be represented in a string nor complex enough to justify being 
an XML input. In other words lists (like Alex's list of mime types) or 
dictionaries (like XSLT's parameters, HTTP headers and POST parameters).

I see three possibilities:

1. Say that all parameters are strings, and in all the built-in 
components use a convention (such as JSON) for representing lists and 
dictionaries:

<p:munge>
   <p:mime-types>
     [ "application/pdf", "image/jpeg", "text/html" ]
   </p:mime-types>
</p:munge>

<p:xslt>
   <p:initial-mode>#default</p:initial-mode>
   <p:parameters>
     { "foo": "This is the value of $foo",
       "bar": "This is the value of $bar" }
   </p:parameters>
</p:xslt>

<p:http>
   <p:username>...</p:username>
   <p:password>...</p:password>
   <p:headers>
     { "User-Agent": "...",
       "Authorization": "..." }
   </p:headers>
   <p:parameters>
     { "firstname": "...",
       "lastname": "..." }
   </p:parameters>
</p:http>



2. Say that lists and dictionaries should be represented by XML 
documents, passed as inputs. These XML documents can follow a set pattern:

<p:munge>
   <p:input port="mime-types">
     <p:list>
       <p:item>application/pdf</p:item>
       <p:item>image/jpeg</p:item>
       <p:item>text/html</p:item>
     </p:list>
   </p:input>
</p:munge>

<p:xslt>
   <p:initial-mode>#default</p:initial-mode>
   <p:input port="parameters">
     <p:dictionary>
       <p:entry name="foo">This is the value of $foo</p:entry>
       <p:entry name="bar">This is the value of $bar</p:entry>
     </p:dictionary>
   </p:input>
</p:xslt>

<p:http>
   <p:username>...</p:username>
   <p:password>...</p:password>
   <p:input port="headers">
     <p:dictionary>
       <p:entry name="User-Agent">...</p:entry>
       <p:entry name="Authorization">...</p:entry>
     </p:dictionary>
   </p:input>
   <p:input port="parameters">
     <p:dictionary>
       <p:entry name="firstname">...</p:entry>
       <p:entry name="lastname">...</p:entry>
     </p:dictionary>
   </p:input>
</p:http>



3. Introduce mechanisms for dealing with list and dictionary parameters, 
such as a repeated parameter to construct a list and parameters with 
name attributes to construct a dictionary. (The type of the parameter 
would be set when the parameter was defined.)

<p:munge>
   <p:mime-type>application/pdf</p:mime-type>
   <p:mime-type>image/jpeg</p:mime-type>
   <p:mime-type>text/html</p:mime-type>
</p:munge>

<p:xslt>
   <p:initial-mode>#default</p:initial-mode>
   <p:param name="foo">This is the value of $foo</p:param>
   <p:param name="bar">This is the value of $bar</p:param>
</p:xslt>

<p:http>
   <p:username>...</p:username>
   <p:password>...</p:password>
   <p:header name="User-Agent">...</p:header>
   <p:header name="Authorization">...</p:header>
   <p:parameter name="firstname">...</p:parameter>
   <p:parameter name="lastname">...</p:parameter>
</p:http>


(1) keeps things pretty simple in terms of the specification, is very 
powerful and flexible, but can make it hard for the user who wants to, 
say, set the value of an XSLT parameter based on an input document. In 
the current set-up, string construction can only be done in a select 
attribute, using concat(), which makes it very fiddly.

(2) keeps things pretty simple in terms of the specification, is very 
powerful and flexible, but is verbose. Plus setting values dynamically 
is convaluted (you have to go through a transformation to do so), and 
the blurring of the line between inputs and parameters might be seen as 
a problem.

(3) would add complexity to the specification and isn't as powerful as 
(1) or (2), in that you can't dynamically decide whether to add an item 
to a list or entry to a dictionary, but is fairly simple for users.

FWIW, (3) appeals to me, but I know I'm prone to over-engineering these 
things and (1) and (2) seem perfectly feasible options as well.

Cheers,

Jeni
-- 
Jeni Tennison
http://www.jenitennison.com

Received on Thursday, 1 March 2007 09:41:32 UTC