User:Bitmap/ws/js/template
This document details the proposed /ws/js/template endpoint. It is intended for use by the MusicBrainz JavaScript as a tool to render (relatively) small, reusable templates defined on the server. Templates can therefore be shared for both server and client rendering needs.
Syntax
General
Requests should be sent to the URL
/ws/js/template/{name}
which fetches the template with name {name}.
The available template names are hardcoded, and correspond to a single template file in the mbserver root.
Variables are sent to the template by HTTP POST, in JSON format. The document must be structured as follows:
{
"stash": { ... }
}
"stash" is an object containing all of the parameters to the template.
Batch Rendering
To render multiple instances of the template by a single POST request, an alternative syntax is allowed:
{
"stash": [
{ ... },
{ ... },
...
]
}
Here, "stash" contains an array of objects.
Example
(Not a real example.)
POST /ws/js/template/track HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"stash": [
{
"position": "1",
"name": "Part Company",
"length": "4:54",
"artist": "The Go-Betweens"
},
{
"position": "2",
"name": "Just a King in Mirrors",
"length": "2:58",
"artist": "The Go-Betweens"
}
]
}
Response
If the request is OK, the response will contain a JSON object with the rendered HTML fragment:
{
"output": "<html>"
}
If a single object was sent to the stash, "output" will contain a string. If an array of objects was sent, "output" will be an array of strings (even if only one object is in the array). The order of the fragments will correspond to the order of the objects sent to the stash.
{
"output": [
"<html>",
"<more html>",
...
]
}
Other possible responses are listed below.
- 400 - The JSON sent was malformed/could not be parsed.
- 404 - There is no template with name {name}.
Example
(Not a real example.)
{
"output": [
" 1 Part Company The Go-Betweens 4:54 ", " 2 Just a King in Mirrors The Go-Betweens 2:58 " ] }
Available Templates
None yet.
[The following are examples of templates I need for my relationship editor.]
relationship-editor-recording
<td>
[% link_recording(track.recording, 'show', track.name) -%]
([% track.length | format_length %])
[% IF show_artists -%]
by [% artist_credit(track.artist_credit) %]
[%- END %]
<br />
<dl class="ars">
[%- FOR type_relationships=track.recording.grouped_relationships('artist', 'label', 'recording', 'release') -%]
[%- FOR group=type_relationships.value -%]
[% FOR rel=group.value %]
<dt>[% l(group.key) %]:</dt>
<dd>
[% link_entity(rel.target) %]
<input type="hidden" name="relationships.[% track.id %].id" value="[% rel.id %]" />
<input type="hidden" name="relationships.[% track.id %].action" class="action" />
<input type="hidden" name="relationships.[% track.id %].types.0" value="[% rel.link.type.entity0_type %]" />
<input type="hidden" name="relationships.[% track.id %].types.1" value="[% rel.link.type.entity1_type %]" />
<input type="hidden" name="relationships.[% track.id %].entity0.id" value="[% rel.entity0_id %]" />
<input type="hidden" name="relationships.[% track.id %].entity1.id" value="[% rel.entity1_id %]" />
</dd>
[%- END -%]
[%- END -%]
[%- END %]
</dl>
</td>
relationship-editor-work
<td>
[%- FOR type_relationships=track.recording.grouped_relationships('work') -%]
[%- FOR group=type_relationships.value -%]
[% FOR rel=group.value %]
[% link_entity(rel.target) %] ([% l(group.key) %])
<input type="hidden" name="relationships.[% track.id %].id" value="[% rel.id %]" />
<input type="hidden" name="relationships.[% track.id %].action" class="action" />
<input type="hidden" name="relationships.[% track.id %].types.0" value="[% rel.link.type.entity0_type %]" />
<input type="hidden" name="relationships.[% track.id %].types.1" value="[% rel.link.type.entity1_type %]" />
<input type="hidden" name="relationships.[% track.id %].entity0.id" value="[% rel.entity0_id %]" />
<input type="hidden" name="relationships.[% track.id %].entity1.id" value="[% rel.entity1_id %]" />
<span class="ui-buttons key-[% track.id %] rel-[% rel.id %]">
<a href="#" class="edit-button">edit</a><a href="#" class="remove-button">remove</a>
</span>
<dl class="ars">
[%- FOR work_rel=rel.target.relationships -%]
[% IF work_rel.target_type != 'recording' %]
<dt>[% l(work_rel.phrase) %]:</dt>
<dd>
[% link_entity(work_rel.target) %]
<input type="hidden" name="relationships.[% track.id %].id" value="[% work_rel.id %]" />
<input type="hidden" name="relationships.[% track.id %].action" class="action" />
<input type="hidden" name="relationships.[% track.id %].types.0" value="[% work_rel.link.type.entity0_type %]" />
<input type="hidden" name="relationships.[% track.id %].types.1" value="[% work_rel.link.type.entity1_type %]" />
<input type="hidden" name="relationships.[% track.id %].entity0.id" value="[% work_rel.entity0_id %]" />
<input type="hidden" name="relationships.[% track.id %].entity1.id" value="[% work_rel.entity1_id %]" />
</dd>
[%- END -%]
[%- END %]
</dl>
[%- END -%]
[%- END -%]
[%- END %]
</td>
