Attachments
An important function of many electronic portfolio tools is to hold electronic files that either have been created by the portfolio holder, or in some other way serve as evidence of other items, particularly including abilities claimed. Indeed, some practice makes this the most important aspect of the portfolio, with relatively little provision for documentation of activities, or for reflection.
Note that many resources are not files, and cannot be attached as files. This page deals only with attachable files. For other resources that are not attached, please see the documentation on resources.
In Leap2A, files are transported in a zip archive, along with a single Leap2A XML file. All other files must be referred to from somewhere within the Leap2A XML, otherwise it would be unclear what they mean, and how they relate to other parts of the portfolio information. There is no particular structure specified for the zip archive, except that it must contain exactly one file called "leap2a.xml" at the root directory. Folders may be used, or not, in any way within the zip archive, and in particular the folder structure and names may be used by systems to guide re-import of exported files.
There are two kinds of file to consider:
- a file that is, in itself, an important part of the portfolio;
- an incidental attachment that is understood solely in the context of the item it is attached to.
Important parts
Files that are in themselves important parts of the portfolio are represented within the Leap2A XML as items of type resource, with their own entry. The resource entry that represents the file in the Leap2A XML is linked to the actual file with
<link rel="enclosure" href=... type=... length=... />
where the href value is a relative link to the actual file in the zip archive. See the Atom documentation on enclosure. Although other Atom link types could in principle be used (and may have been used in 2009-03 implementations), using rel="enclosure" is adaptable to any kind of file, and so can be used consistently. It is also fully compatible with the option of describing the resource in the resource entry's content.
The length attribute, recommended in Atom, is also recommended in Leap2A, but is not mandatory.
Linking to resource items from other items in the portfolio
Where a file has an associated Leap2A XML resource entry that represents it, reference from other places in the portfolio must not be directly to the file itself, but only to the resource entry. The link from the non-resource to the resource entry should use the most meaningful Leap2A relationship that is applicable. The link rel="enclosure" must not be used. If no more specific relationship is applicable, use link rel="related" (see relation).
Resource types where the resource refers to an attached file
Of the existing resource types, the one that is most suitable for resources with attached files is "Offline".
Do not export content with src attribute
As it clarified in the resource page, and in the documentation for content, the use of the src attribute within atom:content – atomOutOfLineContent – is deprecated for Leap2A export. It is, however, advisable to process this on import, in case the import follows non-Leap2A Atom conventions.
Incidental attachments
Where an attachment is understood solely in the context of an item to which it is attached, it may be represented with <link rel="enclosure" ... />, as specified in Atom, directly from any suitable item. Any number of attachments may be attached to the same item in this way. This mechanism for attachment is equivalent to linking to a resource entry, where the resource entry has no meaningful title or content of its own. The intention is for this to be similar to the practice in e-mail and blogs to include any files to which the blog entry or e-mail refers.
Use of the Atom enclosure link
Where the Atom enclosure link is used, the Atom rules for this must be followed. Within Leap2A, the href attribute of the this enclosure link must be a relative URL pointing to the file in the zip archive. Thus, rel="enclosure" is included as a Leap2A-specified native Atom relationship, alongside rel="related".
The Atom link rel="enclosure" should only be used in this way, to link a file directly to a Leap2A item, and not in any other way: specifically it must '''not''' be used to link between two Leap2A items.
Related pages
- On the relationships page there is discussion about Threads. Threads relate also to conventions established for direct communication.
- http://www.leapspecs.org/2A/literals#content_or_description
- http://www.leapspecs.org/2A/literals#structured_content
- http://www.leapspecs.org/2A/types/resource
- categories#resource_type
Background
See the threads on PORTFOLIO-INTEROPERABILITY-WORK starting with