Re: ACTION-1970 - Propose list of page access functions

All,

Following our last call, the idea was to change the approach to the
following:

- provide one function to access the document location
- provide general-purpose URL destructuring functions

The proposal becomes as follows:

This function returns a URI representing the location of the document:

    xf:location-uri() as xs:anyURI

(This is expected to be an HTTP or HTTPS URL for practical purposes.)

The following functions all take a URI as first parameter, and return a
specific part. The various parts are inspired by the Java URI class, which
I think is reasonable: [1]

    xf:uri-scheme($uri as xs:anyURI) as xs:string?
    xf:uri-scheme-specific-part($uri as xs:anyURI, $raw as xs:boolean) as
xs:string?
    xf:uri-authority($uri as xs:anyURI, $raw as xs:boolean) as xs:string?
    xf:uri-user-info($uri as xs:anyURI, $raw as xs:boolean) as xs:string?
    xf:uri-host($uri as xs:anyURI) as xs:string?
    xf:uri-port($uri as xs:anyURI) as xs:integer?
    xf:uri-path($uri as xs:anyURI, $raw as xs:boolean) as xs:string?
    xf:uri-query($uri as xs:anyURI, $raw as xs:boolean) as xs:string?
    xf:uri-fragment($uri as xs:anyURI, $raw as xs:boolean) as xs:string?

Each function may not return a given component, in which case it returns
the empty sequence.

Some of these functions take an optional $raw parameter [2], which defaults
to `false()`. When $raw is `true()`, the value is returned "without
interpreting any escaped octets".

The following two functions, which were the ones initially desired, are
added:

    xf:param-names($uri as xs:anyURI) as xs:string*
    xf:param-values($uri as xs:anyURI, $name as xs:string) as xs:string*

They only return a non-empty sequence for hierarchical URIs which have a
query part. The first one returns all parameter names, possibly with
duplicates, in the order in which they appear. The second one returns all
parameter values for a given parameter name, in the order in which they
appear.

Alternatively, these two functions could apply directly to a query string,
rather than to a URI.

Examples:

1. Get the current path:

  xf:uri-path(xf:location-uri())

2. Get the first "foo"  URL parameter:

  xf:param-values(xf:location-uri(), 'foo')[1]

I think the above would be pretty comprehensive as far as figuring out URI
parts.

One question is whether to standardize all of this directly in XForms, or
to request broader feedback, for example from EXPath [3].

Feedback welcome,

-Erik

[1] http://docs.oracle.com/javase/8/docs/api/java/net/URI.html
[2] Which in XPath means each function has two versions.
[3] http://expath.org/

On Tue, Apr 15, 2014 at 10:25 PM, Erik Bruchez <erik@bruchez.org> wrote:
> All,
>
> Here is my list of proposed functions related to the page location
> (browser) or request information (server).
>
> I think, at the very least, we would like something to help with query
> parameters. Something like:
>
>     xf:parameter-names() as xs:string*
>     xf:parameter-values($name as xs:string) as xs:string*
>
> We can go further and provide access to more details of the location:
>
> Entire URL:
>
>     xf:location-url() as xs:anyURI
>
> URL parts, following mostly :
>
>     xf:location-protocol() as xs:string
>     xf:location-host() as xs:string
>     xf:location-port() as xs:string
>     xf:location-path() as xs:string
>     xf:location-query() as xs:string
>     xf:location-hash() as xs:string
>
> (The browser has "pathname" instead of "path", and "search" instead of
> "query". Those sound a bit antique and odd.)
>
> Server implementations are not expected to be able to provide
> `xf:location-hash()`, as that is known by the client only.
>
> In addition, the following username/password are possible but of
> dubious utility:
>
>     xf:location-username() as xs:string
>     xf:location-password() as xs:string
>
> On the client, this would be available if you have:
>
>     http://foo:bar@example.org/
>
> At this point it seems (not verified) that only Firefox supports
> username/password. On the server, this would translate into obtaining
> the username/password of a BASIC authentication, which may or may not
> be available.
>
> On naming:
>
> 1. We could use a common prefix, e.g. `location-` for all. But
> `xf:location-parameter-names()` and `xf:location-parameter-values()`
> become very  long in that case.
>
> 2. We could also use a different namespace URI for what we would call
> a "request" or "location" module.
>     - Pros: shorter names, like `l:port()`, and a clearer sense of
modularity
>     - Cons: a new namespace, and people don't like namespaces.
>
> Feedback welcome!
>
> -Erik