Talk:Template forms

Semantic Wiki

It will probably be pointed out fairly quickly that semantic wiki could be used to accomplish a similar thing. Lets quickly outline the benefits and drawbacks.

Template properties will be difficult to Share

Each of these XML Template_forms wikipages will be written without any of the properties having shared semantic meaning?

To illustrate the problem:

• Looking at the the license field example we see its properties are raw coded into the XML.
  • Say you want to pull the "license" list from a category:
    • You end up applying a series of properties/hacks to the license field.
      • • populated from category:licenses,
        • has human help description English, Spanish, French
        • is a link to a license url, has thumbnails etc.
    • NOW... you want to reuse that license filed for the video page description that puts the license field in a slightly different place.
      • BUT its all hard-coded into the template xml of the "image template" page...
  • SO... what people will end up doing is transclude {{Template:license_filed/xml}} calls inside the xml Template_Form that transclude the license_filed/xml template page.
• We can imagine this happening a bunch... you end up recreating semantic mediaWiki property pages except using lots of template calls instead of structured data per property page... or if you don't allow transclution on xml pages you get lots of copy and pasting and maintenance issues and excessively general templates.

• Of course you still need to tie the semantic property to the template property with some sort of markup.. but I think that would be more straight forward. ie reading the property part of [[Property::{{TEMPLATE_VALUE]] in the template page. (or transitioning to a more xml like template description language which perhaps Template_forms could be compatible with?

Template forms won't significantly improve structured data maintenance situation

• The above does not touch on how the data could be stored, displayed, or queried which are addressed in the semantic wiki based approach.
• having the templates have xml properties is nice but there will be no system to query them in aggregate in real-time. Instead we will have only slightly better approach to templates as fields are ad-hock tagged with data types without consistency or shared ontology across template types.
• Imagine you want to update some property or see pages that use a given property, or update a set of properties across different language wikis.
  • We are still left with bots doing A LOT of edits which is at greater cost than just storing the data in some structured fashion to begin with.
• We essentially expecting wiki-users across language to manually read other template properties on other wikis and copy and paste the values in ... instead of setting up a system that treats structured data as such?

Long Term Planning

• Semantic mediaWIki is a "hack" of structured data ontop of mediaWiki conventions and has many problems but it is better than lots of little less general solutions that address only parts of the same problem set.
• We don't have to use all of semantic MediaWIki at once. For example if there is just resources for the template property problem at the moment then just use it for template properties?
  • This way we have a road map towards increasingly interesting feature set, rather than a road map towards increasingly hackish solutions.

Questions for Using Semantic Wiki

• Is it scalable? Has anyone run any tests? Has anyone outputted all of DBpedia to wiki page nodes with semantic properties and see how it performs?
• Is it too much extra complexity for any given task that the foundation technical staff can take on at any given time?
• Can it really be modularized and feature striped be useful for a particular context without exposing the complexity?

XML format could be better

The XML format proposed seems to make it very difficult to re-use code because of the over-qualification of tag names and feature-limiting use of attributes.

To the first point, elements like ParameterValueLabel are redundant. The path to that tag is "Parameter/ParameterValue/ParameterValueLabel" where the ParameterValueLabel element is one of possibly many other sibling ParameterValueLabel elements. Aside from my own proposal's choice of case and wording, this should at minimum be "Parameter/Value/Label". Furthermore, sticking to existing metaphors and language used in related formats, such as HTML helps allot with readability by way of familiarity. I'm proposing a structure where such path would be "param/option/label" where label is an element that encapsulates all messages so it could be handled on it's own in a generic way (discussed more below).

To the latter point, attributes are best used for classifying or supplementing the information inside the tag (the "contents" or "text" of the tag). Take a look at the syntax for the HTML button tag which uses the contents of the tag to define the contents of the button (makes sense to me) in comparison to the input element which uses a value attribute to define the contents of the button. What happens when we want to do something interesting in the contents of the button? Well if it's an input tag, too bad. But the button tag is ready for anything.

The syntax for the input element seems similar to the example that has been proposed here.

<Parameter name="author">
  <ParameterDescription language="en" value="Author" help="The creator of ..." />
  <ParameterDescription language="de" value="Autor" />
  <ParameterDescription language="ja" help="この画像のク..." />
</Parameter>

What if we want to do something interesting with the "value" of the description? Like the input tag, we are out of luck - if the primary content of the tag is defined by the contents however, we would be free to add more functionality to things in the future.

Also, what happens when we need to get the message of the description in a certain language, or fallback on let's say the first one defined?

// $param is assumed to be a selection of a <Parameter> element
var msg = $param.find( 'ParameterDescription[language=ja][value],ParameterDescription[language][value]:first' ).eq( 0 ).attr( 'value' );

First off, the code used to process the XML is obviously not going to be reusable. It's also quite verbose which makes it more difficult to read.

I am proposing a more generic format, which will be easier to work with. Using a more generic format also allows us to make tags that define messages easier for translators to interact with - both in adding new ones (the tags are simpler) and identifying which ones need adding (the tags are logically organized by purpose and language).

<param name="author" type="text" group="main">
  <label>
    <msg lang="en">Author</msg>
    <msg lang="de">Autor</msg>
  </label>
  <help>
    <msg lang="en">The creator of ...</msg>
    <msg lang="ja">この画像のク...</msg>
  </help>
</param>

Selecting the the message in Japanese, or the first one defined as a fallback now looks like this.

// $label is assumed to be a selection of a <label> element
var msg = $label.find( 'msg[lang=en],msg:first' ).eq( 0 ).text();

This bit of JavaScript is very re-usable, in fact it could be used on every single instance of multilingual message definitions. It's also very brief and easy to read.

Here's an example I've written up based on the one already proposed, but I included a few translations, which may be wacky since I just used Google translation tools to do them.

<template>
  <groups>
    <group name="main">
      <label>
        <msg lang="en">Details</msg>
        <msg lang="de">Beiwerk</msg>
        <msg lang="ja">詳細</msg>
      </label>
    </group>
  </groups>
  <params>
    <param name="author" type="text" group="main">
      <label>
        <msg lang="en">Author</msg>
        <msg lang="de">Autor</msg>
        <msg lang="ja">著者<msg>
      </label>
      <help>
        <msg lang="en">The creator of this image; preferably a link to a user page</msg>
        <msg lang="de">Der Schöpfer dieses Bildes, vorzugsweise einen Link auf eine Benutzerseite</msg>
        <msg lang="ja">この画像のクリエイター、ユーザーのページにできればリンク</msg>
      </help>
    </param>
    <param name="license" type="option" group="main">
      <label>
        <msg lang="en">License</msg>
        <msg lang="de">Lizenz</msg>
        <msg lang="ja">ライセンス</msg>
      </label>
      <help>
        <msg lang="en">The license under which this image will be published</msg>
        <msg lang="en">Die Lizenz, unter der das Bild veröffentlicht wird</msg>
        <msg lang="ja">これで、この画像がパブリッシュされるライセンス</msg>
      </help>
      <options>
        <option value="CC-by">
          <msg lang="en">Creative Commons Attribution</msg>
          <!-- Other languages would just fallback to the first/only one defined  -->
        </option>
        <option value="CC-by-sa" />
        <!-- No msg tag could result in the label being the value -->
      </options>
    </param>
  </params>
</template>

--Trevor Parscal 21:57, 23 September 2009 (UTC)

I like... the one thing I'm not sure about is moving the <group>s to another section that way. Going ahead and nesting the params inside the groups makes me feel warm and fuzzy in general, and avoids duplicating the group names on all the parameters. --Brion VIBBER 22:04, 23 September 2009 (UTC)

The idea with groups here is to keep the messages for the group names in the same place, and make it so a group was optional rather than required - all param elements without a group attribute are considered to be in the default/nameless group. This especially makes sense when grouping is not needed (templates with only a few parameters). But I am flexible on this, and can see positives to nesting parameters in groups beyond warm and fuzzy feelings :) While nesting parameters in groups may make translation a little harder, it would probably be a little more straight-forward to build a form from, nesting parameters in groups would present the added benefit of allowing group elements to contain group elements (multi-level grouping, which my implementation cannot do). You could also achieve the optional grouping by allowing param elements directly in the template element - in this way groups become analogous to HTML fieldsets. I do wonder though, in the case of nesting parameters in groups, how would the labels for each group be defined? would there be a group/label element (with group/label/msg child elements) and a group/params element (with group/params/param child elements)? --Trevor Parscal 22:30, 23 September 2009 (UTC)

I'd probably treat <group>s kind of like <fieldset>s here; a <param> can be in a <group> but doesn't need to be. Speaking of which, we should be explicit whether ordering translates directly to order in output. --Brion VIBBER 23:01, 23 September 2009 (UTC)

The format I proposed (not nesting params in groups) seems more focused on parameter order in a template call, whereas the nesting of params in groups seems to be more focused on parameter order in a form. It seems like you could really go either way (XML node order == template call order | XML node order == UI presentation order). One thing to consider is that using attributes with numeric indexes to define order is usually an awkward and error prone method. Assuming we use nested params in groups and declare the order of params to be for the sake of the UI and not necessarily the output, having an extra section of XML like...

<output>
  <param name="author" />
  <param name="license" />
</output>

...would probably be more maintainable - and in it's absence the order of the XML nodes (for the purpose of the UI) would be used as a fallback. Trevor Parscal 23:36, 23 September 2009 (UTC)

Yes, I thought of the <group> tag (which originated in the German Wikipedia) as basically a <fieldset>, which could in fact correspond to an actual <fieldset> in the form (probably not, but who knows). And my thought was that the order in the XML would dictate the order in the form. Trevor - your suggestions make sense, but I have a question: what did you mean by "What if we want to do something interesting with the "value" of the description?"? Yaron Koren 23:21, 23 September 2009 (UTC)

I mean that just because right now you think there will only be plain un-formatted text for field names and help, this is very likely not always going to be the case - unless of course you lock us into that by using an attribute to define them instead of the contents of a tag. This is especially going to be important with help which is very likely to contain formatting, and if wikitext formatting is used, then where is it going to be parsed? On the server and then sent to the client in HTML? Even if that's true, XML tags are used all the time in wikitext - so what then? Trevor Parscal 23:36, 23 September 2009 (UTC)

Ah, I get it, that makes sense. Yaron Koren 23:41, 23 September 2009 (UTC)

This conversation is getting a little disjointed (understandable, because there are a lot of issues) but - to get to the issue of parameter order, I don't know if there's a need to have their order in the template call ever be different from their order in the form. For what it's worth, in Semantic Forms the order is always the same, and no one's complained about it yet. Yaron Koren 23:45, 23 September 2009 (UTC)

Making my idea of falling back to the template call order being the same as the UI order by default make all the more sense, but in cases where we may find that to be unsatisfactory, adding an output element would solve the problem elegantly. Trevor Parscal 23:52, 23 September 2009 (UTC)

Mock-up?

>additionally, by default every template call would show up on the edit page as "minimized" in some way; perhaps replaced by a button, which when clicked allowed users to either edit the call with a form or edit the source directly.

Just wondering if someone could do a mock-up of this. I'm finding it hard to picture - do you really mean embedding buttons within the edit control? Or would you have an edit control, then a button, then another edit control...etc? That would work ok for big templates but would be onerous for little ones like en's "th" or something. Stevage 23:24, 23 September 2009 (UTC)

By "button", I was really imagining just some sort of rectangle, which is partly inspired by how Wikia does it. See here for an example of that - the gray "Stub" rectangle represents a call to the "Stub" template, and clicking on it is supposed to let you edit the template (it looks like it doesn't actually work unless you're logged in, though). Yaron Koren 23:49, 23 September 2009 (UTC)

For the syntax-highlighted editor, we are planning to make the template call a collapsible block of text which can be edited by hand or with a graphical user interface. We are intending on placing a (perhaps preview of the rendered template/at minimum a button) in the place of the template call when viewing in a WYSIWYG mode (which is in the perhaps far future depending on manpower available to us) In the case of the "th" template, the box/button being inline will make allot of sense visually in both editing modes. In the case of fragmented templates which are seen in table generation among other things, the current implementation is scary and those templates should be modified to conform to a more manageable form. The concept of this more "manageable" form is that a template that is broken up into parts for whatever reason should have a single wrapping template. For instance

{{thing
|{{head}}
|{{body}}
|{{foot}}
}}

rather than

{{thing-head}}
{{thing-body}}
{{thing-foot}}

* fixed the tripple brackets to be double - sorry about that

Trevor Parscal 23:50, 23 September 2009 (UTC)

Really, the first one is preferable? I thought one of the goals was to avoid template calls within template calls. Yaron Koren 23:52, 23 September 2009 (UTC)

Yes, at lunch I felt that way, by the end of the conversation with the rest of the tech team I not feel that template calls as parameter are much better than single rendered elements (like a table or infobox) being created by multiple consecutive templates. Trevor Parscal 00:03, 24 September 2009 (UTC)

Consecutive templates are necessary when you need free text which can include | and = (supposing the triple braces in the example were a typo - otherwise I don't understand it). Many table templates would be unnecessary if there would be a better table format such as | if="condition" | ... instead of {{#if:condition|{{{!}}} ...}} - much of the ugliness comes from the need for conditional rows and cells. --Tgr 12:02, 24 September 2009 (UTC)

User's perspective

I'm not sure that the way it is done on dewiki should be kept (of course, it's probably the best that could be done without deeper modifications of MediaWiki). I see several problems:

1) If template text remains in the edit box as is the case on dewiki now, we have the same problem: an editor faced with incomprehensible wall of text and markup.

2) If the template text doesn't remain in the edit box, by default every template call would show up on the edit page as "minimized" in some way. But in which way?

