CollectionsHowTo

Making Collection Files

Collection files (.co) are actually just renamed ZIP files. Thus no fancy new tools or file formats are needed -- just pick your favourite ZIP tool. This also has the added advantage that the collection files tend to be nice and compact for transferring. It's also what we did for the Shareaza skin files (.sks), so there is some consistency.

Collection.xml

The main file in the .co (zip) is Collection.xml, which must appear somewhere. This file should start out in most cases:

<?xml version="1.0" encoding="UTF-8" ?>
<collection xmlns="http://www.shareaza.com/schemas/Collection.xsd">
<!-- properties and contents go here -->
</collection>

Next are the two main elements of a collection:

Properties - This element describes the collection itself, including its title, its mount information (optional), and its metadata using a folder schema. Metadata is quite important because it is what allows others to search for and find the collection, and is also used to mount the collection in the right place in the library. Also, the metadata provided here will be copied to the metadata for the library folder, providing a way to send out clean, fully featured metadata. Here's an example of a music album:

	<properties>
		<title>Album Name</title>
		<mounting>
			<parent uri="http://www.shareaza.com/schemas/musicAlbumCollection.xsd"/>
		</mounting>
		<metadata xmlns:s="http://www.shareaza.com/schemas/musicAlbum.xsd">
			<s:musicAlbum>
				<s:title>Album Name</s:title>
				<s:artist>Artist Name</s:artist>
				<s:year>2000</s:year>
				<s:genre>Pop</s:genre>
			</s:musicAlbum>
		</metadata>
	</properties>

Contents - This element contains entries for each file that the collection references. There can be one or more URNs identifying the file, for example a bitprint is a good idea, but you could also include an ed2k to facilitate searching, or whatever. At least one URN is required. Optionally it can include a nominal filename and file size for display purposes. Also optionally, it can include metadata. This metadata takes precedence over that collected from the file itself. This allows a collection (created by hand remember) to provide much more comprehensive metadata for the files it references, and so when other users search for and find files in the collection, they will be better commented. Finally, the file record can nominate that this file is actually contained inside the ZIP and should be extracted. Could be useful for album art or other small things.

	<contents>
		<!-- this is a normal file that someone would download -->
		<file>
			<id>urn:bitprint:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA</id>
			<description>
				<name>File name.mp3</name>
			</description>
			<metadata xmlns:s="http://www.shareaza.com/schemas/audio.xsd">
				<s:audio>
					<s:title>Song Title</s:title>
					<s:artist>Artist</s:artist>
					<s:album>Album</s:album>
					<s:genre>Pop</s:genre>
					<s:year>2000</s:year>
					<s:track>1</s:track>
				</s:audio>
			</metadata>
		</file>
		<!-- this is an example of a file that your HTML pages could reference, the hash has to match the file 
			or it will not work (i think) -->
		<file>
			<id>urn:bitprint:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA</id>
			<description>
				<name>style.css</name>
			</description>
			<packaged>
				<source>style.css</source>
			</packaged>
		</file>
	</contents>

The rest of the ZIP can be used to package files. This should include at least an "index.htm" file, which is the root content page for display in the library. It could contain other pages, and supporting resources such as images, or even flash or whatever.

Namespace and Page Access

The collection file content inside the .co is accessed through a URL protocol of the form "p2p-col://SHA1/path", where SHA1 is the SHA1 of the .co file. A content author will not need to worry about that, as Shareaza determines the correct URL for the index.htm file, and then all links or image src="" tags are relative. Note that Shareaza never decompresses the .co file! It's all accessed through the p2p-col: namespace, so there are no "local files" and hopefully no security issues -- eg if you deploy an EXE file in the .co and link to it on a page, it should show the normal "are you sure you want to download this potentially unsafe file" prompt.

Script and Object Model

The content pages can contain all kinds of cool things such as DHTML. In fact, I imagine most pages would contain simple script code to show different content depending on whether a user has each file downloaded or not.

Script on the page can interact with the Shareaza object model via the standard "window.external.*" property. This is a front object provided by Shareaza with 5 methods:

• window.external.open( "urn:..." ) - open indicated file if it is available, returns true/false
• window.external.enqueue( "urn:..." ) - add indicated file to playlist if it is available, returns true/false
• window.external.download( "urn:..." ) - find the file with the indicated URN, and download it
• window.external.downloadAll() - download all files in the collection (if they are not already available)
• window.external.detect( "urn:.." ) - detects the state of the indicated file. Returns a string - "Complete" means the file is fully available. Empty string "" means the file is not known anywhere. Otherwise, a download percent in the form "x.xx%".
• window.external.missingCount - indicates how many files in the collection have not yet been downloaded

NOTE: The methods above ONLY work with URNs listed in the XML.

---

If you think you have made something worth sharing then consider making a collection template: How-To.