GettingStartedEmbeddedHtml

An introduction to embedding Argots within your HTML and XHTML pages.
Featured

Updated Jul 13, 2010 by mark.bir...@gmail.com

Introduction

The technique that we use to place Argot terms into a web-page is called RDFa, a standard from the W3C. If you are not familiar with it, then you may want to read IntroductionToRdfa first, before continuing with the discussion here.

In this tutorial we'll show how to markup a simple job vacancy, using terms from the Vacancy Argot.

A sample vacancy

To give us something to work with, here is a vacancy from the Civil Service web-site:

There is a lot of information here, and most of it is easy to decipher for a human reader:

Reference	RT6210
Department	National Audit Office
Job title	Researchers – for Value for Money audit work
Location	SW1W9SP, Greater London, London
Closing date	23 July 2010
Number of vacancies	10 or more
Working arrangement	Full time

If we want to get as much as we can out of this information we need to make it 'machine-readable', and that involves using RDFa to add terms to the markup -- terms that will come from lists such as the Argots on this site.

We'll now look at how to add RDFa to the markup.

Loading vocabularies

As you saw in the IntroductionToRdfa, the terms that we are using to describe a job vacancy come from named lists. The first step then, is to make a reference at the top of the document to the lists we'd like to use.

The terms we need are from the following lists:

List name	Description	Prefix
Argot Hub	The Argots defined on this site.	arg
Dublin Core	A common list of terms which are applicable in a wide range of situations.	dc
FOAF	The Friend-of-a-Friend vocabulary, used to describe people, companies, projects, and so on.	foaf

To express a list of terms that we want to have included in our document we add @xmlns references, like this:

<html
 xmlns:dc="http://purl.org/dc/terms/"
 xmlns:arg="http://purl.oclc.org/argot/"
 xmlns:foaf="xmlns:foaf="http://xmlns.com/foaf/0.1/"
>
  ...
</html>

Note that by adding the declarations to the root of the document they are available throughout the entire document, but if you only have control over a part of the document it's just as valid to place the vocabulary declarations on another element:

<div
 xmlns:dc="http://purl.org/dc/terms/"
 xmlns:arg="http://purl.oclc.org/argot/"
 xmlns:foaf="xmlns:foaf="http://xmlns.com/foaf/0.1/"
>
  ...
</div>

The only requirement is that these declarations are placed 'above' any markup that uses them -- i.e., on an element that is a parent of any element that references one of these vocabularies.

Now that we have the vocabularies available, we can look at how to add terms.

Adding a vacancy

In this section we'll look at how to add a vacancy, and in the next section we'll add jobs to the vacancy. This may seem a little odd, but in these argots we distinguish between a vacancy -- which is an indication that one or more jobs are available -- and a job, which is something with a salary and a location.

Identifying a vacancy

A vacancy requires two pieces of information to identify it. The first indicates that the vacancy is a document, and the second makes this more precise and says that it's a specific type of document -- a vacancy.

The first part of this information is expressed using the RDFa attribute @typeof, as follows:

<div  typeof="foaf:Document">

The second piece of information is expressed by qualifying this with a Dublin Core type value:

<span rel="dc:type" resource="[arg:Vacancy]"></span>

Note that there is nothing inside the span element, but we need to have the open and closing tags for HTML browsers, since they don't all correctly process the XHTML short-form:

<!-- Do NOT do this -->
<span rel="dc:type" resource="[arg:Vacancy]" />

So far, our template looks like this:

<div  typeof="foaf:Document">
  <span rel="dc:type" resource="[arg:Vacancy]"></span>
</div>

Recall that we said the vocabulary declarations need not appear on the html element, as long as they are declared before they are used? This means that you might find it easier to control if the declarations are placed on the first element that is part of the vacancy declaration:

<div
 xmlns:dc="http://purl.org/dc/terms/"
 xmlns:arg="http://purl.oclc.org/argot/"
 xmlns:foaf="xmlns:foaf="http://xmlns.com/foaf/0.1/"

 typeof="foaf:Document"
>
  <span rel="dc:type" resource="[arg:Vacancy]"></span>
</div>

Joining the Linked Data cloud