2a) It could be shown as some placeholder text. This would lead to editors often deleting the placeholder text accidentally.

2b) perhaps replaced by a button, which when clicked allowed users to either edit the call with a form or edit the source directly: this requires a rich edit box that we don't (and won't?) have.

I'm not sure what would be the solution for this. Perhaps, the same way it is possible to separately edit a section, it could be possible to separately edit a template call or a table. Then they wouldn't appear in edit box at all, yet it would still be possible to edit them (both as source or with an editor). Nikola Smolenski 07:42, 24 September 2009 (UTC)

It would require an edit box that basically just did some syntax highlighting; I don't know if it would qualify as "rich". I updated the page to explain that part and provide some links; does it make sense now? Yaron Koren 20:34, 24 September 2009 (UTC)

@ 2a) Possibly deleting the placeholder text should be inhibited in some way. E.g. you must open it first, then make it empty, than save the empty thing, only then it is gone. --Purodha 00:16, 10 November 2009 (UTC)

Template groups

It would be nice to have template groups so that you can switch from one template to the other while keeping the parameters (think cite_* and similar template families). --Tgr 12:51, 24 September 2009 (UTC)

Another proposal

Based on my research, our discussion / white-boarding sessions and some common sense.

• XML element names ARE case-sensitive, epsecially in that the closing tag must be the same as the opening tag. In some XML formats like HTML tags can be any case as long as the closing tag matches - but it's essentially just converted to lowercase internally. To avoid typing mistakes and to be more consistent with formats like XHTML, SVG and other existing uses of XML within wiki-text, I propose we stick to all lowercase. Abbreviations are preferred over complete words ("msg" not "message"), and if multiple-words absolutely must be used, hyphens are are preferred over merging words together ("element-name" not "elementname").
• 3rd party tools can add data tags to the template, group or param tags.
• Ordering and grouping of the param elements in the XML is representative of how the params should be presented in a form or table. Template call order is either unchanged (if editing an existing call) or generated by placing parameters with non-numeric ids in alphabetical order, and then inserting parameters with numeric ids at the index of their ID number.

