RE: Custom functions (Major re-write, please review)

Nick,

> In my opinion the above example is sufficient. In XQuery you can already
> namespace your variables to prevent name collisions (e.g.: my:values
> instead of values) with other 'libraries'. In javascript you can namespace
> your variables, but we can't use the full XML namespace as the namespace.
> Therefore I proposed to always use the XForms.var.{local-variable-name}
> (consequenctly my:foo would hide my2:foo in the javascript binding...).

Ok.


> Having the script element allows you to put the script in a separate file
> and use the src attribute (you probably won't the src attribute then also
> available on the function element)

I don't think the src attribute would be of any use in this context. If you declare the function signature in the XForm then what would you put in your external file? Would you repeat the function signature to make the file's content a valid script or would you have a naked sequence of expressions without a signature?


> The sequence element is the only constructor element for now, but in the
> future we could also have other constructor elements like they have in XSLT
> to allow easy creation of mixed content.

Even if we went for the full XSLT style function declaration instructions, with variable, sequence, value-of, etc... I don't then see how they'd have a meaning in a situation where you were using JavaScript. It's a collision between two different worlds. Although it sounds a bit restrictive, I think it would make things a lot simpler to say the following:

1) If you want to use variables and/or XML literals then use a language that supports them e.g JavaScript or XQuery (XForms implementation permitting).
2) There should be a 'value' attribute that can contain simple expressions.
3) You can use the text content of the 'function' instruction to declare the function's body (this makes it easy to use CDATA).
4) In the absence of a 'type' attribute assume the value/text is an XPath expression (this is because there's no MIME-Type for XPath).
5) Where both a 'value' attribute and text content are present one or other takes precedence (I think we do something similar with resource attribute and element and the attribute takes precedence I think.)



Regards

Philip




From: Nick Van den Bleeken [mailto:Nick.Van.den.Bleeken@inventivegroup.com]
Sent: Wednesday, March 21, 2012 11:57 AM
To: Philip Fennell
Cc: Public Forms
Subject: Re: Custom functions (Major re-write, please review)

Hi Philip,

Thank you for your reply.


1) If the XForms implementation supported XQuery them how would the body of the function be declared:

<function signature="my:clip($values as xs:decimal*, $threshold as xs:decimal) as xs:decimal*">
   <script type="application/xquery">
      for $v in $values
      where $v le $threshold
      return
         $v
   </script>
</function>

Is the above example sufficient or would you use some namespace/context prefix, like that which you describe for JavaScript, to identify parameters declared in the function signature?

In my opinion the above example is sufficient. In XQuery you can already namespace your variables to prevent name collisions (e.g.: my:values instead of values) with other 'libraries'. In javascript you can namespace your variables, but we can't use the full XML namespace as the namespace. Therefore I proposed to always use the XForms.var.{local-variable-name}  (consequenctly my:foo would hide my2:foo in the javascript binding...).



2) Do we really need the script and sequence elements? We could do away with both of these elements as follows:

* Move the type attribute up to the function element.
* The return type defines whether the result is a sequence or not. Therefore, there's no need to explicitly use a sequence constructor instruction.
* To my mind, and this is a personal opinion, separating the body from the signature declaration, by placing it in a script element, seems to distance it from its signature declaration. I'd feel more comfortable writing the body of the function as the content of the function.

If we did away with the script/sequence element then how would we identify plain XPath expressions as the body of the function:

<function signature="my:foo($p as xs:decimal*) as xs:decimal">
  sum($p)
</function>

Would it be enough to make the type attribute optional and in its absence the default behaviour is to evaluate the body as XPath?


Having the script element allows you to put the script in a separate file and use the src attribute (you probably won't the src attribute then also available on the function element)

The sequence element is the only constructor element for now, but in the future we could also have other constructor elements like they have in XSLT to allow easy creation of mixed content. Not completely sure that we need this though... (more people have proposed to drop the sequence element).

As far as I know this would be the first place where you can enter an XPath expression outside an attribute in XForms (even in XSLT all path expressions are in attributes).

I have a slight preference for having an extra element, but it looks like more people just want it as direct content, we should shortly discuss it on the phone to get a resolution on this one I guess.



3) The override attribute's semantics is very clear and precise but I was wondering whether we could introduce a 'use-when' mechanism that allows us to provide a broader control over when custom functions, and other features for that matter, are used. It would be statically evaluated. The 'use-when' concept is already well understood by XSLT and XProc users. The use cases include:

