Creating a collection: Difference between revisions
m (..) |
(→How do you uninstall a collection?: moved/merged with Collections#Removing a collection ) |
||
(63 intermediate revisions by 18 users not shown) | |||
Line 1: | Line 1: | ||
{{Translations}} |
{{Translations}} |
||
''see also: [[creating an activity]]'' |
|||
If you would like to package a collection of mostly-static content for use on the XO, follow the instructions below to create a collection (sometimes called a library or content bundle). When you're done, you can add your new bundle to the [[Collections]] page so that it can be viewed and downloaded by children worldwide. |
|||
Upon installation it will appear in the [[Library]]. |
|||
If you'd like to help out by creating collections but are unsure of where to begin, see the list of [[User:ZdenekBroz/NewBundle|new bundle ideas]]. |
|||
== Overview == |
== Overview == |
||
The [[Library|OLPC Library]] is the set of content and materials (outside of the core OS and [[Activities]]) that ships |
The [[Library|OLPC Library]] is the set of content and materials (outside of the core OS and [[Activities]]) that ships on the XO laptop and/or school server (the exact set of content shipped with the laptop is usually determined by the organization distributing the laptops within a specific country). In order to make your content available to OLPC projects worldwide, you must create a self-contained [[OLPC Human Interface Guidelines/Activities/Activity Bundles|bundle]] for your content. This page describes the process of creating such a bundle, providing the information you need to select, format, and package a collection. |
||
Note: These instructions explain how to package ''browsable content'' for the OLPC library. Materials in a collection that need to be run by an [[Activity]] other than [[Browse]] will have to have a mime-type registered with the [[Browse]] activity so they can launch from there. [[Activities]] may be part of content packages for the library as well, for instance as sample code to be read. For more information on packaging source code, as well as other questions you may have, skip down to the [[#FAQ]]. |
|||
Collections currently unpack into a directory under <tt>/home/olpc/Library</tt>. Future improvements to the current bundle format are intended to allow a single bundle to contain both an activity and a collection (including, for instance, default help/readme materials). |
|||
Note: These instructions explain how to package ''browsable content'' for the OLPC library. Materials in a content bundle that need to be run by an [[Activity]] other than [[Browse]] will have to have a mime-type registered with the [[Browse]] activity so they can launch from there. [[Activities]] may be part of content packages for the library as well, for instance as sample code to be read; for more information, skip down to the [[Creating_a_content_bundle#FAQ|FAQ]]. |
|||
'''If you plan to host your own bundles, please note the [[#bundle hosting]] guidelines.'' |
|||
Content bundles unpack into a directory under /home/olpc/Library. |
|||
== Feedback == |
== Feedback == |
||
As you create your bundle, please note any puzzles or problems you encounter, |
As you create your bundle, please note any puzzles or problems you encounter, as well as any thoughts for improvement that you might have. You can leave feedback on the [[Talk:Creating a collection]] page. |
||
The process and format is a new one, and feedback helps improve it. One place to do that is on the [[Talk:Creating a content bundle]] page. |
|||
==Selecting |
==Selecting content== |
||
The first step to creating your |
The first step to creating your collection is to determine what content should be included. In some cases, this is easy: everything! In other cases, there are additional considerations: |
||
; Size : How big is your collection? |
; Size : How big is your collection? Keep in mind the limited disk space available on the XO. You may wish to bundle only a subset of your content, perhaps figuring out a way to make the content available entirity on the school server. |
||
:Note: The XO-1's filesystem invisibly compresses files to save space, so you may be using less disk space than you think. Text files are compressed about 50%. Other file formats are basically unchanged. If you are curious, there are (somewhat difficult to apply) instructions in [[JFFS2]] to measure likely disk usage. |
|||
; Quality : Does your collection have a rating system in place? If so, consider including only top-rated material in your content bundle. Otherwise, think about "curating" a selection of high quality material to be included in your bundle (or bundles). |
|||
; Quality : Does your collection have a rating system in place? If so, consider including only top-rated material in your collection. Otherwise, think about "curating" a selection of high quality material to be included in your bundle (or bundles). |
|||
; Relevance : Is your entire collection relevant to children? If so, terrific! If not, consider including only material that will help children learn, explore, and expand their worlds. |
; Relevance : Is your entire collection relevant to children? If so, terrific! If not, consider including only material that will help children learn, explore, and expand their worlds. |
||
Line 27: | Line 34: | ||
; Licensing issues : What kind of copyright exists on the material in your collection? Do you have legal permission to archive and distribute it? Please be sure to review the licensing terms of your collection. For guidance on licensing, see [[licenses]]. |
; Licensing issues : What kind of copyright exists on the material in your collection? Do you have legal permission to archive and distribute it? Please be sure to review the licensing terms of your collection. For guidance on licensing, see [[licenses]]. |
||
==Formatting |
==Formatting content== |
||
Once you've determined the material you'd like to include in your collection, you'll need to format it for use on the XO. |
|||
:''Add explanatory info about the browser and how content is viewed on the XO...'' |
|||
===File formats=== |
|||
Once you've determined the material you'd like to include in your content bundle (or, again, bundles-- since in many cases, you'll have to make two), you'll need to format it for use on the XO. |
|||
The first step of this process is to make sure that all of the content you plan to include is accessible from a HTML index page, or a series of linked HTML pages. '''HTML is currently the only format directly supported by the library''', but you can then include hyperlinks to files of any format supported by the activities present on the XO. When clicked, the content will be presented as a download, copied into the journal, then opened in the appropriate activity. |
|||
===File Formatting=== |
|||
The first step of this process is to make sure that your collection is formatted in a file format that is supported by the library. (Other file formats may be supported on the XO, but not within the library). The following is a list of file formats supported by the library: |
|||
For example, for a simple content bundle including 5 PDF files, you would have to additionally write a HTML index page, providing hyperlinks and descriptions of the 5 PDF files that make up the bundle. |
|||
; Text : <tt>.txt</tt>, <tt>.doc</tt>, <tt>.abw</tt> - These formats can be read by AbiWord and will launch it from the browser. AbiWord will write <tt>.abw</tt> files. |
|||
===Visual formatting=== |
|||
:<tt>.pdf</tt> - This can be ready by xbook, which launches automatically from the browser when following a link to a pdf. |
|||
The second step of the formatting process is to make sure that your collection displays correctly on the XO. The small screen can sometimes lead to unexpected formatting and display issues. Also test it with the screen rotated and in e-book mode (with the screen rotated and lowered). |
|||
; Multimedia document with layout : <tt>.html</tt> - Parsed by the browser. Source will soon be viewable. |
|||
The easiest way to test the visual display of your material is to view it on an XO. If you don't have access to an XO — or to another person who has one — you can install and run the Sugar emulator on your computer. [[Emulating the XO]] has installation instructions. |
|||
: <tt>.pdf</tt> - Read by xbook. |
|||
==Packaging content== |
|||
; Formatted text : <tt>.xml</tt>, <tt>.rss</tt> - Read by the browser and by penguinTV (as feeds). |
|||
; Images : <tt>.jpeg</tt>, <tt>.gif</tt>, <tt>.png</tt> - These can be viewed by many applications, including the browser. |
|||
: <tt>.svg</tt> - 99% supported. |
|||
; Music : <tt>.csound</tt> - This will be playable by TamTam... currently its XO build doesn't provide a way to save or load sound files, however. |
|||
: <tt>.ogg</tt> - See other common audio formats below; can be played by Helix or Gstreamer, not part of the current build. |
|||
: <tt>.mp3</tt>, <tt>.wav</tt> - These can be played by Helix or Gstreamer, standalone or as a browser plugin, when they are installed. |
|||
: <tt>.rm</tt>, <tt>.ra</tt> - This can be played by the Helix plugin when installed with a RealAudio codec. |
|||
: ''Currently, audio files selected in the browser will launch a player if it is present.'' |
|||
; Video : <tt>.ogg</tt> - Can be played by Helix or Gstreamer, standalone or as a plugin. A [[Helix Media Activity|Helix activity]] is now in the build. can now be downloaded in a few steps. To play video, please download this activity along with some videos (see for instance [http://dev.laptop.org/pub/content/Library/media/PL_10_20_019w.mov this video]). |
|||
: <tt>.mpeg</tt>, <tt>.mov</tt>, <tt>.wmv</tt>, <tt>.rm</tt> - See above. |
|||
; Helix : The [[Helix Media Activity]] has more information about media activity |
|||
; Python : The [[Develop]] activity will provide one way to view python files; the 'view source key' another. |
|||
; Javascript : This will viewable the same way page source can be viewed through the browser. |
|||
; Etoys projects : <tt>.pr</tt> files automatically launch etoys from the browser. |
|||
If you have a question about a file format that is not listed above, ask it on the [[Talk:Creating_a_content_bundle&action=edit|talk page]]. |
|||
===Visual Formatting=== |
|||
The second step of the formatting process is to make sure that your collection displays correctly on the XO. (The small screen can sometimes lead to unexpected formatting and display issues). |
|||
The easiest way to test the visual display of your material is to view it on an XO. If you don't have access to an XO-- or to another person who has one-- you can install and run the Sugar emulator on your computer. [[Emulating the XO]] has installation instructions. |
|||
===Disk usage=== |
|||
The XO's filesystem invisibly compresses files (poorly) to save space. So you may be using less disk space than you think. Text files are compressed about 50%. Other media are basically unchanged. If you are curious, there are somewhat difficulty to apply instructions in [[JFFS2]] to measure likely disk usage. |
|||
==Packaging Content== |
|||
Once you've selected and formatted your content, the last thing to do is to package it as a bundle. |
Once you've selected and formatted your content, the last thing to do is to package it as a bundle. |
||
=== Bundle |
=== Bundle structure === |
||
A collection or library bundle is a directory compressed as a <tt>.zip</tt> file renamed to end in <tt>.xol</tt>. (.xo and .xol formats are planned to merge, in which case a collection in a bundle will be identified by the "library" subdirectory and its "library.info" file.) |
|||
[[Image:stories-index.jpg|thumb|Sample <tt>index.html</tt> file: Stories. This index page uses the default <tt>library.css</tt> file. [http://dev.laptop.org/pub/content/library/literature/index.html Source]]] |
|||
Each bundle must contain a single top-level directory which has the same name as the bundle (minus the <tt>".xol"</tt> extension). All other files in the bundle ''must'' be within this directory. The top-level directory must also contain a subdirectory called <tt>library</tt> that contains certain configuration files. |
|||
[[Image:booklist-index.jpg|thumb|Sample <tt>index.html</tt> file: International Children's Digital Library. This index page uses its own css files. [http://dev.laptop.org/pub/content/library/icdl/index.html Source]]] |
|||
Here is an example of a library bundle for a collection called "dictionary.xol": |
|||
A content bundle is a directory compressed as a <tt>.zip</tt> file, renamed to end in <tt>.xol</tt>. Each content bundle must contain an index page called <tt>index.html</tt>, as well as a subdirectory called <tt>library</tt> that contains certain configuration files. Here is an example of a content bundle for a collection called "Dictionary": |
|||
dictionary/ |
|||
Dictionary.xol/ |
|||
A/ |
A/ |
||
aardvark.html |
aardvark.html |
||
abacus.html |
abacus.html |
||
acacia.html |
acacia.html |
||
... |
|||
B/ |
B/ |
||
balloon.html |
balloon.html |
||
... |
|||
C/ |
C/ |
||
... |
... |
||
Line 106: | Line 76: | ||
library.info |
library.info |
||
library-dictionary.jpg |
library-dictionary.jpg |
||
library.xml |
|||
library.css |
|||
contents |
contents |
||
contents.sig |
contents.sig |
||
index.html |
index.html |
||
; '''<tt> |
; '''<tt>dictionary/</tt>''' : The top-level directory, which has the same name as the bundle itself (minus the <tt>".xol"</tt> extension). |
||
; '''<tt>library/</tt>''' : This directory contains all the metadata associated with the collection. It includes several configuration files which are discussed below in [[ |
; '''<tt>library/</tt>''' : This directory contains all the metadata associated with the collection. It includes several configuration files which are discussed below in [[Creating_a_collection#Configuration_Files|configuration files]]. |
||
; '''<tt>index.html</tt>''' |
; '''<tt>index.html</tt>''': This is the top-level navigation page for the collection. The <tt>index.html</tt> page is the page that is displayed in the main frame of the reader when a child selects the collection from the library sidebar. |
||
=== Configuration files === |
|||
: At right are two examples of <tt>index.html</tt> pages. The first is a standard index page auto-generated from a <tt>library.xml</tt> file using the default library style sheet. The second is an index page adapted from a pre-existing digital collection that uses its own organization scheme and style sheets. For additional examples of index pages, visit the online version of the [http://dev.laptop.org/pub/content/library/ OLPC Library]. For information about various configurations of index pages, xml files, and style sheets, keep on reading! |
|||
: ''Note: XML automation is not yet in place, so for now, content bundles MUST provide a static index.html page. |
|||
=== Configuration Files === |
|||
The "<tt>library</tt>" directory contains all the metadata associated with the collection. It includes the following files: |
The "<tt>library</tt>" directory contains all the metadata associated with the collection. It includes the following files: |
||
; <tt>library.info</tt> : The <tt>library.info</tt> file is a text file that follows a key/value pair format. It contains information about the source, version, language, and subject of the collection (among other things). [[Sample library.info file]] is an example |
; <tt>library.info</tt> : The <tt>library.info</tt> file is a text file that follows a key/value pair format. It contains information about the source, version, language, and subject of the collection (among other things). [[Sample library.info file]] is an example and more-or-less the definitive documentation of this format, with information about required and optional entries. |
||
; <tt>library-dictionary.jpg</tt> (optional): This is the icon that represents the collection in the library navigation sidebar. The icon should have the same name as the collection's <tt>.xol</tt> file, except with <tt>library-</tt> at the front. The icon can be in any number of supported file formats, including SVG, JPEG, PNG, and GIF. See [[Choosing image formats]] for more information. |
|||
:''Note: This may not need to exist, since icons appear at the category level, not the level of individual collections. |
|||
; <tt>library.xml</tt> (optional): If you choose not to provide a customized <tt>index.html</tt> page for your collection, you must provide this file. [[Sample library.xml file]] is an example. <tt>[[Library.xml]]</tt> is the generic version, with information about various elements and attributes. |
|||
; <tt>library.css</tt> (optional): If you choose not to provide a customized <tt>index.html</tt> page for your collection but would still like to customize the look and feel of your collection, you can include a <tt>library.css</tt> file in your content bundle. [[Sample library.css file]] is an example. <tt>[[Library.css]]</tt> is the generic version, with information about customizable classes and IDs. |
|||
: ''Note: If you do not provide your own style sheet, the default values will be used.'' |
|||
=== Language and Localization === |
|||
''Library localization is still in development. At this point, just indicate the language(s) of your collection in the <tt>locale</tt> field of the [[Sample library.info file|library.info file]].'' |
|||
=== Packaging Instructions === |
|||
==== step by step ==== |
|||
1. Look at your content, and make sure that no top-level directories are named <tt>library/</tt>. |
|||
: You can use [http://crank.laptop.org/~lauren/libraryInfo/ this web form] to create a library.info file for your bundle. |
|||
2. Make a directory for your content, with the name you want to give your bundle. (Let's call it <tt>dictionary/</tt> for the sake of example.) |
|||
=== Localization === |
|||
3. Copy your content files (with any folder structure you like) into <tt>dictionary/</tt>. |
|||
Collections tend to rely much more heavily on text than code, and often the right way to localize something fully is to make a separate bundle for each language (even for some of the activity bundles that now have twenty localizations, the bulk of their size is taken up by their locale materials). |
|||
4. Within <tt>dictionary/</tt>, make a second directory called <tt>library/</tt>. |
|||
Currently, we do not offer tools for any other option. Simply indicate the language(s) of your collection in the <tt>locale</tt> field of the [[Sample library.info file|library.info file]]. |
|||
== Packaging a collection == |
|||
6. If you would like to supply an icon for your content bundle (see [[Creating_a_content_bundle#Configuration_Files|configuration files]] above), copy this icon (<tt>.svg</tt>, <tt>.jpg</tt>, <tt>.gif</tt>, or <tt>.png</tt>) into the <tt>library/</tt> directory and rename it <tt>library-dictionary</tt> (with the appropriate format suffix). |
|||
=== Step by step === |
|||
7. Decide whether: |
|||
* You want to use standard OLPC formatting (possibly with minor changes to colors and styles) in displaying your content on the XO. |
|||
* You want to customize the display children see when using the XO to view your content. |
|||
# Make sure that no top-level directories in your content are named <tt>library/</tt>. |
|||
8a. If you want to use standard OLPC formatting: |
|||
# Make a directory for your content, with the name you want to give your collection. (Let's call it <tt>omnium/</tt> for the sake of example.) |
|||
:1. Create a text file <tt>library.xml</tt> within <tt>library/</tt>. |
|||
# Copy your content files (with any folder structure you like) into <tt>omnium/</tt>. |
|||
:2. For every item in your content bundle that you want displayed to students, include items in your <tt>library.xml</tt> file that mirror those in the example [[Library.xml]] file. |
|||
# Within <tt>omnium/</tt>, make a second directory called <tt>library/</tt>. |
|||
:3. If you want to change the colors and styles of the OLPC formatting, create a text file <tt>library.css</tt> within <tt>library/</tt>that gives your preferred css. |
|||
# Within <tt>library/</tt>, create a text file called <tt>library.info</tt> and give it content as in the [[sample library.info file]]. |
|||
# Create a text file <tt>index.html</tt> in <tt>omnium/</tt>. |
|||
# In <tt>index.html</tt>, write html code providing links to all your content items. |
|||
# Zip up <tt>omnium/</tt>, with all its subdirectories into a <tt>.zip</tt> file with the same name as your bundle (eg <tt>omnium.zip</tt>). |
|||
# Rename the zip file as a <tt>.xol</tt> file (e.g. <tt>omnium.xol</tt>). |
|||
Voila! The <tt>.xol</tt> file is your collection's library bundle. |
|||
8b. If you want to use your own customized formatting: |
|||
:1. Create a text file <tt>index.html</tt> in <tt>dictionary/</tt>. |
|||
:2. In <tt>index.html</tt>, write html code providing links to all your content items. |
|||
== Bundle hosting == |
|||
9. Then zip <tt>dictionary/</tt>, with all its subdirectories into a <tt>.zip</tt> file with the same name as your bundle (eg <tt>dictionary.zip</tt>). |
|||
To host your own bundles, you must tell your web server about the bundle mime types Sugar expects. You need to add the following to your web-server configuration (<tt>/etc/apache/mime.types</tt>, or <tt>/etc/mime.types</tt> on Ubuntu systems): |
|||
application/vnd.olpc-sugar xo |
|||
10. Rename the zip file as a <tt>.xol</tt> file (e.g. <tt>dictionary.xol</tt>). |
|||
application/vnd.olpc-content xol |
|||
If you want to host your bundles elsewhere, you are welcome to upload them to this [[wiki]] or to <tt>dev.laptop.org</tt> (you can [[requesting an account|request an account] there if you need shell access), which will set the mime-type properly when they are later downloaded. |
|||
Voila! The <tt>.xol</tt> file is your content bundle. |
|||
== FAQ == |
|||
==== using a setup.py script ==== |
|||
''needs testing'' |
|||
==== Can I repackage an activity as a library bundle? ==== |
|||
Make sure all of your files are listed in the bundle manifest (explained in Sugar Activity Tutorial), and create a setup.py file with the following code: |
|||
Yes -- but only for the purposes of providing navigation through the elements of the activity, as opposed to actually executing it. |
|||
<pre> |
|||
#!/usr/bin/env python |
|||
try: |
|||
from sugar.activity import contentbundlebuilder |
|||
contentbundlebuilder.start("YourBundleName") |
|||
except ImportError: |
|||
import os |
|||
os.chdir('..') |
|||
os.system('cat YourBundleName/contents | zip YourBundleName.xol -@') |
|||
os.system('mv YourBundleName.xol ./YourBundleName') |
|||
os.chdir('YourBundleName') |
|||
</pre> |
|||
To package your activity as a library bundle, you just need to add the <tt>index.html</tt> page and the <tt>library</tt> directory (including relevant configuration files) to your existing activity bundle. Then, rename it as a <tt>.xol</tt> file, and you should be all set. If you are modifying a bundle on an XO, you will also need to move it from /home/olpc/Activities to /home/olpc/Library . As mentioned above, there are plans to merge the xo and xol formats, so that no repackaging is needed for a bundle to be interpreted in both ways. |
|||
This way you can run |
|||
==== How do you open an XOL file?==== |
|||
./setup.py |
|||
An XOL file is a zip file with .xol extension instead of .zip. You can extract the contents using any unzip utility. If you want to install a content bundle, you do it just like any other activity. Download it with the browser, then resume it from the Journal. The new bundle will show up the next time you open the Browse Activity or if you refresh the browser's homepage. |
|||
====How do you uninstall a collection?==== |
|||
without sugar installed, and at the end find a zipped up .xol file ready for you to install on an XO or emulator. |
|||
See [[Collections#Removing a collection]]. |
|||
====How do I upload my collection to this wiki, and host it here?==== |
|||
=== FAQ === |
|||
You can upload it by clicking "Upload file" in the left margin, and entering the filename and description on the page that comes up. Then, after you hit the upload button, it'll be hosted on the OLPC Wiki. Then, to get it into the index of Collections, you can edit that page by hand as well. (you can also try using [[OLPC:Semantic Mediawiki|Semantic Mediawiki]] to add your entry to the table.) |
|||
== See also == |
|||
'''Can I package an activity as a content bundle?''' |
|||
* [[Creating an activity]] |
|||
* [http://sugarlabs.org/go/Activities/InfoSlicer InfoSlicer] is a tool to create a collection from content on the Internet. |
|||
[[Category:Content]] |
|||
Yes! Content bundles are designed to coexist with activity bundles. To package your activity as a content bundle, you just need to add the <tt>index.html</tt> page and the <tt>library</tt> directory (including relevant configuration files) to your existing activity bundle. Then, rename it as a <tt>.xol</tt> file and you should be all set. |
|||
[[Category:File formats]] |
|||
[[Category:HowTo]] |
Latest revision as of 22:01, 29 June 2011
If you would like to package a collection of mostly-static content for use on the XO, follow the instructions below to create a collection (sometimes called a library or content bundle). When you're done, you can add your new bundle to the Collections page so that it can be viewed and downloaded by children worldwide.
Upon installation it will appear in the Library.
If you'd like to help out by creating collections but are unsure of where to begin, see the list of new bundle ideas.
Overview
The OLPC Library is the set of content and materials (outside of the core OS and Activities) that ships on the XO laptop and/or school server (the exact set of content shipped with the laptop is usually determined by the organization distributing the laptops within a specific country). In order to make your content available to OLPC projects worldwide, you must create a self-contained bundle for your content. This page describes the process of creating such a bundle, providing the information you need to select, format, and package a collection.
Note: These instructions explain how to package browsable content for the OLPC library. Materials in a collection that need to be run by an Activity other than Browse will have to have a mime-type registered with the Browse activity so they can launch from there. Activities may be part of content packages for the library as well, for instance as sample code to be read. For more information on packaging source code, as well as other questions you may have, skip down to the #FAQ.
Collections currently unpack into a directory under /home/olpc/Library. Future improvements to the current bundle format are intended to allow a single bundle to contain both an activity and a collection (including, for instance, default help/readme materials).
'If you plan to host your own bundles, please note the #bundle hosting guidelines.
Feedback
As you create your bundle, please note any puzzles or problems you encounter, as well as any thoughts for improvement that you might have. You can leave feedback on the Talk:Creating a collection page.
Selecting content
The first step to creating your collection is to determine what content should be included. In some cases, this is easy: everything! In other cases, there are additional considerations:
- Size
- How big is your collection? Keep in mind the limited disk space available on the XO. You may wish to bundle only a subset of your content, perhaps figuring out a way to make the content available entirity on the school server.
- Note: The XO-1's filesystem invisibly compresses files to save space, so you may be using less disk space than you think. Text files are compressed about 50%. Other file formats are basically unchanged. If you are curious, there are (somewhat difficult to apply) instructions in JFFS2 to measure likely disk usage.
- Quality
- Does your collection have a rating system in place? If so, consider including only top-rated material in your collection. Otherwise, think about "curating" a selection of high quality material to be included in your bundle (or bundles).
- Relevance
- Is your entire collection relevant to children? If so, terrific! If not, consider including only material that will help children learn, explore, and expand their worlds.
- Language issues
- Does your collection contain material in multiple languages? We hope it does! To the greatest extent possible, please give preference to materials that exist in multiple languages, or that can be easily translated by our localization team.
- Licensing issues
- What kind of copyright exists on the material in your collection? Do you have legal permission to archive and distribute it? Please be sure to review the licensing terms of your collection. For guidance on licensing, see licenses.
Formatting content
Once you've determined the material you'd like to include in your collection, you'll need to format it for use on the XO.
File formats
The first step of this process is to make sure that all of the content you plan to include is accessible from a HTML index page, or a series of linked HTML pages. HTML is currently the only format directly supported by the library, but you can then include hyperlinks to files of any format supported by the activities present on the XO. When clicked, the content will be presented as a download, copied into the journal, then opened in the appropriate activity.
For example, for a simple content bundle including 5 PDF files, you would have to additionally write a HTML index page, providing hyperlinks and descriptions of the 5 PDF files that make up the bundle.
Visual formatting
The second step of the formatting process is to make sure that your collection displays correctly on the XO. The small screen can sometimes lead to unexpected formatting and display issues. Also test it with the screen rotated and in e-book mode (with the screen rotated and lowered).
The easiest way to test the visual display of your material is to view it on an XO. If you don't have access to an XO — or to another person who has one — you can install and run the Sugar emulator on your computer. Emulating the XO has installation instructions.
Packaging content
Once you've selected and formatted your content, the last thing to do is to package it as a bundle.
Bundle structure
A collection or library bundle is a directory compressed as a .zip file renamed to end in .xol. (.xo and .xol formats are planned to merge, in which case a collection in a bundle will be identified by the "library" subdirectory and its "library.info" file.)
Each bundle must contain a single top-level directory which has the same name as the bundle (minus the ".xol" extension). All other files in the bundle must be within this directory. The top-level directory must also contain a subdirectory called library that contains certain configuration files.
Here is an example of a library bundle for a collection called "dictionary.xol":
dictionary/ A/ aardvark.html abacus.html acacia.html ... B/ balloon.html ... C/ ... library/ library.info library-dictionary.jpg contents contents.sig index.html
- dictionary/
- The top-level directory, which has the same name as the bundle itself (minus the ".xol" extension).
- library/
- This directory contains all the metadata associated with the collection. It includes several configuration files which are discussed below in configuration files.
- index.html
- This is the top-level navigation page for the collection. The index.html page is the page that is displayed in the main frame of the reader when a child selects the collection from the library sidebar.
Configuration files
The "library" directory contains all the metadata associated with the collection. It includes the following files:
- library.info
- The library.info file is a text file that follows a key/value pair format. It contains information about the source, version, language, and subject of the collection (among other things). Sample library.info file is an example and more-or-less the definitive documentation of this format, with information about required and optional entries.
- You can use this web form to create a library.info file for your bundle.
Localization
Collections tend to rely much more heavily on text than code, and often the right way to localize something fully is to make a separate bundle for each language (even for some of the activity bundles that now have twenty localizations, the bulk of their size is taken up by their locale materials).
Currently, we do not offer tools for any other option. Simply indicate the language(s) of your collection in the locale field of the library.info file.
Packaging a collection
Step by step
- Make sure that no top-level directories in your content are named library/.
- Make a directory for your content, with the name you want to give your collection. (Let's call it omnium/ for the sake of example.)
- Copy your content files (with any folder structure you like) into omnium/.
- Within omnium/, make a second directory called library/.
- Within library/, create a text file called library.info and give it content as in the sample library.info file.
- Create a text file index.html in omnium/.
- In index.html, write html code providing links to all your content items.
- Zip up omnium/, with all its subdirectories into a .zip file with the same name as your bundle (eg omnium.zip).
- Rename the zip file as a .xol file (e.g. omnium.xol).
Voila! The .xol file is your collection's library bundle.
Bundle hosting
To host your own bundles, you must tell your web server about the bundle mime types Sugar expects. You need to add the following to your web-server configuration (/etc/apache/mime.types, or /etc/mime.types on Ubuntu systems):
application/vnd.olpc-sugar xo application/vnd.olpc-content xol
If you want to host your bundles elsewhere, you are welcome to upload them to this wiki or to dev.laptop.org (you can [[requesting an account|request an account] there if you need shell access), which will set the mime-type properly when they are later downloaded.
FAQ
Can I repackage an activity as a library bundle?
Yes -- but only for the purposes of providing navigation through the elements of the activity, as opposed to actually executing it.
To package your activity as a library bundle, you just need to add the index.html page and the library directory (including relevant configuration files) to your existing activity bundle. Then, rename it as a .xol file, and you should be all set. If you are modifying a bundle on an XO, you will also need to move it from /home/olpc/Activities to /home/olpc/Library . As mentioned above, there are plans to merge the xo and xol formats, so that no repackaging is needed for a bundle to be interpreted in both ways.
How do you open an XOL file?
An XOL file is a zip file with .xol extension instead of .zip. You can extract the contents using any unzip utility. If you want to install a content bundle, you do it just like any other activity. Download it with the browser, then resume it from the Journal. The new bundle will show up the next time you open the Browse Activity or if you refresh the browser's homepage.
How do you uninstall a collection?
See Collections#Removing a collection.
How do I upload my collection to this wiki, and host it here?
You can upload it by clicking "Upload file" in the left margin, and entering the filename and description on the page that comes up. Then, after you hit the upload button, it'll be hosted on the OLPC Wiki. Then, to get it into the index of Collections, you can edit that page by hand as well. (you can also try using Semantic Mediawiki to add your entry to the table.)
See also
- Creating an activity
- InfoSlicer is a tool to create a collection from content on the Internet.