OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [dita] <include> element in base vocabulary for DITA 2.0

I am using <object> to represent a form. The XSL takes the various field characteristics from <param> elements inside the <object>. Here is an example:

<object type="form" props="post(submitproposal.php)">
<param type="text" name="name" props="size(30)" otherprops="Your full name"/>
<param type="text" name="email" props="size(30)" otherprops="E-mail address"/>
<param type="text" name="org" props="size(30)" otherprops="Organization"/>
<param type="listbox" name="type" props="size(20)" otherprops="Presentation,Workshop"/>
<param type="text" name="title" props="size(60)" otherprops="Session title"/>
<param type="textarea" name="abstract" props="size(5x60)" otherprops="Session abstract"/>
<param type="submit" name="submit" value="Submit"/>

Maybe this is a crazy approach, maybe not. I figured that the form is really like an object - which might be a movie in a player or any other widget that offers interactive options. Processing the input, IMHO, is not part of the definition in the DITA file and should not be. Just like formatting is - and should be - separate from the semantics of the DITA file.

My 2 cents. Eurocents, i.e. 2.21741 USD cents :-)


Op 6 augustus 2016 17:39:47 +02:00, schreef Chris Nitchie <chris.nitchie@oberontech.com>:

I’ve never considered using <xref> to describe form fields. When talking specifically about forms, I think of the source/destination of an input’s value as metadata on the input, not the primary nature of the input. For example:


<textfield [class=”+ topic/data input-d/input widget-d/textfield “ datatype=”text”] id=”firstName”>

  <required [class=”+ topic/data input-d/inputConfig widget-d/required ” name=”required” value=”true”]/>

  <minLength [class=”…” name=”minLength”] value=”3”/>

  <datapoint [class=”…” name=”datapoint” scope=”external”] keyref=”user/firstName”/>

  <!-- OR -->

  <datapoint href="">



All of which is to say that I don’t consider the hookup of form fields to their data sources to be quite the same use case as processing-time transclusion.


I’d be open to working on any proposals related to adding a ‘forms’ domain to DITA 2.0. I might even consider submitting such a proposal when the time comes.





From: <dita@lists.oasis-open.org> on behalf of Don Day <donday@donrday.com>
Date: Tuesday, August 2, 2016 at 10:58 AM
To: "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>
Subject: Re: [dita] <include> element in base vocabulary for DITA 2.0


During the discussion of this item in the 19 July 2016 TC meeting, I mentioned some experiences I had with transclusion behaviors. My use case was using DITA to represent a form front end to a database. Normally, we edit DITA documents directly. In this case, DITA markup represents form fields that get their content from a database--literally a transclusion aspect. I needed to represent a transclusion query, which is different than a conref query, so @conref was out as a way to model the query. I made peace with xref because @href represents the query semantic, while it still has a conref semantic in the processing role of getting a title as content.

Here are a few lines of a "document-as-form":

<dl id="xpdformdata" outputclass="asForm" spectitle="Add Event" class="- topic/dl ">
<dlentry class="- topic/dlentry ">
        <dt class="- topic/dt ">Event Name:</dt>
        <dd class="- topic/dd ">
               <xref type="head" href="" format="form" class="- topic/xref "/>
<dlentry class="- topic/dlentry ">
        <dt class="- topic/dt ">Event Type:</dt>
        <dd class="- topic/dd ">
               <xref type="select" href="" format="form" class="- topic/xref ">
<data value="conference" class="- topic/data ">Conference</data>
               <data value="webinar" class="- topic/data ">Webinar</data>
                <data value="meeting" class="- topic/data ">Meeting</data>
                <data value="training" class="- topic/data ">Training Class</data>
                <data value="other" class="- topic/data ">Other</data>

And notes FWIW from my transform file:

<!-- use xref to represent an input field in a form: xref type="input" href="" format="form"-->
<!-- "Non-DITA targets use standard URL syntax."
    SQL equivalence:
        table = filename
        row = repeating container element (rowType semantic name, e.g. 'users')
        field names = element names
    Our pattern: {$filename}:{$rowType}:{$value}
    In use:     href=""
    get $filename as "dbLoCS", $rowType as "TitlePage", $value as "title"
    XSLT:     <xsl:value-of select="document(concat($filename,'.xml'))/tables/$rowType/*[name()=$value]"/>

CSS sample: render the queried title LIKE a title
input.title {width:100%; font-weight:bold; font-size:1.5em;}

And as rendered (with no data in this case, hence "CREATE" role in database):

From a webinar slide I gave about this process:

Definition list "specialized" to represent forms

  • DITA definition list represents regular parts of an HTML form.
  • A fully specialized structure would be enforced by editors.
  • The displayed document is the live form, interfaces to SQL table.
  • Demo: Add Event: document as form (launch here)
  • Key takeaways:
    • DITA behaviors apply: instance/reference fields by conref, conditional views, etc..
    • Document as schema defines the data structure, database holds the data.
    • Rendered form can be copied and reused directly in Web applications; "form generation" with style.

The net is that I was able to make peace with xref as a tranclusion element. I used it to transclude SQL field data, but the semantic justifies pulling in any other non-DITA (or DITA) rendition type as well, as long as the application has a standard way of recognizing that rendition role and applying it. This is why I mentioned "viewport" as a way of describing what is happening in this case.

Hoping this helps the discussion.



On 6/25/2016 8:51 AM, Chris Nitchie wrote:

The <coderef> attribute is a transclusion element – it loads the referenced file and places its contents as CDATA at the location of the referencing element. However, <coderef> is a specialization of <xref>, which is not a transclusion element. That is, the specialization-based fallback behavior for <coderef> is fundamentally incompatible with the expected processing. The same is true for svgref and mathmlref. The only way for people other than the TC to create similar transclusion elements via specialization is to specialize from one of those, or customize their processors to do the right thing with their element.


For DITA 2.0, I suggest we add an <include> element to the base vocabulary to act as a base for specialization for these kinds of elements.


<include href="" format=”format” parse=”xml|text”>

  <fallback>Fallback content here</fallback>



This is roughly modeled on xinclude, but without the need for the namespace, and with @class so it can be used as a base for specialization. (And, of course, @keyref-capable.)





Don R. Day
Founding Chair, OASIS DITA Technical Committee (current version: DITA 1.3)
LinkedIn: donrday   Twitter: @donrday
About.me: Don R. DaySkype: don.r.day

"Where is the wisdom we have lost in knowledge?
Where is the knowledge we have lost in information?"
--T.S. Eliot


Virus-free. www.avast.com


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]