Wikipedia talk:TemplateData/Tutorial: Difference between revisions

Revision as of 16:41, 25 July 2013

Latest revision as of 23:18, 3 September 2014

(9 intermediate revisions by 5 users not shown)

Line 1:

{{Merge#REDIRECT to|[[Wikipedia talk:VisualEditor/TemplateData}}]]

If there is a discrete set of valid values for a parameter, e.g. collapse="yes"/"no", where do we tell the user which choices they've got? The "string" doesn't give them many pointers. --[[User:99of9|99of9]] ([[User talk:99of9|talk]]) 21:58, 28 June 2013 (UTC)

:The description, ideally :). [[User:Okeyes (WMF)|Okeyes (WMF)]] ([[User talk:Okeyes (WMF)|talk]]) 22:29, 28 June 2013 (UTC)

== "default" tag ==

I discovered that there is an additional tag, "<code>default</code>", that shows the default value for the template parameter. Example:

<pre>

<templatedata>

{

"description": "Description of the template",

"params": {

"1": {

"label": "Label of the parameter",

"description": "Description of the parameter",

"type": "string",

"required": true,

"default": "Default text of this parameter"

}

}

}

</templatedata>

</pre>

It is not mentioned in this tutorial, but it is listed in the TemplateData table that is produced. Are we supposed to be using it yet? '''[[User:The Anonymouse|The&nbsp;Anonymouse]]'''&nbsp;([[User talk:The Anonymouse|talk]]) 13:58, 29 June 2013 (UTC)

:Yeah, using it is fine - it's just not necessary, so I tried to strip the tutorial down to "things that are required", basically :). [[User:Okeyes (WMF)|Okeyes (WMF)]] ([[User talk:Okeyes (WMF)|talk]]) 15:08, 29 June 2013 (UTC)

::OK, thanks! '''[[User:The Anonymouse|The&nbsp;Anonymouse]]'''&nbsp;([[User talk:The Anonymouse|talk]]) 04:32, 30 June 2013 (UTC)

== More useful debugging output needed ==

{{tracked|50511}}

This system is really not usable without better debugging. I just spent over an hour creating 200 lines of TemplateData for [[Template:Infobox disease]], and when I try to save it, all I get is "JSON syntax error". I'm not going to use this system until it does a better job of pinpointing errors, or at least giving some clue about the type of error. (If anybody is interested in trying to spot the syntax error, I saved my work as a comment in [[Template:Infobox disease/doc]].) [[User:Looie496|Looie496]] ([[User talk:Looie496|talk]]) 16:27, 1 July 2013 (UTC)

:I agree we need better debugging commentary; actually, I'm unable to find a bug with that. {{Ping|Adavidb}}? [[User:Okeyes (WMF)|Okeyes (WMF)]] ([[User talk:Okeyes (WMF)|talk]]) 17:14, 1 July 2013 (UTC)

::There was a double-quote symbol missing from the end of the "label" entry for the "eMedicineSubj" parameter. Such syntax errors are very difficult to catch with visual review alone. I commented out various parts of the code to narrow down where the error was. The corrected version remains commented, for any additional changes before activation. —[[User:Adavidb|ADavidB]] 18:05, 1 July 2013 (UTC)

:::Thanks. I've uncommented it and saved it -- appears to work. I still think I'm going to wait until there are more informative error messages before making further use of this system. Regards, [[User:Looie496|Looie496]] ([[User talk:Looie496|talk]]) 18:26, 1 July 2013 (UTC)

::::Seems reasonable; I've added a bug for it. [[User:Okeyes (WMF)|Okeyes (WMF)]] ([[User talk:Okeyes (WMF)|talk]]) 18:42, 1 July 2013 (UTC)

== Should be hidden when empty, and always link to documentation ==

I just discovered the existence of this after an IP editor added it to [[Template:Colon/doc]]. I have two observations: firstly, the displayed output needs to link to the TemplateData documentation (perhaps link "Template parameters"), otherwise it's virtually inexplicable - I had to perform a help namespace search to find it. Secondly, if empty it should either be hidden or a message along the lines of "this template does not take any parameters" should be shown. At present it just produces a clumsy-looking empty table, as in the example above.

This isn't meant to be negatively critical of the implementation, I know it's very early days yet. — [[User:Scott Martin|'''<span style="color:#000">Scott</span>''']] <span style="color:#900">•</span> [[User talk:Scott Martin|''<span style="color:#000">talk</span>'']] 12:07, 2 July 2013 (UTC)

::Good points, both :). I'm not sure how we'd handle the first one - what do we do with localisation, for example? - but we can look into it. [[User:Okeyes (WMF)|Okeyes (WMF)]] ([[User talk:Okeyes (WMF)|talk]]) 12:58, 2 July 2013 (UTC)

