Difference between revisions of "User:Bitmap/ws/js/template"

From MusicBrainz Wiki
(draft v2)
 
Line 2: Line 2:
  
 
==Syntax==
 
==Syntax==
 +
 +
===General===
  
 
Requests should be sent to the URL
 
Requests should be sent to the URL
Line 11: Line 13:
 
The available template names are hardcoded, and correspond to a single template file in the mbserver root.
 
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 outermost type in the document must be an array of objects, with each object representing a separate rendering request. This allows the endpoint to render multiple instances of the template in a single POST.
+
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===
 
===Example===
Line 19: Line 41:
 
   POST /ws/js/template/track HTTP/1.1
 
   POST /ws/js/template/track HTTP/1.1
 
   
Content-Type: application/json; charset=utf-8
 
   
Content-Type: application/json; charset=utf-8
    
+
   
  [
+
   {
    {
+
    "stash": [
      "position": "1",
+
      {
      "name": "Part Company",
+
        "position": "1",
      "length": "4:54",
+
        "name": "Part Company",
      "artist": "The Go-Betweens"
+
        "length": "4:54",
    },
+
        "artist": "The Go-Betweens"
    {
+
      },
      "position": "2",
+
      {
      "name": "Just a King in Mirrors",
+
        "position": "2",
      "length": "2:58",
+
        "name": "Just a King in Mirrors",
      "artist": "The Go-Betweens"
+
        "length": "2:58",
     }
+
        "artist": "The Go-Betweens"
   ]
+
      }
 +
     ]
 +
   }
  
 
==Response==
 
==Response==
  
If the request is OK, the response will contain a JSON array of rendered HTML fragments (strings). The order of the fragments will be the same as the argument objects' order in the initial request.
+
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.
 
Other possible responses are listed below.
Line 48: Line 86:
 
(Not a real example.)
 
(Not a real example.)
  
   [
+
   {
    "<tr class="track">
+
    "output": [
      <td class="position">1</td>
+
      "<tr class="track">
      <td class="title">Part Company</td>
+
        <td class="position">1</td>
      <td class="artist">The Go-Betweens</td>
+
        <td class="title">Part Company</td>
      <td class="length">4:54</td>
+
        <td class="artist">The Go-Betweens</td>
    </tr>",
+
        <td class="length">4:54</td>
    "<tr class="track">
+
      </tr>",
      <td class="position">2</td>
+
      "<tr class="track">
      <td class="title">Just a King in Mirrors</td>
+
        <td class="position">2</td>
      <td class="artist">The Go-Betweens</td>
+
        <td class="title">Just a King in Mirrors</td>
      <td class="length">2:58</td>
+
        <td class="artist">The Go-Betweens</td>
    </tr>"
+
        <td class="length">2:58</td>
   ]
+
      </tr>"
 +
    ]
 +
   }
  
 
==Available Templates==
 
==Available Templates==

Latest revision as of 15:13, 5 June 2012

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>