A key principle of Linked Data is to give everything a URI so that others can refer to your data. In our example so far the URI for the vacancy is 'hidden' since it is automatically generated by using @typeof. However, for our vacancy to become part of the Linked Data cloud we need only add an identifier using the RDFa @about attribute, placed on the same element as the @typeof attribute (the value in the attribute doesn't matter, provided that it begins with '#'):

<div
 xmlns:dc="http://purl.org/dc/terms/"
 xmlns:arg="http://purl.oclc.org/argot/"
 xmlns:foaf="xmlns:foaf="http://xmlns.com/foaf/0.1/"

 about="#this"
 typeof="foaf:Document"
>
  <span rel="dc:type" resource="[arg:Vacancy]"></span>
</div>

Now some other Linked Data service can refer to this vacancy using the following URI:

http://www.civilservice.gov.uk/jobs/careers-detail.aspx?JobId=5085#this

Identifying the publisher

For the vacancy to appear correctly in any search results, it is important to add publisher information. The property to use is dc:publisher, which requires a URI. Currently there are no well-defined identifiers for organisations and departments so if one is not available for your organisation, then use the organisation's home-page:

<span rel="dc:publisher" resource="http://www.civilservice.gov.uk/"></span>

Indicating the source of the vacancy

It's important for search engines and other crawlers to be able to indicate where the vacancy came from. Since in this case the vacancy has actually come from the page itself then we can easily indicate this by using a relative URI:

<span rel="dc:source" resource=""></span>

The title of the job

Now that we have a container for the vacancy we can start to add information about it. One of the most important values will be the job-title, for which we use the Dublin Core term, dc:title:

<h2 property="dc:title">Researchers – for Value for Money audit work </h2>

Note how RDFa allows its attributes to be added to any HTML element.

Providing a reference

Next we need a reference code to identify the job, for which we use the Dublin Core identifier property:

<h3>Summary Information for vacancy - reference <span property="dc:identifier">RT6210</span></h3>

At the moment there is no coordinated, inter-departmental way, to create vacancy references, so in this example the reference is the Civil Service's own value.

Closing date

Information about the closing date for applications can be provided using the Dublin Core valid property. Note however that as with salary we'll invariably override the inline text with the @content value since the machine-readable format for dates is not so good for humans:

<p property="dc:valid" content="2010-07-23">23 July 2010</p>

The date format is yyyy-mm-dd as defined by ISO 8601.

Interview start date

If there is a specific date on which the interviews will begin, this can be indicated with the arg:interviewsStart property (again, using ISO 8601):

<p property="arg:interviewsStart" content="2010-07-30">30 July 2010</p>

Number of jobs available

If there is more than one job available then this can be indicated with the Dublin Core extent property:

Number of vacancies: <span property="dc:extent" content="11">10 or more</span>

Short description

A short description of the vacancy can be provided with the Dublin Core abstract property. This may be used as a summary in search results, so it could be used to 'sell' the vacancy and encourage candidates to read on:

Brief Description: <span property="dc:abstract"
  >Is your background in Economics, Statistics, Operational Research, Social Research or Performance
  Measurement?</span>

Long description

To provide a full description we use the Dublin Core description property. This will often contain other mark-up:

Vacancy Description: <span property="dc:description"
  >The role of Researcher is to apply strong quantitative research and analytical skills to our value for
  money (VFM) audits. Researchers work as integral members of...</span>

References to supporting documents

Often a vacancy will refer to documents that an applicant can read to find about more about the job, the potential employer, any requirements, and so on. These can be added using the Dublin Core requires property, for example:

<a rel="dc:references" href=/uploaded_files/060410113140_Job%20Description.pdf
  >060410113140_Job Description.pdf</a>

Job details

So far everything we have described concerns the vacancy in the sense of a notification about a job, rather than the job itself. For example, a job might have the title 'nurse', whilst the vacancy might have the title 'Five nurses needed in South London hospital'. Information such as salary and location are attached to the job rather than the vacancy, so now we'll look at how to make the connection. (More information is available at ArgotJob.)

Indicating a job

A job is indicated in much the same way as a vacancy, using @typeof, although it's slightly simpler since we don't need to use the Dublin Core type property. The declaration would look something like this:

<div typeof="arg:Job">
  ...
</div>

However, if left like this the job would actually be unrelated to the vacancy, so we need to establish a connection between the two, which we do with the Dublin Core hasPart property:

<div rel="dc:hasPart">
  <div typeof="arg:Job">
    ...
  </div>
</div>

If you've lost track a bit, all we're saying is that we have a vacancy which references a job. The general pattern for this would be:

<div
 about="#this"
 typeof="foaf:Document"
>
  <span rel="dc:type" resource="[arg:Vacancy]"></span>
  .
  .
  .
  <div rel="dc:hasPart">
    <div typeof="arg:Job">
      .
      .
      .
    </div>
  </div>
</div>

One last point to make on this; the other reason for splitting jobs and vacancies in this way is that sometimes an advert will reference many jobs. This is easily achieved by placing many job 'blocks' inside the hasPart container:

<div
 about="#this"
 typeof="foaf:Document"
>
  <span rel="dc:type" resource="[arg:Vacancy]"></span>
  .
  .
  .
  <div rel="dc:hasPart">
    <div typeof="arg:Job">
      .
      .
      .
    </div>
    <div typeof="arg:Job">
      .
      .
      .
    </div>
    <div typeof="arg:Job">
      .
      .
      .
    </div>
  </div>
</div>

Salary range

The salary range is added to the job using the arg:salaryFrom and arg:salaryTo properties. We'll also use the RDFa @content attribute to provide a machine-readable value that is different to the human-readable one:

From <span property="arg:salaryFrom" content="22000">£22,000</span> to <span property="arg:salaryTo" content="32000">£32,000</span>.

If the salary is expressed as a monthly figure -- or some other period -- then there are other properties available to describe this, and they are explained in ArgotJobRemuneration. For example, to indicate that the salary is monthly, we might add this:

Pay frequency: <span property="arg:salaryFrequency">Monthly</span>

Location

The location of the job is simple to markup, using the Dublin Core dc:coverage term:

<p property="dc:coverage">Greater London, London, SW1W 9SP</p>

More information is available at ArgotLocation.

Type of job

To indicate whether the job is permanent or a fixed-term appointment, we use the arg:jobType property:

Appointment Terms: <span property="arg:jobType">Permanent</span>

Working arrangements

To indicate the working arrangements for the job -- such as full-time or part-time -- we use the arg:workingArrangements property:

Working Arrangements: <span property="arg:jobType">Full-time</span>

Specific requirements

Some jobs will have specific requirements, such as that a CRB check is carried out, or that the employee holds a UK work-permit. To create a container for requirements we use the arg:requires property, as follows:

<div rel="arg:requires">
 ...
</div>

To indicate whether the job will require travel we add a requirement. For example, if international travel is required, this can be added to the requirements container as follows:

<div rel="arg:requires">
  Travel required: <span resource="[arg:TravelInternational]">Some international travel</span>
</div>

Similarly, if a CRB check is required we do this:

<div rel="arg:requires">
  CRB check required: <span resource="[arg:CheckCRB]">Yes</span>
</div>

Note that the values in the requirements section only indicate that there is a requirement. If they are not present then there is no requirement. So to indicate that foreign travel is not required we simply omit the relevant value:

<div rel="arg:requires">
  CRB check required: <span resource="[arg:CheckCRB]">Yes</span>
  International travel required: <span>No</span>
</div>

It's also worth bearing in mind that in RDFa it doesn't matter whether items are grouped on a single property, or whether the property is repeated. For example, the two sets of mark-up mean exactly the same thing in RDFa:

<div rel="arg:requires">
  CRB check required: <span resource="[arg:CheckCRB]">Yes</span>
  Travel required: <span resource="[arg:TravelInternational]">Some international travel</span>
</div>

<div rel="arg:requires">
  CRB check required: <span resource="[arg:CheckCRB]">Yes</span>
</div>
<div rel="arg:requires">
  Travel required: <span resource="[arg:TravelInternational]">Some international travel</span>
</div>

This may be useful if the requirements information is scattered throughout the page, and is difficult to group. And if you only have a single requirement at a particular location on the page, it can be expressed in the following more compact way:

Travel required: <span rel="arg:requires" resource="[arg:TravelInternational]">Some international travel</span>

Comment by bren...@gumpshen.com, Apr 27, 2011

The property on Working arrangements is incorrect

► Sign in to add a comment