Tag a Content Item

tags are added to a content item using a field called com.escenic.tags. This field is a ordered list constructed of payloads. The order of the list is kept. The payload itself is constructed of two fields.

tag

The href attribute of the origin element is used to identify the tag. The value of the href attribute can be derefenced to get the tag entry. The value element contains the read only value of the tag title.

<field name="tag">
  <origin href="http://example.com/tags/cn"/>
  <value>Celebrity News</vdf:value>
</vdf:field>  
            
relevance

The relevance of the tag in regards to this content item. Relevance is a number between 0.0 and 1.0 inclusive. If the relevance field is omitted the server will return with a 400 Bad request response.

<field name="relevance">
  <value>0.7</vdf:value>
</vdf:field>  
            

When you GET the entry after a successful PUT or POST, the resulting atom entry will contain atom category elements in addition to the list of tags in the com.escenic.tag field. This is a informational feature offered for generic Atom processors.

<category scheme="tag:geographic@escenic.com,2011-04-28" term="Oslo" label="Oslo" title="Tag: Europe / Norway / Oslo"/>
      

To add tags to an existing content item:

  1. Retrieve the content item as an Atom entry resource (as described in Change a Content Item).

  2. Add the com.escenic.tags field to the entry or replace it if the content item was was tagged already.

    <field name="com.escenic.tags"> 
      <list> <!-- order is kept --> 
        <payload> 
          <field name="tag"> 
            <origin href="http://example.com/mj"> <!-- URL of the tag entry --> 
            <value>Michael Jackson</value> <!-- read only value of the tag "title" --> 
          </field> 
          <field name="relevance"> <!-- mandatory --> 
            <value>1.0</value> <!-- must be floating point between (inclusive) 0.0 and 1.0 --> 
          </field> 
        </payload> 
        <payload> 
          <field name="tag"> 
            <origin href="http://example.com/tags/hc"> 
            <value>Holy Cow</value> 
          </field> 
          <field name="relevance> 
            <value>0.8</value> 
          </field> 
        </payload> 
        <payload> 
          <field name="tag"> 
            <origin href="http://example.com/tags/cn"> 
            <value>Celebrity News</value> 
          </field> 
          <field name="relevance> 
            <value>0.7</value> 
          </field> 
        </payload> 
      </list> 
    </field>
  3. Save the modified entry in a file.

  4. PUT the file back to the same URI from which it was retrieved (as described in Change a Content Item).