== Placement ==

The section [[Wikipedia:VisualEditor/TemplateData tutorial#TemplateData]] implies that it doesn't matter if {{tag|TemplateData}} is added to the /doc page or to the main template page. I would suggest that the {{tag|TemplateData}} should be placed on the /doc page wherever possible, since if it's put on the template, it'll add pages to the [[Help:Job queue|job queue]] unnecessarily (see [[bugzilla:50372]] and [[WP:VPT#TemplateData: Is it working?]]). --[[User:Redrose64|<span style="color:#a80000; background:#ffeeee; text-decoration:inherit">Red</span>rose64]] ([[User talk:Redrose64|talk]]) 16:25, 3 July 2013 (UTC)

:Fair point; I'll make sure it's tweaked when we update the documentation (being written now). [[User:Okeyes (WMF)|Okeyes (WMF)]] ([[User talk:Okeyes (WMF)|talk]]) 15:09, 5 July 2013 (UTC)

== Parameters in example ==

The order of parameters in the "Str left"-example is reversed. In Templatedata (and the step by step instruction) "string" should come first, then "count". They are unnamed parameters, the current order won't work or would return wrong results. [[User:GermanJoe|GermanJoe]] ([[User talk:GermanJoe|talk]]) 14:43, 5 July 2013 (UTC)

:Oh, darn :(. We're actually about to update the tutorial :). [[User:Okeyes (WMF)|Okeyes (WMF)]] ([[User talk:Okeyes (WMF)|talk]]) 15:09, 5 July 2013 (UTC)

::Fixed the template [[Template:Str_left]] for now ;). [[User:GermanJoe|GermanJoe]] ([[User talk:GermanJoe|talk]]) 07:45, 9 July 2013 (UTC)

:::Thanks! :D. I need to start making a list of names (in a "free cookies" way, not in a PRISM way) [[User:Okeyes (WMF)|Okeyes (WMF)]] ([[User talk:Okeyes (WMF)|talk]]) 08:13, 9 July 2013 (UTC)

== Editor for TemplateData ? ==

Hi, is there any editor tool for TemplateData on enwiki ? On frwiki, a user made a [[:fr:Utilisateur:Ltrlg/scripts/TemplateDataEditor.js|script]] which allows creating/updating the {{tag|templatedata}} visually and very easily. Anyone willing to make the same for enwiki ? --[[User:NicoV|NicoV]] ^{([[:fr:Discussion Utilisateur:NicoV|Talk on frwiki]])} 08:42, 16 July 2013 (UTC)

:Ooh. I'd love if someone could take and translate that. [[User:Okeyes (WMF)|Okeyes (WMF)]] ([[User talk:Okeyes (WMF)|talk]]) 13:35, 16 July 2013 (UTC)

::I posted a request on [[Wikipedia:WikiProject User scripts/Requests]]. --[[User:NicoV|NicoV]] ^{([[:fr:Discussion Utilisateur:NicoV|Talk on frwiki]])} 16:39, 16 July 2013 (UTC)

:::Editor available at [[User:NicoV/TemplateDataEditor.js]]. --[[User:NicoV|NicoV]] ^{([[:fr:Discussion Utilisateur:NicoV|Talk on frwiki]])} 23:00, 19 July 2013 (UTC)

::::Yes, sounds really useful, but how do we use it? Could you give a non-techie "How to do it" guide, please? Thanks. [[User:PamD|<font color="green">'''''Pam'''''</font>]][[User talk:PamD|<font color="brown">'''''D'''''</font>]] 23:08, 19 July 2013 (UTC)

{{unindent}}Sure :

* Edit [[Special:MyPage/skin.js]].

* Add a line with the following text <code>importScript('User:NicoV/TemplateDataEditor.js');</code>

* Save the page

* Read the note at the top of the page explaining how to bypass your browser cache, and follow its instructions.

Then, when you edit a template (or rather its documentation page) :

[[File:TemplateDataEditor.png|thumb|upright=2|Editor for [[:en:Wikipedia:VisualEditor/TemplateData|TemplateData]]]]

* You should see a "TemplateData" link on the left, in the "Toolbox" section

* Check if the template page already contains a {{tag|templatedata}} tag

* If not, add an empty one <code>&lt;templatedata /&gt;</code>

* Click on the "TemplateData" link

* You should see a big window that's quite easy to use

--[[User:NicoV|NicoV]] ^{([[:fr:Discussion Utilisateur:NicoV|Talk on frwiki]])} 23:16, 19 July 2013 (UTC)

:Thanks - too late at night to try anything now but I look forward to having a go at it tomorrow. [[User:PamD|<font color="green">'''''Pam'''''</font>]][[User talk:PamD|<font color="brown">'''''D'''''</font>]] 23:30, 19 July 2013 (UTC)

::Hope you'll enjoy it :-) More explanations on how to install/use at [[User:NicoV/TemplateDataEditor]]. --[[User:NicoV|NicoV]] ^{([[:fr:Discussion Utilisateur:NicoV|Talk on frwiki]])} 04:57, 20 July 2013 (UTC)

:::I've amended the first instruction, since it's not necessary to work out whether you should put it in [[Special:MyPage/vector.js]] or somewhere else if you use a different skin. The link [[Special:MyPage/skin.js]] automatically goes to the relevant .js file for your current skin.

:::But, it can be simpler. Does it work in all current skins (Cologne Blue, Modern, Monobook, Vector)? If so, the place to put it would be [[Special:MyPage/common.js]]; then, if you change skins, the script does not need to be reinstalled for the new skin. --[[User:Redrose64|<span style="color:#a80000; background:#ffeeee; text-decoration:inherit">Red</span>rose64]] ([[User talk:Redrose64|talk]]) 07:15, 20 July 2013 (UTC)

::::Thanks, I didn't know about skin.js. I do'nt know if it works for all skins, but it seems quite simple, so probably. In [[User:NicoV/TemplateDataEditor]], I suggested to use common.js. --[[User:NicoV|NicoV]] ^{([[:fr:Discussion Utilisateur:NicoV|Talk on frwiki]])} 07:20, 20 July 2013 (UTC)

Should it work within userspace aswell? Tried in my user sandbox with the skeleton TemplateData (just for testing), but toolbox option would not appear. Editing in template space under Vector.js looks fine though - great addition, thank you. [[User:GermanJoe|GermanJoe]] ([[User talk:GermanJoe|talk]]) 13:20, 22 July 2013 (UTC)

:Currently, it works only in template namespace, but it could be added also in user namespace. --[[User:NicoV|NicoV]] ^{([[:fr:Discussion Utilisateur:NicoV|Talk on frwiki]])} 14:55, 22 July 2013 (UTC)

::Modified to work also in userspace. --[[User:NicoV|NicoV]] ^{([[:fr:Discussion Utilisateur:NicoV|Talk on frwiki]])} 15:12, 22 July 2013 (UTC)

:::Thanks for the quick change - works for me :). [[User:GermanJoe|GermanJoe]] ([[User talk:GermanJoe|talk]]) 18:06, 22 July 2013 (UTC)

Ltrlg has modified TemplateDataEditor in frwiki, including suggestions here and adding a way to easily translate the tool in many languages. So, it can now be used from every wiki. If you want to contribute to translations, I think the best way is to propose translations at [[:fr:Discussion utilisateur:Ltrlg/scripts/TemplateDataEditor.js]], the messages to be translated are at the beginning of [[:fr:Utilisateur:Ltrlg/scripts/TemplateDataEditor.js]] (the "messages"). --[[User:NicoV|NicoV]] ^{([[:fr:Discussion Utilisateur:NicoV|Talk on frwiki]])} 11:31, 24 July 2013 (UTC)

== Had a go - feedback ==

I've just tried adding TemplateData to {{tl|EW charity}} on its /doc page - not one of the commonest templates, but one I know and understand as I wrote it. But I don't know whether I've done it right, and from the sound of it there's a 60-hour delay before I can look at its effect. Hmm, not ideal.

Comment on the tutorial: you don't explain what to do for an optional parameter (ie that "required" can be omitted, which seems to be the case, rather than needing to be set to "false"). I also wasn't very clear what I was supposed to be putting in the various fields - perhaps if I use more templates with templatedata it will start to make more sense.

I don't like being offered a choice without any indication which is preferred or why: please indicate the "best" or "standard" place to put the TemplateData (template page or /doc page) - and it might be helpful to standardise mildly on whether it goes at top or bottom of the /doc page, if that's the better page for it to be. Unnecessary choices are hard work: just tell us where to put the TemplateData.

In the list of heavily used templates, I noted that {{tl|hatnote}} is marked up as "done". I wanted to have a look at the effects, as it's a template with no named parameters, just one locational parameter. Editing my sandbox I clicked to transclude "Hatnote"... and got no information about the parameters, just the usual "Add parameter" and "No unused parameters" - not what I expected. Looking at [http://en.wikipedia.org/w/index.php?title=Template:Hatnote/doc&action=history the history] I see the TemplateData was added on 11 June, 6 days ago. Should something useful be displayed when I try to use the template? I'm struggling rather with all of this as yet. [[User:PamD|<font color="green">'''''Pam'''''</font>]][[User talk:PamD|<font color="brown">'''''D'''''</font>]] 15:59, 17 July 2013 (UTC)

:Having another look, I see that it seems to tell me I need to add "required" and set it to "false". Do I really? And I've realised that one reason the example is particularly confusing is that "string" is both a parameter name and a type! There might be a clearer example perhaps? [[User:PamD|<font color="green">'''''Pam'''''</font>]][[User talk:PamD|<font color="brown">'''''D'''''</font>]] 16:05, 17 July 2013 (UTC)