* Only use this declaration when using a particular XForms implementation: use-when="system-property('xf:vendor') = 'Orbeon'"
* If the default behaviour is to override then to disable that: use-when="not(function-available('my:foo'))"

Now, I admit that the second use case looks a bit clumsy compared to override="no". May be there's room for both?


use-when is a neat feature and xsl:function supports both use-when and override attributes. In my opinion the use-when attribute is a bit of strange beast ;) because it has no access to information defined in the document nor to any source document. This will be the first path expression that doesn't follow the in-scope evaluation rules. So I'm a bit reluctant to add it to the XForms spec, and if we add it, it should be a global element that can be added on all xforms elements **and** host language elements. (for people who don't know the use-when attribute see http://www.w3.org/TR/xslt20/#conditional-inclusion for more information). I think there is room for both attributes.



Regards

Philip




Kind regards,

Nick Van den Bleeken
R&D Manager

Phone: +32 3 425 41 02
Office fax: +32 3 821 01 71
nick.van.den.bleeken@inventivegroup.com<mailto:nick.van.den.bleeken@inventivegroup.com>
www.inventivedesigners.com


[cid:image001.png@01CD0788.E2FDE850][cid:image002.png@01CD0788.E2FDE850][cid:image003.png@01CD0788.E2FDE850]

On 21 Mar 2012, at 11:29, Philip Fennell wrote:








From: Nick Van den Bleeken [mailto:Nick.Van.den.Bleeken@inventivegroup.com]
Sent: Thursday, March 15, 2012 10:44 AM
To: Erik Bruchez
Cc: Public Forms
Subject: Re: Custom functions (Major re-write, please review)

I've integrated everything we discussed yesterday to the XForms 2.0 spec. I also added editorial notes for all the things we didn't came to a resolution.

 http://www.w3.org/MarkUp/Forms/wiki/XForms_2.0#The_function_Element

Please review.

Kind regards,

Nick Van den Bleeken
R&D Manager

Phone: +32 3 425 41 02
Office fax: +32 3 821 01 71
nick.van.den.bleeken@inventivegroup.com<mailto:nick.van.den.bleeken@inventivegroup.com>
www.inventivedesigners.com<http://www.inventivedesigners.com>


<image001.png><image002.png><image003.png>

On 14 Mar 2012, at 11:36, Nick Van den Bleeken wrote:

Apparently I miss interpreted the XPath 3.0 spec. Michael Kay says "User-defined functions get no context item, position, or size. That's true both for named global functions and inline functions."

So I think our custom functions also shouldn't do that. Now that we have variables you can work around this limitation.

Example:

<var name="context" value="."/>

<var name="context-pos" value="position()"/>

<var name="context-size" value="last()"/>

<function signature="my:f() as number" value="$context-pos = $context-size"/>



Kind regards,

Nick Van den Bleeken
R&D Manager

Phone: +32 3 425 41 02
Office fax: +32 3 821 01 71
nick.van.den.bleeken@inventivegroup.com<mailto:nick.van.den.bleeken@inventivegroup.com>
www.inventivedesigners.com<http://www.inventivedesigners.com>


<image001.png><image002.png><image003.png>

On 13 Mar 2012, at 16:39, Nick Van den Bleeken wrote:

Erik,

I might interpret it incorrectly but reading the XPath 3.0 spec:

"The static context for the function body is inherited from the location of the inline function expression, with the exception of the static type of the context item which is initially undefined.

The variables in scope for the function body include all variables representing the function parameters, as well as all variables that are in scope for the inline function expression." [1]

I think the focus (context item, context position, and context size) is the same inside the function body and where the function is defined, you only don't have the static type information of the context item in the function body.

Kind regards,

Nick Van den Bleeken
R&D Manager

Phone: +32 3 425 41 02
Office fax: +32 3 821 01 71
nick.van.den.bleeken@inventivegroup.com<mailto:nick.van.den.bleeken@inventivegroup.com>
www.inventivedesigners.com<http://www.inventivedesigners.com/>

1: http://www.w3.org/TR/xpath-30/#id-inline-func

On 12 Mar 2012, at 17:23, Erik Bruchez wrote:

Biased +1 ;)

In particular the function signature idea is in line with other suggestions to reduce markup, and the good part is that we don't have to reinvent the wheel for the syntax.

Where I have a doubt is whether we should define an initial context for the functions. Ideally there should be one defined, but unless I am mistaken XPath 3.0 still says there is no initial context, is that right? If so my main concern would be the ease of using an XPath 3.0 implementation out of the box to implement functions.

