Loading ...
Sorry, an error occurred while loading the content.
 

Using URI templates in XHTML

Expand Messages
  • Philippe Mougin
    Hi, Context: ******** I m using XHTML for the representation of some resources, in a Restful machine-to-machine context. In particular, I m using it for
    Message 1 of 19 , Nov 9, 2011
      Hi,

      Context:
      ********
      I'm using XHTML for the representation of some resources, in a Restful machine-to-machine context. In particular, I'm using it for representing the "entry point" of my system, from where clients can dynamically learn how to construct URLs to other resources and start navigate the resource space. To that end I've been using XHTML <a> and <form> elements as hypermedia controls.

      URI templates:
      **************
      I'm now in possession of a shinny new URI-template library (implementing http://tools.ietf.org/html/draft-gregorio-uritemplate-07) that I plan to embed in some of the clients of my system. These client programs will then be able to easily interpret (i.e., expand) URI templates.

      Question:
      *********
      I'd like to use URI template as hypermedia control in XHTML, as a (richer) alternative to my existing forms. What do you think is the best way to do so ? Specifically, how would you represent an URI template in XHTML (given it must be used as a hypermedia control for programatic clients)?

      Thanks,
      Philippe Mougin
    • Eric J. Bowman
      ... XForms is also very useful for constructing URLs on the client. ... Consensus will need to be reached, eventually, but I d suggest that URI templates be
      Message 2 of 19 , Nov 9, 2011
        "Philippe Mougin" wrote:
        >
        > Context:
        > ********
        > I'm using XHTML for the representation of some resources, in a
        > Restful machine-to-machine context. In particular, I'm using it for
        > representing the "entry point" of my system, from where clients can
        > dynamically learn how to construct URLs to other resources and start
        > navigate the resource space. To that end I've been using XHTML <a>
        > and <form> elements as hypermedia controls.
        >

        XForms is also very useful for constructing URLs on the client.

        >
        > Question:
        > *********
        > I'd like to use URI template as hypermedia control in XHTML, as a
        > (richer) alternative to my existing forms. What do you think is the
        > best way to do so ? Specifically, how would you represent an URI
        > template in XHTML (given it must be used as a hypermedia control for
        > programatic clients)?
        >

        Consensus will need to be reached, eventually, but I'd suggest that URI
        templates be integrated into (X)HTML with new attributes -- any existing
        attribute which takes a URI (@href, @src etc.) may take a suffix of 't'
        to indicate the presence of an expansion model which yields a URI
        (@hreft, @srct etc.).

        The real problem is how to indicate the allowable values for expansions,
        for the purpose of generating a list of possible state transitions (just
        like a form). I can imagine doing this in XForms, and having a re-
        usable library. I don't know the nature of the library you mention, but
        code-on-demand is just as valid for generating a list of links (even as
        a GET <form>).

        -Eric
      • Mike Kelly
        ... There s already an adequate solution to that problem - you can define the inputs up-front against the link relation in question. e.g. the link relation
        Message 3 of 19 , Nov 9, 2011


          On Wed, Nov 9, 2011 at 6:06 PM, Eric J. Bowman <eric@...> wrote:
          "Philippe Mougin" wrote:
          >
          > Question:
          > *********
          > I'd like to use URI template as hypermedia control in XHTML, as a
          > (richer) alternative to my existing forms. What do you think is the
          > best way to do so ? Specifically, how would you represent an URI
          > template in XHTML (given it must be used as a hypermedia control for
          > programatic clients)?
          >

          Consensus will need to be reached, eventually, but I'd suggest that URI
          templates be integrated into (X)HTML with new attributes -- any existing
          attribute which takes a URI (@href, @src etc.) may take a suffix of 't'
          to indicate the presence of an expansion model which yields a URI
          (@hreft, @srct etc.).

          The real problem is how to indicate the allowable values for expansions,
          for the purpose of generating a list of possible state transitions (just
          like a form).  I can imagine doing this in XForms, and having a re-
          usable library.  I don't know the nature of the library you mention, but
          code-on-demand is just as valid for generating a list of links (even as
          a GET <form>).


          There's already an adequate solution to that problem - you can define the inputs up-front against the link relation in question.

          e.g. the link relation 'circle' has an href containing a URI template which accepts the variable 'radius'

          which tells you what you need to know to build an automated client which follows this link:

          <a rel="circle" href="/circle/radius;{radius}" />

          Cheers,
          Mike
        • Eric J. Bowman
          ... I don t see invalid markup as an adequate solution -- @href takes a URI, not a template; section 1.4 of the URI-template draft states that URI templates
          Message 4 of 19 , Nov 9, 2011
            Mike Kelly wrote:
            >
            > There's already an adequate solution to that problem - you can define
            > the inputs up-front against the link relation in question.
            >

            I don't see invalid markup as an adequate solution -- @href takes a
            URI, not a template; section 1.4 of the URI-template draft states that
            URI templates aren't URIs. Instead of having to parse @href before
            determining how to parse @href (is it a URI or a template), it makes
            sense to follow the logic in the URI-template draft and provide new
            attributes to match a new parsing model (or elements, in the case of
            XForms elements which take URIs as content).

            >
            > e.g. the link relation 'circle' has an href containing a URI template
            > which accepts the variable 'radius'
            >
            > which tells you what you need to know to build an automated client
            > which follows this link:
            >
            > <a rel="circle" href="/circle/radius;{radius}" />
            >

            How? Does @href take on a different syntax due to the definition of
            rel='circle'? Where is *that* in the media type definition for XHTML?

            -Eric
          • Mike Kelly
            ... You re focusing on a side issue. Let s change it to this for now: Is that (and the description of the
            Message 5 of 19 , Nov 9, 2011
              On Wed, Nov 9, 2011 at 7:40 PM, Eric J. Bowman <eric@...> wrote:
              >
              > Mike Kelly wrote:
              > >
              > > There's already an adequate solution to that problem - you can define
              > > the inputs up-front against the link relation in question.
              > >
              >
              > I don't see invalid markup as an adequate solution -- @href takes a
              > URI, not a template; section 1.4 of the URI-template draft states that
              > URI templates aren't URIs.  Instead of having to parse @href before
              > determining how to parse @href (is it a URI or a template), it makes
              > sense to follow the logic in the URI-template draft and provide new
              > attributes to match a new parsing model (or elements, in the case of
              > XForms elements which take URIs as content).
              >
              > >
              > > e.g. the link relation 'circle' has an href containing a URI template
              > > which accepts the variable 'radius'
              > >
              > > which tells you what you need to know to build an automated client
              > > which follows this link:
              > >
              > > <a rel="circle" href="/circle/radius;{radius}" />
              > >
              >
              > How?  Does @href take on a different syntax due to the definition of
              > rel='circle'?  Where is *that* in the media type definition for XHTML?
              >

              You're focusing on a side issue. Let's change it to this for now:

              <a rel="circle" hreft="/circle/radius;{radius}" />

              Is that (and the description of the rel circle) not an adequate
              solution to the "real problem" you mentioned before?

              Cheers,
              Mike
            • Eric J. Bowman
              ... No, it is not adequate. The definition of rel= circle still doesn t tell me what the range of allowable values is for the application domain, or what
              Message 6 of 19 , Nov 9, 2011
                Mike Kelly wrote:
                >
                > You're focusing on a side issue. Let's change it to this for now:
                >
                > <a rel="circle" hreft="/circle/radius;{radius}" />
                >
                > Is that (and the description of the rel circle) not an adequate
                > solution to the "real problem" you mentioned before?
                >

                No, it is not adequate. The definition of rel='circle' still doesn't
                tell me what the range of allowable values is for the application
                domain, or what units are used. An XForms slider control can delimit
                the allowable values and declare them to be pixels, resulting in a
                self-documenting API instead of an endpoint dependent upon out-of-band
                knowledge.

                -Eric
              • Mike Kelly
                ... Yes, it s an incomplete example. The definition could be extended to include that information, right? ... This would be a self-documenting API to you, but
                Message 7 of 19 , Nov 9, 2011
                  On Thu, Nov 10, 2011 at 12:19 AM, Eric J. Bowman <eric@...> wrote:
                  > Mike Kelly wrote:
                  >>
                  >> You're focusing on a side issue. Let's change it to this for now:
                  >>
                  >> <a rel="circle" hreft="/circle/radius;{radius}" />
                  >>
                  >> Is that (and the description of the rel circle) not an adequate
                  >> solution to the "real problem" you mentioned before?
                  >>
                  >
                  > No, it is not adequate.  The definition of rel='circle' still doesn't
                  > tell me what the range of allowable values is for the application
                  > domain, or what units are used.

                  Yes, it's an incomplete example. The definition could be extended to
                  include that information, right?

                  > An XForms slider control can delimit
                  > the allowable values and declare them to be pixels, resulting in a
                  > self-documenting API instead of an endpoint dependent upon out-of-band
                  > knowledge.

                  This would be a self-documenting API to you, but not to the automated
                  (m2m) client you build against it. An automated client is dependent on
                  the knowledge you instill it with up front which, from its point of
                  view when interacting with the application, is out-of-band.

                  I'm not clear on what you mean by 'endpoint' here, either.

                  Cheers,
                  Mike
                • Eric J. Bowman
                  ... No, not if we re talking about REST s uniform interface. A generic description of rel= circle could conceivably require a positive integer, but
                  Message 8 of 19 , Nov 9, 2011
                    Mike Kelly wrote:
                    >
                    > >
                    > > No, it is not adequate.  The definition of rel='circle' still
                    > > doesn't tell me what the range of allowable values is for the
                    > > application domain, or what units are used.
                    >
                    > Yes, it's an incomplete example. The definition could be extended to
                    > include that information, right?
                    >

                    No, not if we're talking about REST's uniform interface. A generic
                    description of rel='circle' could conceivably require a positive
                    integer, but individual application domains must still have a mechanism
                    to delimit the value, i.e. declare a range of 4 - 50. Declaring that
                    range in the definition of the link relation limits the re-use of that
                    link relation in other application domains, since it's application-
                    specific. Such application specifics belong in hypertext, not link-
                    relation definitions (which should strive to be generic).

                    >
                    > > An XForms slider control can delimit
                    > > the allowable values and declare them to be pixels, resulting in a
                    > > self-documenting API instead of an endpoint dependent upon
                    > > out-of-band knowledge.
                    >
                    > This would be a self-documenting API to you, but not to the automated
                    > (m2m) client you build against it.
                    >

                    It would be a self-documenting API for any user-agent which understands
                    the slider form control, I fail to see what bearing the nature of the
                    user (machine or human) has on it.

                    >
                    > An automated client is dependent on the knowledge you instill it with
                    > up front which, from its point of view when interacting with the
                    > application, is out-of-band.
                    >

                    You lost me there. REST is the antithesis of hard-coding such
                    information into the client code. If the range of 4 - 50 is baked into
                    the client code, the client can't adapt if the service modifies the
                    allowable range. If, however, this range is presented in a hypertext
                    control, updating the service range from 4 - 50 to 4 - 25 won't break
                    existing clients because this knowledge is presented in-band.

                    >
                    > I'm not clear on what you mean by 'endpoint' here, either.
                    >

                    Instead of the hypertext providing the user-agent with instructions as
                    to the allowable state transitions (links), your example provides an
                    endpoint where undefined values derived through out-of-band knowledge
                    may be used to expand {radius}. That's quite different from using
                    hypertext to drive application state, so I'm calling it an endpoint.

                    -Eric
                  • Marc Portier
                    ... care to share which one? I ve been working on a js-jquery implementation at https://github.com/marc-portier/uri-templates/ myself ... good question, and an
                    Message 9 of 19 , Nov 10, 2011
                      On 09-11-11 17:39, Philippe Mougin wrote:

                      >
                      > URI templates:
                      > **************
                      > I'm now in possession of a shinny new URI-template library (implementing
                      > http://tools.ietf.org/html/draft-gregorio-uritemplate-07) that I plan to

                      care to share which one?

                      I've been working on a js-jquery implementation at
                      https://github.com/marc-portier/uri-templates/ myself


                      > embed in some of the clients of my system. These client programs will
                      > then be able to easily interpret (i.e., expand) URI templates.
                      >
                      > Question:
                      > *********
                      > I'd like to use URI template as hypermedia control in XHTML, as a
                      > (richer) alternative to my existing forms. What do you think is the best
                      > way to do so ? Specifically, how would you represent an URI template in
                      > XHTML (given it must be used as a hypermedia control for programatic
                      > clients)?
                      >

                      good question, and an interesting field for further 'standardisation'
                      IMHO... some first thoughts:

                      uri-templates are macro's producing actual uri's for individual 'contexts'

                      Below I assume you think about in-browser (js) code that will be
                      expanding the templates, right? If not: server side-expansion just
                      yields uri's that can be injected in the HTML: so nothing special needed.


                      Anyway, in terms of HTML such I think the lists of contexts could be
                      provided by any repeating thing like ul/li, table/tr, p

                      in a json-wrapped way:

                      <li data-context='{"id": "3367-29283-2484", "type": "item", "field":
                      "whatever"}'> label </li>

                      or a more distributed way:

                      <tr data-id="3367-29283-2484"><td>label</td><td
                      data-context-name="type">item</td><td
                      data-context-name="field">whatever</td></tr>

                      (or even think microformats, and use class attributes rather then data-x)



                      What remains is the need to know for each of these contexts in which
                      template they should be injected (to achieve what result)

                      So on the surrounding <ul> or <table> you could envision some indication
                      of those:

                      <ul data-uri-t="item-ref, item-form" > stating that these templates are
                      useful on the items nested in the ul


                      All that then makes sense inside some browser-state (HTML provided, HTTP
                      header, provided, ajax loaded or whatever) where item-ref and item-form
                      are known relations for 'links', something of the equivalent of

                      <link rel="item-ref" href="item/{type}/{id}" /><!-- GET PUT DELETE -->
                      <link rel="item-form" href="forms/{type}{?id}" /><!-- GET POST -->


                      with a self-describing pure data-structure like this one could think
                      about jquery code that enhances the structure with onclick-events or
                      even added in clickable icons to follow the uri's associated to the
                      various relations


                      as said, just some first thoughts
                      -marc=

                      > Thanks,
                      > Philippe Mougin
                      >
                      >
                    • Mike Kelly
                      ... Those application domains can extend and/or over-ride the description to suit their specific requirements. ... Right, a system-wide description of a rel
                      Message 10 of 19 , Nov 10, 2011
                        On Thu, Nov 10, 2011 at 3:02 AM, Eric J. Bowman <eric@...> wrote:
                        > Mike Kelly wrote:
                        >>
                        >> >
                        >> > No, it is not adequate.  The definition of rel='circle' still
                        >> > doesn't tell me what the range of allowable values is for the
                        >> > application domain, or what units are used.
                        >>
                        >> Yes, it's an incomplete example. The definition could be extended to
                        >> include that information, right?
                        >>
                        >
                        > No, not if we're talking about REST's uniform interface.  A generic
                        > description of rel='circle' could conceivably require a positive
                        > integer, but individual application domains must still have a mechanism
                        > to delimit the value, i.e. declare a range of 4 - 50.

                        Those application domains can extend and/or over-ride the description
                        to suit their specific requirements.

                        > Declaring that
                        > range in the definition of the link relation limits the re-use of that
                        > link relation in other application domains, since it's application-
                        > specific.

                        Right, a system-wide description of a rel will be more generic than an
                        application-specific one, extension is re-use.

                        > Such application specifics belong in hypertext, not link-
                        > relation definitions (which should strive to be generic).

                        I think this might be based on unexamined suppositions.

                        >>
                        >> > An XForms slider control can delimit
                        >> > the allowable values and declare them to be pixels, resulting in a
                        >> > self-documenting API instead of an endpoint dependent upon
                        >> > out-of-band knowledge.
                        >>
                        >> This would be a self-documenting API to you, but not to the automated
                        >> (m2m) client you build against it.
                        >>
                        >
                        > It would be a self-documenting API for any user-agent which understands
                        > the slider form control, I fail to see what bearing the nature of the
                        > user (machine or human) has on it.

                        To me, self-documenting means clients interact with the application by
                        intuitively comprehending the semantics and controls they are
                        presented with as they are proceeding through the application. So the
                        question is; are machine clients capable of a level of intuitive
                        comprehension to make these more complex form controls worth pursuing?
                        I'm not sure they are.

                        The current available writing on machine based form consumption seems
                        to focus on the theoretical benefits without actually demonstrating
                        the extent of change they can enable, in practice, over the
                        out-of-band approach.

                        The question is not whether machines can or can't interact with
                        form-like controls, they can, it's whether doing so is worth the
                        effort or is prohibitively complex.

                        I guess keeping consumption of your application down by making it both
                        theoretically 'pure' and prohibitively complex is one way of dealing
                        with a scalability challenge.

                        >>
                        >> An automated client is dependent on the knowledge you instill it with
                        >> up front which, from its point of view when interacting with the
                        >> application, is out-of-band.
                        >>
                        >
                        > You lost me there.  REST is the antithesis of hard-coding such
                        > information into the client code.

                        Which part of the dissertation are you taking this from?

                        > If the range of 4 - 50 is baked into
                        > the client code, the client can't adapt if the service modifies the
                        > allowable range.  If, however, this range is presented in a hypertext
                        > control, updating the service range from 4 - 50 to 4 - 25 won't break
                        > existing clients because this knowledge is presented in-band.

                        This is the wrong way of thinking about this problem. In either case,
                        the automated client will be fed an objective which included a
                        now-out-of-range value. The only change to the client behaviour you
                        are making, is that the client can use the control to pre-empt a 4xx
                        response and avoid making the request in the first place. In both
                        cases the automated client will still have to take some
                        pre-established action hard-coded into it. That is the nature of
                        automated things.

                        Cheers,
                        Mike
                      • Philippe Mougin
                        Marc, thanks for answering. ... It s a Java library developed by a colleague. It isn t publicly available (yet). ... In my context, this isn t necessarily
                        Message 11 of 19 , Nov 10, 2011
                          Marc, thanks for answering.

                          > > I'm now in possession of a shinny new URI-template library (implementing
                          > > http://tools.ietf.org/html/draft-gregorio-uritemplate-07) that I plan to
                          >
                          > care to share which one?

                          It's a Java library developed by a colleague. It isn't publicly available (yet).

                          > Below I assume you think about in-browser (js) code that will be
                          > expanding the templates, right?

                          In my context, this isn't necessarily in-browser code, or js code (more likely Java, C# or Perl code). But yes, I 'm talking about client side expansion of URI templates communicated by the server.

                          > Anyway, in terms of HTML such I think the lists of contexts could be
                          > provided by any repeating thing like ul/li, table/tr, p

                          Interesting. This resonates with the problem Eric wrote about: dynamically passing a declarative description of constraints on allowed values for expansion. In your example, you communicate a list of possible contexts for expansion. A context is a set of value for performing a given expansion. Do I understand correctly? If so, I'm not sure why you don't directly pass to the client a list of URI generated server-side by expanding the "templates" using the various contexts? I'm certainly missing some pieces here!

                          Philippe
                        • Philippe Mougin
                          Eric, Mike, Thanks for the insightful remarks. Dynamically communicating constraints on allowable values for expansions in a declarative way is sure an
                          Message 12 of 19 , Nov 10, 2011
                            Eric, Mike,

                            Thanks for the insightful remarks.

                            Dynamically communicating constraints on allowable values for expansions in a declarative way is sure an interesting problem.
                            For m2m interactions, one challenge is that the more stuff we try to communicate dynamically, the more client programs become difficult to implement. So we probably all have to find a good tradeoff depending on our particular contexts. For example, in my current project I have considered using XForms for my hypermedia controls, but it would have been too much complex for the teams in charge of implementing clients. I settled for HTML forms, which are less powerful but easier to use.
                            To get back to URI templates, now that I can provide tooling to some of the client developers, they could become a worthwhile addition.

                            Putting aside the problem of dynamically communicating allowable values for expansion (let's progress one step at a time), I like your idea of <a rel="circle" hreft="/circle/radius;{radius}" />. As the hreft attribute isn't standard XHTML we would have to get it from our own namespace. This would give: <a rel="circle" my:hreft="/circle/radius;{radius}" />

                            However it looks like it breaks the HTML 5 specification which states: "The target, rel, media, hreflang, and type attributes must be omitted if the href attribute is not present.

                            We could mint a new rel attribute in our own namespace, which would give: <a my:rel="circle" my:hreft="/circle/radius;{radius}" />

                            At that point however, I wonder if using <a> still makes much sense. What do you think?
                            An alternative is to create a new element. If we name it "link", an XHTML representation containing this element would look like:

                            <html xmlns="http://www.w3.org/1999/xhtml" xmlns:my="http://www.example.com/my">
                            <body>
                            <my:link rel="circle" hreft="/circle/radius;{radius}" />
                            </body>
                            </html>

                            What is your take on this? Can we do better?

                            Philippe

                            --- In rest-discuss@yahoogroups.com, Mike Kelly <mike@...> wrote:
                            >
                            > On Wed, Nov 9, 2011 at 7:40 PM, Eric J. Bowman <eric@...> wrote:
                            > >
                            > > Mike Kelly wrote:
                            > > >
                            > > > There's already an adequate solution to that problem - you can define
                            > > > the inputs up-front against the link relation in question.
                            > > >
                            > >
                            > > I don't see invalid markup as an adequate solution -- @href takes a
                            > > URI, not a template; section 1.4 of the URI-template draft states that
                            > > URI templates aren't URIs.  Instead of having to parse @href before
                            > > determining how to parse @href (is it a URI or a template), it makes
                            > > sense to follow the logic in the URI-template draft and provide new
                            > > attributes to match a new parsing model (or elements, in the case of
                            > > XForms elements which take URIs as content).
                            > >
                            > > >
                            > > > e.g. the link relation 'circle' has an href containing a URI template
                            > > > which accepts the variable 'radius'
                            > > >
                            > > > which tells you what you need to know to build an automated client
                            > > > which follows this link:
                            > > >
                            > > > <a rel="circle" href="/circle/radius;{radius}" />
                            > > >
                            > >
                            > > How?  Does @href take on a different syntax due to the definition of
                            > > rel='circle'?  Where is *that* in the media type definition for XHTML?
                            > >
                            >
                            > You're focusing on a side issue. Let's change it to this for now:
                            >
                            > <a rel="circle" hreft="/circle/radius;{radius}" />
                            >
                            > Is that (and the description of the rel circle) not an adequate
                            > solution to the "real problem" you mentioned before?
                            >
                            > Cheers,
                            > Mike
                            >
                          • Erik Wilde
                            hello philippe. ... indeed it is. have you considered dependencies in your scenario? one use case we have all of the time is the GET initial form; GET list of
                            Message 13 of 19 , Nov 10, 2011
                              hello philippe.

                              > Dynamically communicating constraints on allowable values for expansions in a declarative way is sure an interesting problem.

                              indeed it is. have you considered dependencies in your scenario? one use
                              case we have all of the time is the "GET initial form; GET list of
                              countries, wait for country to be filled out; GET list of states; wait
                              for state to be filled out; GET list of cities; pick city; PUT/POST
                              form" pattern, in all sorts and shapes. i am wondering whether there is
                              some consensus about how to deal with this as declaratively as possible,
                              or whether anybody is just happily scripting all of this.

                              cheers,

                              dret.

                              --
                              erik wilde | mailto:dret@... - tel:+1-510-2061079 |
                              | UC Berkeley - School of Information (ISchool) |
                              | http://dret.net/netdret http://twitter.com/dret |
                            • mike amundsen
                              Erik: in one recent case, a client decided to handle these UI list dependencies by sending all the data in the form and letting local scripts to the filtering
                              Message 14 of 19 , Nov 10, 2011
                                Erik:

                                in one recent case, a client decided to handle these UI list
                                dependencies by sending all the data in the form and letting local
                                scripts to the filtering w/o the need to call back to the server. in
                                this case the lists were quite static (product-related filters) and
                                relatively small (tens of items in each list, not hundreds). caching
                                makes composing and shipping this representation to the clients
                                relatively inexpensive (after the first delivery to a client).

                                mca
                                http://amundsen.com/blog/
                                http://twitter.com@mamund
                                http://mamund.com/foaf.rdf#me





                                On Thu, Nov 10, 2011 at 12:35, Erik Wilde <dret@...> wrote:
                                > hello philippe.
                                >
                                >> Dynamically communicating constraints on allowable values for expansions in a declarative way is sure an interesting problem.
                                >
                                > indeed it is. have you considered dependencies in your scenario? one use
                                > case we have all of the time is the "GET initial form; GET list of
                                > countries, wait for country to be filled out; GET list of states; wait
                                > for state to be filled out; GET list of cities; pick city; PUT/POST
                                > form" pattern, in all sorts and shapes. i am wondering whether there is
                                > some consensus about how to deal with this as declaratively as possible,
                                > or whether anybody is just happily scripting all of this.
                                >
                                > cheers,
                                >
                                > dret.
                                >
                                > --
                                > erik wilde | mailto:dret@...  -  tel:+1-510-2061079 |
                                >            | UC Berkeley  -  School of Information (ISchool) |
                                >            | http://dret.net/netdret http://twitter.com/dret |
                                >
                                >
                                > ------------------------------------
                                >
                                > Yahoo! Groups Links
                                >
                                >
                                >
                                >
                              • Erik Wilde
                                hello mike. ... yes, for small pick lists, including the allowable values is an option and is a good option to avoid additional requests. ... the problem is
                                Message 15 of 19 , Nov 10, 2011
                                  hello mike.

                                  > in one recent case, a client decided to handle these UI list
                                  > dependencies by sending all the data in the form and letting local
                                  > scripts to the filtering w/o the need to call back to the server. in
                                  > this case the lists were quite static (product-related filters) and
                                  > relatively small (tens of items in each list, not hundreds).

                                  yes, for small pick lists, including the allowable values is an option
                                  and is a good option to avoid additional requests.

                                  > caching
                                  > makes composing and shipping this representation to the clients
                                  > relatively inexpensive (after the first delivery to a client).

                                  the problem is that dependent lists can get huge; imagine the scenario i
                                  used which, when fully expanded, lists all cities in all countries
                                  world-wide. clearly, that's not something you want to ship to the
                                  client, so there needs to be some iterative process. you could probably
                                  say that this is very similar to faceted navigation, only that the
                                  process in this case is driven by form fields, and not by search-based
                                  interactions. we have tons of scenarios where we must have value-assist
                                  as a service, because these things also can be computed by server-side
                                  logic, so they don't even exist without input parameters provided by the
                                  client.

                                  cheers,

                                  dret.

                                  --
                                  erik wilde | mailto:dret@... - tel:+1-510-2061079 |
                                  | UC Berkeley - School of Information (ISchool) |
                                  | http://dret.net/netdret http://twitter.com/dret |
                                • Marc Portier
                                  ... ah ok, since you mentioned XHTML I just assumed browser-client and expanded further to assume javascript, sorry for that ... Well, that surely *is* an
                                  Message 16 of 19 , Nov 13, 2011
                                    On 10-11-11 15:40, Philippe Mougin wrote:
                                    > Marc, thanks for answering.
                                    >
                                    > > > I'm now in possession of a shinny new URI-template library
                                    > (implementing
                                    > > > http://tools.ietf.org/html/draft-gregorio-uritemplate-07) that I
                                    > plan to
                                    > >
                                    > > care to share which one?
                                    >
                                    > It's a Java library developed by a colleague. It isn't publicly
                                    > available (yet).
                                    >
                                    > > Below I assume you think about in-browser (js) code that will be
                                    > > expanding the templates, right?
                                    >
                                    > In my context, this isn't necessarily in-browser code, or js code (more
                                    > likely Java, C# or Perl code). But yes, I 'm talking about client side
                                    > expansion of URI templates communicated by the server.
                                    >

                                    ah ok, since you mentioned XHTML I just assumed browser-client and
                                    expanded further to assume javascript, sorry for that

                                    > > Anyway, in terms of HTML such I think the lists of contexts could be
                                    > > provided by any repeating thing like ul/li, table/tr, p
                                    >
                                    > Interesting. This resonates with the problem Eric wrote about:
                                    > dynamically passing a declarative description of constraints on allowed
                                    > values for expansion. In your example, you communicate a list of
                                    > possible contexts for expansion. A context is a set of value for
                                    > performing a given expansion. Do I understand correctly? If so, I'm not
                                    > sure why you don't directly pass to the client a list of URI generated
                                    > server-side by expanding the "templates" using the various contexts? I'm

                                    Well, that surely *is* an option as I mentioned myself, but if you go
                                    this path, then you don't need to provide the client with uri-templates
                                    nor contexts, and you don't need anything else then the xhtml we already
                                    have...

                                    So I just assumed you meant this, if not it seemed to make your question
                                    void?

                                    > certainly missing some pieces here!
                                    >

                                    Not sure, maybe I'm missing the pieces, but here is my line of thinking:
                                    if you think about sending uri-templates to the client, then I assume
                                    you want it doing the expansions, and thus, that client will need to
                                    have a way to access, derive, produce the contexts for that...

                                    So really, in my mind relating this issue to XHTML (as per your subject)
                                    really opens up two interesting issues:

                                    [1] a way to send the uri-templates (link/ref, or the suggested hreft,
                                    srct variants) ... or ...

                                    [2] and a way to send the contexts

                                    regards,
                                    -marc=

                                    > Philippe
                                    >
                                    >
                                  • Philippe Mougin
                                    ... Yes, I need client side expansion, as I want to use URI templates to dynamically communicate how to build certain URIs. However, my clients are
                                    Message 17 of 19 , Nov 15, 2011
                                      > > Interesting. This resonates with the problem Eric wrote about:
                                      > > dynamically passing a declarative description of constraints on allowed
                                      > > values for expansion. In your example, you communicate a list of
                                      > > possible contexts for expansion. A context is a set of value for
                                      > > performing a given expansion. Do I understand correctly? If so, I'm not
                                      > > sure why you don't directly pass to the client a list of URI generated
                                      > > server-side by expanding the "templates" using the various contexts? I'm
                                      >
                                      > Well, that surely *is* an option as I mentioned myself, but if you go
                                      > this path, then you don't need to provide the client with uri-templates
                                      > nor contexts, and you don't need anything else then the xhtml we already
                                      > have...
                                      > So I just assumed you meant this, if not it seemed to make your question
                                      > void?

                                      Yes, I need client side expansion, as I want to use URI templates to dynamically communicate how to build certain URIs. However, my clients are purpose-built programs whose developers will be given some informations out of band. For example, I might communicate http://example.com/stockquote/{symbol} dynamically, associated with a given rel value for finding it in a representation, but specify in my service documentation (i.e., out of band) that it must be expanded using a variable named "symbol" whose value must be the stock symbol of the company you want a stock quote for.

                                      So my main question is what you labeled as "question [1]": what is the best way to embed such an URI template in XHTML.

                                      One viable option is creating a specific "link" element with a rel and hreft attribute, which would give:

                                      <html xmlns="http://www.w3.org/1999/xhtml" xmlns:my="http://example.com/my">
                                      <body>
                                      <my:link rel="http://example.com/rels/stockquote" hreft="http://example.com/stockquote/{symbol}" />
                                      </body>
                                      </html>

                                      Another idea I have is to use the existing xrd's link element, which has support for URI templates (xrd is specified at http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.html).

                                      This would give:

                                      <html xmlns="http://www.w3.org/1999/xhtml" xmlns:xrd="http://docs.oasis-open.org/ns/xri/xrd-1.0">
                                      <body>
                                      <xrd:link rel="http://example.com/rels/stockquote" template="http://example.com/stockquote/{symbol}" />
                                      </body>
                                      </html>

                                      I'd be grateful for any feedback on these as well as other ideas on how to best use URI templates as hypermedia controls in XHTML.

                                      Philippe
                                    • mike amundsen
                                      PM: the choice between adding a custom LINK element to XHTML or one based on XRD is not too interesting; i suspect they
                                      Message 18 of 19 , Nov 15, 2011
                                        PM:

                                        <puts-on-his-client-developer-hat>
                                        the choice between adding a custom LINK element to XHTML or one based
                                        on XRD is not too interesting; i suspect they would both need
                                        essentially the same development effort in order to recognize, parse,
                                        and process in representations.
                                        </puts-on-his-client-developer-hat>

                                        <puts-on-media-type-designer-hat>
                                        when implementing these "templates" (whether via HTML FORM, URI
                                        Template, or some other method), i include the possible "fields" that
                                        would appear in a template as documentation. this is totally
                                        out-of-band data, of course. and that data must be "incorporated" by
                                        server and client devs in some way. it's basically a dictionary of
                                        possible data points that both client and server need to keep in mind
                                        as possible values passed in transitions (templates) or steady-states
                                        (response representations). what/how implementors handle this is up to
                                        each case.
                                        </puts-on-media-type-designer-hat>

                                        hopefully that helps.

                                        MCA

                                        mca
                                        http://amundsen.com/blog/
                                        http://twitter.com@mamund
                                        http://mamund.com/foaf.rdf#me





                                        On Tue, Nov 15, 2011 at 09:31, Philippe Mougin <pmougin@...> wrote:
                                        >
                                        >
                                        >
                                        >
                                        >
                                        >> > Interesting. This resonates with the problem Eric wrote about:
                                        >> > dynamically passing a declarative description of constraints on allowed
                                        >> > values for expansion. In your example, you communicate a list of
                                        >> > possible contexts for expansion. A context is a set of value for
                                        >> > performing a given expansion. Do I understand correctly? If so, I'm not
                                        >> > sure why you don't directly pass to the client a list of URI generated
                                        >> > server-side by expanding the "templates" using the various contexts? I'm
                                        >>
                                        >> Well, that surely *is* an option as I mentioned myself, but if you go
                                        >> this path, then you don't need to provide the client with uri-templates
                                        >> nor contexts, and you don't need anything else then the xhtml we already
                                        >> have...
                                        >> So I just assumed you meant this, if not it seemed to make your question
                                        >> void?
                                        >
                                        > Yes, I need client side expansion, as I want to use URI templates to dynamically communicate how to build certain URIs. However, my clients are purpose-built programs whose developers will be given some informations out of band. For example, I might communicate http://example.com/stockquote/{symbol} dynamically, associated with a given rel value for finding it in a representation, but specify in my service documentation (i.e., out of band) that it must be expanded using a variable named "symbol" whose value must be the stock symbol of the company you want a stock quote for.
                                        >
                                        > So my main question is what you labeled as "question [1]": what is the best way to embed such an URI template in XHTML.
                                        >
                                        > One viable option is  creating a specific "link" element with a rel and hreft attribute, which would give:
                                        >
                                        > <html xmlns="http://www.w3.org/1999/xhtml" xmlns:my="http://example.com/my">
                                        >    <body>
                                        >        <my:link rel="http://example.com/rels/stockquote" hreft="http://example.com/stockquote/{symbol}" />
                                        >    </body>
                                        > </html>
                                        >
                                        > Another idea I have is to use the existing xrd's link element, which has support for URI templates (xrd is specified at http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.html).
                                        >
                                        > This would give:
                                        >
                                        > <html xmlns="http://www.w3.org/1999/xhtml" xmlns:xrd="http://docs.oasis-open.org/ns/xri/xrd-1.0">
                                        >    <body>
                                        >        <xrd:link rel="http://example.com/rels/stockquote" template="http://example.com/stockquote/{symbol}" />
                                        >    </body>
                                        > </html>
                                        >
                                        > I'd be grateful for any feedback on these as well as other ideas on how to best use URI templates as hypermedia controls in XHTML.
                                        >
                                        > Philippe
                                        >
                                        >
                                        >
                                        >
                                        > ------------------------------------
                                        >
                                        > Yahoo! Groups Links
                                        >
                                        >
                                        >
                                        >
                                      • Eric J. Bowman
                                        ... Surely this information can be written down and linked to in-band? Hard-coded clients aren t such a bad thing if, at least, the shared understandings are
                                        Message 19 of 19 , Nov 15, 2011
                                          "Philippe Mougin" wrote:
                                          >
                                          > Yes, I need client side expansion, as I want to use URI templates to
                                          > dynamically communicate how to build certain URIs. However, my
                                          > clients are purpose-built programs whose developers will be given
                                          > some informations out of band.
                                          >

                                          Surely this information can be written down and linked to in-band?
                                          Hard-coded clients aren't such a bad thing if, at least, the shared
                                          understandings are linked to (as opposed to baked-in / out-of-band).

                                          >
                                          > So my main question is what you labeled as "question [1]": what is
                                          > the best way to embed such an URI template in XHTML.
                                          >

                                          OK, I think I see what you're after, this is rough but ought to make
                                          everybody happy (except that it's bad HTML5), and is what is meant by a
                                          self-documenting API...

                                          http://charger.bisonsystems.net/stooges.txt

                                          ...because the code is simpler than prosaic documentation, even though
                                          the URIs are hypothetical and the XSLT, nonexistent. Obviously, either
                                          XSLT or Javascript can be used to generate a UI from that information,
                                          with the option of output in XHTML (whole pages) or JSON (snippets).

                                          Using URI templates as an outright replacement for links and forms in
                                          XHTML, decouples both the choice of forms language and the method of
                                          URI generation. The resulting XHTML (relying on pre-HTML5 <object>
                                          syntax in more ways than one) is svelte, and reduces the need to look
                                          deeper into the code to figure out how to build URLs in a way that's
                                          uniform across approaches / coding-language choices.

                                          RDFa is used to declare that the in-scope (domain-specific) vocabulary
                                          represents nicknames of people, the terms and meanings of the out-of-
                                          scope (shared understanding) vocabulary are left to the externally-
                                          linked document. The link is what counts, but @valuetype gives us the
                                          semantics needed to do name-value expansion for a template passed in
                                          @data, a nice repurposing of obsolete code IMNSHO.

                                          No, you don't have to use the XSLT (or JS), or use the service in a
                                          browser, but that option not only makes it easier for others to learn
                                          your service (particularly if your markup is valid and accessible), it
                                          also provides the opportunity to delimit which options from the shared
                                          vocabulary aren't supported locally (graying out a list item); the
                                          benefit of XSLT/XForms over JS here is one of declarative code vs. code-
                                          on-demand (visibility).

                                          I basically just had my aha moment for URI templates in XHTML, as it
                                          moves UI design choices (like forms language) to another layer.
                                          Interesting!

                                          -Eric
                                        Your message has been successfully submitted and would be delivered to recipients shortly.