::Still not going well: I tried adding {{tl|EW charity}} to an article, couldn't see the parameters I'd added in TemplateData 4 days ago. Tried choosing "EW charity/doc" from the dropdown menu... and the templates appeared with their descriptions... but continuing transcludes the documentation page into the article. Something is going wrong: either the documentation is wrong or I'm misreading it. Could someone have a look at [[Template:Genukiwry/doc]] and tell me what I'm doing wrong? Thanks. [[User:PamD|<font color="green">'''''Pam'''''</font>]][[User talk:PamD|<font color="brown">'''''D'''''</font>]] 22:24, 21 July 2013 (UTC)

:::There is a long delay between changing the template data section and it actually being read by the Visual Editor. I waited nearly a week for {{t1|Coord}} to be updated. You may find it updates quicker if you do a [[WP:NULL]] edit to the main template page (not the doc page).--[[User:Salix alba|Salix]] ([[User talk:Salix alba|talk]]): 22:55, 21 July 2013 (UTC)

:::The data you have specified looks fine for me.--[[User:Salix alba|Salix]] ([[User talk:Salix alba|talk]]): 22:56, 21 July 2013 (UTC)

::::The TD seems ok, except for the parameters names: I think it's not ''regno'' and ''charityname'', but just ''1'' and ''2''. --[[User:NicoV|NicoV]] ^{([[:fr:Discussion Utilisateur:NicoV|Talk on frwiki]])} 08:10, 22 July 2013 (UTC)