-Erik
On Thu, Mar 8, 2012 at 11:56 PM, Nick Van den Bleeken <Nick.Van.den.Bleeken@inventivegroup.com<mailto:Nick.Van.den.Bleeken@inventivegroup.com>> wrote:
Alex and I have had a good constructive discussion about custom functions on twitter. He summarized the discussion here https://gist.github.com/2002642

I think we should implement all remarks. What does the group think of this?

Kind regards,

Nick Van den Bleeken
R&D Manager

Phone: +32 3 425 41 02<tel:%2B32%203%20425%2041%2002>
Office fax: +32 3 821 01 71<tel:%2B32%203%20821%2001%2071>
nick.van.den.bleeken@inventivegroup.com<mailto:nick.van.den.bleeken@inventivegroup.com>
www.inventivedesigners.com<http://www.inventivedesigners.com/>


<image001.png><image002.png><image003.png>

On 08 Mar 2012, at 18:22, Nick Van den Bleeken wrote:

All,

I've updated http://www.w3.org/MarkUp/Forms/wiki/Custom_XPath_functions I tried to make the text more XForms spec like (no longer XSLT spec like)

I made one change to what we agreed on the call yesterday.

The current spec doesn't allows you to intermix script and sequence child elements. I did this because you are allowed to use multiple sequence (and script) elements as the body of a function element to allow easy creation of result sequences. And if you allow multiple sequence (and script) elements it becomes a bit unclear what you want to achieve when you intermix those.

But I allow the author to override already defined functions. I also added an extra attribute override to let the author choose if he wants to override already defined functions. This has the nice consequence that a form author could use XForms implementation specific functions but include a declaration of those functions that will be used in implementations that don't have those functions (by setting override to no).

I put an example of how to fall back to an XPath implementation of a function if the processor doesn't support javascript in 'specification'.

If the form author writes the example like this it would even default to the native implementation if the XForms implementation has implemented the function:


<function name="my:foo" as="number" override="no">

   <param name="p" as="nodeset"/>



   <script type="text/javascript">

      foo(XForms.var.p);

   </script>

</function>

<function name="my:foo" as="number" override="no">

   <param name="p" as="nodeset"/>



   <sequence select="sum($p)"/>

</function>



As you can see in the example I name spaced all 'variables' this is best practice in javascript and many other languages.

===============================================================

I also needed to delete the following example because 'Within the body of a custom function, the focus is initially undefined; this means that any attempt to reference the context item, context position, or context size is a non-recoverable dynamic error.' I would like to follow XSLT's take on this, because this allows you to 'import' the function from anywhere without unexpected side effects.

Example: function selecting all elements called "name" in an instance.

<pre><nowiki>
<function name="my:get-names" as="nodeset">
    <sequence select="//name"/>
</function>
</nowiki></pre>


All comments are very welcome.

Kind regards,

Nick Van den Bleeken
R&D Manager

Phone: +32 3 425 41 02<tel:%2B32%203%20425%2041%2002>
Office fax: +32 3 821 01 71<tel:%2B32%203%20821%2001%2071>
nick.van.den.bleeken@inventivegroup.com<mailto:nick.van.den.bleeken@inventivegroup.com>
www.inventivedesigners.com<http://www.inventivedesigners.com/>
<image001.png><image002.png><image003.png>


________________________________

Inventive Designers' Email Disclaimer:
http://www.inventivedesigners.com/email-disclaimer
--
This message has been scanned for viruses and
dangerous content by MailScanner<http://www.mailscanner.info/>, and is
believed to be clean.


________________________________

Inventive Designers' Email Disclaimer:
http://www.inventivedesigners.com/email-disclaimer


--
This message has been scanned for viruses and
dangerous content by MailScanner<http://www.mailscanner.info/>, and is
believed to be clean.


________________________________

Inventive Designers' Email Disclaimer:
http://www.inventivedesigners.com/email-disclaimer

--
This message has been scanned for viruses and
dangerous content by MailScanner<http://www.mailscanner.info/>, and is
believed to be clean.


________________________________

Inventive Designers' Email Disclaimer:
http://www.inventivedesigners.com/email-disclaimer

--
This message has been scanned for viruses and
dangerous content by MailScanner<http://www.mailscanner.info/>, and is
believed to be clean.


________________________________

Inventive Designers' Email Disclaimer:
http://www.inventivedesigners.com/email-disclaimer

--
This message has been scanned for viruses and
dangerous content by MailScanner<http://www.mailscanner.info/>, and is
believed to be clean.


________________________________

Inventive Designers' Email Disclaimer:
http://www.inventivedesigners.com/email-disclaimer