2A/structured content

From Leapspecs

Belongs to the Leap2A/specification

This is an advanced use of Leap2A content

Contents 1 Principles and requirements 2 The essential structures 2.1 Representations of other items 2.2 Links to other items and files 3 On export 4 On import 5 General filtering and page layout 6 Patterns 6.1 Simple links 6.2 Embedded content

Principles and requirements

In essence, this part of the spec deals with showing where a reference to, or representation of, one item is included in the content of another item. In all of these cases, special treatment is needed to avoid either duplication of material, or broken links.

Where possible, we also want to agree on conventions to avoid, where possible, creating unnecessary problems for an importing system to display content from an exporting system. However, we accept as given that it is generally impossible to do this without loss. We are aiming just at least to enable all the content from one system to be displayed somehow on another system, even if it does not have the elegance of a native display. Ideally, systems should allow reformatting of imported structured content.

These are some of the basic principles which we want to support.

• There is a use for some content to be both human-readable, and to refer to other items within the same portfolio information. We want to provide structured content capability in any context, but two of the more obvious examples of this are
  • PebblePad webfolios
  • Mahara views
• Any exported content needs to be renderable in a simple browser without important loss. That means, among other things, no hidden content, no dependency on Javascript etc. (You can include Javascript, but all the content must be displayed even with Javascript switched off.)
• It is important not to force the generation of extra duplicate content. Importing systems must be able to tell where included content comes from. That is, if the content rendered in a view is simply the content from another item, it must be flagged as such, to enable it to be distinguished from independent layout material.
• Straightforward links, that are not suitable for displaying as embedded objects, should be represented simply.
• To follow the principle that all links between portfolio items should be able to be represented at both ends of the relationship, all relationships between items in the same portfolio information that are embedded in the content of that item need also to be (redundantly) represented as atom:link elements in the item.
• All this only applies to links to, and representations of, content of other items within the portfolio export.

The key concept in implementing this is exported content may contain "referring elements", that refer to other items, and that contain either a representation of the item referred to, or link text for a link to it, in a format appropriate to the exporting system. Importing systems may discard a contained representation and replace it with a link or representation in a form more suitable for display in the importing system.

The essential structures

Representations of other items

 <content type="xhtml">
   <div xmlns="http://www.w3.org/1999/xhtml">
     <p>Any amount of narrative could go here.</p>
     <p>Here may also be some other xhtml content relevant to the formatting of the selection.</p>
     <p>The simplest case might be that some content from another item might be enclosed in a "p" element</p>
     <p rel="leap2:has_part" src="portfolio:resource_344"> <!--this is the element referring to the other item -->

Now, all the material that will go in here, between the start and end tags of the referring element, including any xhtml markup, and any fancy additional extras such as script functions, represents the way that resource_344 is rendered in the manner of the exporting system. All of this, but not the referring element itself, can be thrown away by the importing system, and the content of the referring element can be replaced with the importing system's rendering of resource_344. This text is explanatory - it is unlikely that any text would actually be here. However, there must be something here - to include an empty referring element would add nothing in addition to the link element that must be included in any case.

     </p>
   </div>
 </content>

The fact that all the stuff contained within the referring element may be thrown away, and replaced, leads to a very clear requirement.

When the inside of the referring element is removed, and replaced by arbitrary XHTML of the kind that is allowed inside a p element, the result must still be valid XHTML. This implies that the following common XHTML elements must not be used as referring elements:

• table: because tr elements are expected;
• tr: because td or th elements are expected;
• ol, ul: because li elements are expected;
• dl: because dt, dd elements are expected;
• h1, h2, h3 etc.: because only text and possibly inline elements expected.

In each case, XHTML constrains what can appear within those elements.

Elements that are definitely OK to use as referring elements include:

• p
• td
• li
• div

The a element should only be used as a referring element when it is used in the normal way, as a clickable link.

These lists are not definitive, and further restrictions may be added in future versions.

Links to other items and files

This should be exported like a normal html link, with the addition of an extra rel attribute giving the relationship between the item whose content this is, and the item or file referred to. There should be text, as normal, to click on, which should be unchanged by export and import processes. Obviously, the link href attribute value needs to be relative to the portfolio:

• typically CURIEs starting with the "portfolio:" abbreviation for other items;
• relative URLs for files that are included in the exported zip archive.

On export