This source includes an internal DTD for completeness. You can validate this source at Validome.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE template [
<!ELEMENT template (description?,params?,app*)>
<!ELEMENT params (param|group)*>
<!ELEMENT param (label?,description?,options?,type?,app*)>
<!ATTLIST param id ID #REQUIRED>
<!ELEMENT group (label?,description?,param*,app*)>
<!ELEMENT label (#PCDATA|msg)*>
<!ELEMENT description (#PCDATA|msg)*>
<!ELEMENT options (option*)>
<!ELEMENT option (#PCDATA|msg)*>
<!ELEMENT type (field*)>
<!ATTLIST type name CDATA #REQUIRED>
<!ELEMENT field (#PCDATA)>
<!ATTLIST field name CDATA #REQUIRED>
<!ELEMENT msg (#PCDATA)>
<!ATTLIST msg lang CDATA #REQUIRED>
<!ELEMENT app (field*)>
<!ATTLIST app name CDATA #REQUIRED>
]>
<template>
  <!-- Optional general helpful information -->
  <description>General template help text</description>
  <params>
    <!-- List of params in the order they should used in a template call -->
    <param id="foo">
      <!-- Either text or list of messages - in this example the former -->
      <label>Foo</label>
      <!-- Either text or list of messages - in this example the latter -->
      <description>
        <msg lang="en">Details and examples for foo param</msg>
        <msg lang="de">Details und Beispiele für die foo param</msg>
      </description>
      <!-- Optional set of boilerplate values -->
      <options>
        <!-- Either text or list of messages - in this example the former -->
        <option>Example 1</option>
        <!-- Either text or list of messages - in this example the latter -->
        <option>
          <msg lang="en">Example 2</msg>
          <msg lang="de">Beispiel 2</msg>
        </option>
      </options>
      <!-- Optional info specific to this type - Multiple types are ok! -->
      <type name="date">
      	<!-- Sets of fields with names and values related to the type -->
      	<field name="format">YY-MM-DD HH:MM:SS"</field>
      </type>
    </param>
    <!-- Optional grouping of parameters -->
    <group>
      <!-- Either text or list of messages - in this example the former -->
      <label>Group name</label>
      <!-- Either text or list of messages - in this example the former -->
      <description>Helpful text about what the group is</description>
      <param id="bar">
        <label>Bar</label>
        <!-- 3rd party application specific data for this parameter -->
        <app name="foo">
          <field name="fooz">abc</field>
          <field name="barz">xyz</field>
        </app>
      </param>
      <param id="baz">
        <label>Baz</label>
      </param>
      <!-- 3rd party application specific data for this group -->
      <app name="foo">
        <field name="fooz">abc</field>
        <field name="barz">xyz</field>
      </app>
    </group>
  </params>
  <!-- 3rd party application specific data for entire template -->
  <app name="foo">
    <field name="fooz">abc</field>
    <field name="barz">xyz</field>
  </app>
</template>

--Trevor Parscal 19:28, 27 October 2009 (UTC)

Enlarge the vision

I am not programmer so I don't know if my idea is feasible or interesting. But if we want to offer a nice edit environment for people with no idea of programm language we have to integrate one interface between the wiki code and the user. How ? By parsing the wikicode and by displaying data in several windows. Magnus Manske did already a JavaScript function splitting a wikicode into different frames (see en:User:Magnus_Manske/less_edit_clutter.js). But we can go a step further and imagine to create an environment like gimp: in gimp toolboxes are available in different windows. So we can do the same: one window for every template, one window for the references, one for the main text, one for interwiki links, one for catagories. We will need one window listing all others windows and allowing to close or open them. Then we can open what we want to do the edition. Snipre 16:49, 9 April 2010 (UTC)