:::::Thanks, Nico, I've amended them to numbers and will try again. The documentation isn't helpful as to how to code templates with locational rather than named parameters. Once I can see that I've got this right I might try to help improve the documentation. Will now presumably have to wait some time to see the effect. Will try the null edit suggested. [[User:PamD|<font color="green">'''''Pam'''''</font>]][[User talk:PamD|<font color="brown">'''''D'''''</font>]] 08:19, 22 July 2013 (UTC)

::::::Tweaked the doc already to help. But please double-check, if you like all changes. [[User:GermanJoe|GermanJoe]] ([[User talk:GermanJoe|talk]]) 08:33, 22 July 2013 (UTC)

'''Success''': I've managed to add {{tl|Genukiwry}} to my sandbox, using the templatedata - it certainly helps a lot, but I did find a couple of problems which I've reported at [[Wikipedia:VisualEditor/Feedback#Template_parameter_addition_problems]]. Thanks, all, for your help. I've been experimenting with two different templates and muddling my comments on them both, sorry for any confusion. [[User:PamD|<font color="green">'''''Pam'''''</font>]][[User talk:PamD|<font color="brown">'''''D'''''</font>]] 08:51, 22 July 2013 (UTC)

== Is the example correct? ==

The example for {{t1|str left}} uses named parameters. However the actual template uses positional parameters! Did anyone check or test?

Should we change the example or fix it to use positional parameters instead. Ideally we want a fuller example which combines named parameters, and positional parameters. An example which also used the string/wiki-user-name, string/wiki-page-name would be good.--[[User:Salix alba|Salix]] ([[User talk:Salix alba|talk]]): 15:04, 24 July 2013 (UTC)

:If you want to write a more full example I would be massively grateful; your tweaks so far have been most welcome :). [[User:Okeyes (WMF)|Okeyes (WMF)]] ([[User talk:Okeyes (WMF)|talk]]) 17:06, 24 July 2013 (UTC)

::Just tested, template does only take positional parameters. Have done a quick fix, now the example should be correct. For further improvements another template would be a better example, agreed. [[User:GermanJoe|GermanJoe]] ([[User talk:GermanJoe|talk]]) 17:15, 24 July 2013 (UTC)

== Skeleton TemplateData Generator ==

I've thrown together a [http://singsurf.org/things/TemplateData.php Skeleton TemplateData Generator]. It reads the source of a template and tries to find all the parameters used, using the regexp <code>/\{\{\{[^\|\}</code> and outputs a skeleton document with all the parameters listed. --[[User:Salix alba|Salix]] ([[User talk:Salix alba|talk]]): 15:16, 25 July 2013 (UTC)