If you simply have a straightforward link to another item or file in the current portfolio export, intended to be displayed as a link, use an ordinary XHTML <a> element. To this element, add a rel attribute giving the relation, as well as the href to the related item. The rel attribute value would normally be one of the relationships specified in Leap2A/relationships, including the Atom relationships specified in Leap2A: "related" and "alternate". (2009-12-02: This is also envisaged as including Atom's "enclosure".) The href attribute value needs to be converted, for all items or files included in the export, so that it effectively refers to the item or file inside the portfolio export. An item link will be a CURIE typically with the prefix "portfolio:"; a file link will be a relative URL pointing to the file in the zip archive.

If your link is to a different destination not part of the current portfolio export, simply display it as normal for you, as no special processing will be applied.

If you include any renderable content from another item in a view, webfolio or any other kind of selection, you have to take considerable care to format the export suitably.

• Look for the closest XHTML element which includes the relevant representation. If no existing one fits, you may introduce a div or span if that still results in valid XHTML. If neither option works at first, the export structure should be altered so that there is a suitable element.
• Give that element a rel attribute with the Leap2A relationship with the other item or file. This could be leap2:has_part.
• Give that element a src attribute with a value equal to the id (local, within the exported portfolio information) of the other item.

Then, what goes inside that element effectively says "this is how the exporting system displays this included item for the purposes of this view (etc.)". Take care only to use this pattern where you are displaying nothing else except the included item (or a link to it), as your rendering of it may be ignored or discarded. But do include either a rendering or a link. This pattern with nothing in it would be meaningless: there is no point in including an empty such element at all, because you can achieve exactly the same effect by simply including the part as a part in the list of links, without any presence in the content.

On import

Watch for the patterns detailed above:

• Any XHTML element (inclusive, not just "a", "span" and "div")
  • with a rel attribute with a Leap2A URI value (or CURIE) representing any Leap2A-specified relationship (not just "has part", and could also be a native Atom rel attribute value)
  • with a src or href attribute with a value pointing to another item or file present in the portfolio information to be imported.

When you get one of these, what you do depends on what it was and what you can deal with.

• The Leap2A relationship in the rel attribute will normally have already been given in a separate link sub-element to the entry element, in which case it will have been processed there. If it is not, and the relationship is only in the structured content, you should process it here.
• If there is an href attribute whose value points to another exported item or file in this portfolio,
  • replace the href value with the appropriate value to link to that imported item or file in your system
  • if it is an "a" element, or if what is contained in the referring element is just plain text, leave it alone and treat it as link text.
• If there is a src value pointing to another item or file in the portfolio, try converting it so that the item or file is displayed in the way that you display it in your system, and throw away the inside of the referring element, which should just include the item itself, rendered as the exporting system would do it. Note also:
  • if you get something that you wouldn't or can't include in the view/webfolio etc., replace the inside of the referring element with a link to it instead. If the referring element was not "a", you should include an "a" element here.

General filtering and page layout

Page layouts between different systems may well be incompatible. The general rule is that systems are expected to export their page layout in a way that reflects the way it is displayed in their own system. It is then up to importing systems to convert that to a form suited to their own system. This is likely to need processing.

• Whole-page table markup, e.g. to separate the page into columns, may be filtered out at import, perhaps for example with tr and td elements replaced by div elements.
• Other filtering will need to reflect what is able to be created and edited within the importing system. E.g. if your users can't do tables at all, you should probably convert tables to flowing forms which can be edited using the tools you provide in the interface.

The overall principle is that it is the importing system that takes responsibility for filtering the content. But this should not be a problem in principle, as it is possible to create quite a simple XSLT which replaces any unsuitable markup, for example replacing tables with dl lists.

Patterns

Simple links

An example will be put here. (Please contribute one!)

Embedded content

 <content type="xhtml">
   <div xmlns="http://www.w3.org/1999/xhtml">
     <p>Here is some introductory, contextual or other xhtml content relevant to the formatting of the selection.</p>
     <p>What about something like a video or a flash presentation explaining all this? It would be nice...</p>
       <object width="448" height="252" rel="leap2:has_part" src="portfolio:resource_328">
         <param name="playlist" value="http://news.bbc.co.uk/media/emp/7780000/7783500/7783561.xml" />
         <param name="config_settings_autoPlay" value="false" />
         <param name="config_settings_showPopoutButton" value="false" />
         <param name="autoPlay" value="false" />
         <param name="fmtjDocURI" value="/1/hi/video_and_audio/default.stm" />
         <param name="config_settings_suppressItemKind" value="advert, ident" />
       </object>
     <p>The idea is to include a little RDFa into the XHTML. Here's a slide show now...</p>
       <div rel="leap2:has_part" src="portfolio:resource_344">
         <div style="width:425px;text-align:left" id="__ss_802503">
           <a style="font:14px Helvetica,Arial,Sans-serif;display:block;margin:12px 0 3px 0;text-decoration:underline;"
              href="http://www.slideshare.net/asimong/the-leap2a-approach-to-portfolio-interoperability-presentation?type=powerpoint"
              title="The Leap2A approach to portfolio interoperability">The Leap2A approach to portfolio interoperability</a>
             <object style="margin:0px" width="425" height="355"><param name="movie"
                value="http://static.slideshare.net/swf/ssplayer2.swf?doc=simon20081009-1228057524637076-9&stripped_title=the-leap2a-approach-to-portfolio-interoperability-presentation" />
                <param name="allowFullScreen" value="true"/>
                <param name="allowScriptAccess" value="always"/>
               <embed src="http://static.slideshare.net/swf/ssplayer2.swf?doc=simon20081009-1228057524637076-9&stripped_title=the-leap2a-approach-to-portfolio-interoperability-presentation"
                 type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="425" height="355">
               </embed>
             </object>
         </div>
      </div>
   </div>
 </content>

---