The Pandora Quickstart Guide

Written by: Julian I. Kamil

Installation and configuration

The only prerequisite to Pandora is Ruby 1.8.4. The distributed package includes other external libraries that it depends on. To get up and running quickly, simply follow these steps:

1 Unpack the latest package in a directory of your server:

        tar xvfz pandora-latest.tgz

2 Start the server:

        ruby server.rb

On a fresh installation, this will start an interactive session to create a Pandora configuration file and a new publisher user account. On subsequent invocations, it will start Pandora with the existing configuration file.

Now you can point your web browser, preferably Firefox or Camino, to port 8181 of your server, and view the bundled Pandora book like this:

http://localhost:8181/pandora/Pandora

Creating the book publisher and other user accounts

You need to create at least one user account, the ‘publisher’ account, which you will use to administer Pandora. Pandora does not allow anyone except for the publisher to create new books, so be sure to protect the password that you use for this account.

Normally, the publisher account is created the first time Pandora is run through an interactive terminal session. However, if you choose to create the configuration file manually, you will have to create the publisher account after Pandora starts using the online account registration facility, which requires that you have access to a working SMTP server. If such access is not available, you should use the interactive session to create the Pandora configuration file and the publisher account.

C:\pandora-r0-0.4.0-20060303-190024> ruby --version
ruby 1.8.4 (2005-12-24) [i386-mswin32]
C:\pandora-r0-0.4.0-20060303-190024> ruby server.rb
No Pandora configuration file 'pandora.rc' can be found.
Read 'Pandora >> Documentation / PandoraRC' to learn more about
configuration options.
You can create 'pandora.rc' with a text editor or with this interactive
session.

         Create 'pandora.rc'? [Yn]
            HTTP server port? 8181
                 Mount point? /pandora
         SMTP server address? localhost
            SMTP server port? 25
           Registration type? :manual
         Registration expiry? 7
Allow uninvited registration? yes
             Publisher email? julian.kamil@gmail.com
        Publisher first name? Julian
         Publisher last name? Kamil

Your password will be visible. Install ruby-termios 
to avoid this situation.

                    Stop now? [yN]
          Publisher password? nosecret

Creating configuration file 'pandora.rc'... done!
Creating new user account for the publisher... done!

               Start Pandora? [Yn] n

C:\pandora-r0-0.4.0-20060303-190024> cls

To create the publisher account with the online account registration facility, select the ‘Account’ menu item at the top of the page. This will bring up a registration form where you can specify your full name and a password of your choice. By default, Pandora is set to use a manual approval process, which means that applications for user accounts must be manually approved by the Pandora publisher. So check your email for a request for a new Pandora user account that you need to confirm and approve yourself!

Once you confirmed and approved the application, the user account will be created and you will be able to log in and create new Pandora books.

You can create more user accounts by repeating the same process with other email addresses or by using the ‘add_user.rb’ command line tool:

ruby tools/add_user.rb Library/Books Pandora

This command line tool is especially useful if your Pandora site does not have access to a working SMTP server.

Designating book authors, book editors, and book viewers

The book publisher can designate other registered users as book authors, who are allowed to create new pages, or book editors, who are allowed to modify existing pages.

To designate other registered users as book authors and editors, log in as a publisher, view the book for which you want to designate additional authors and editors, and select the ‘Properties’ menu.

As you can see from the contents of the properties page, you can designate book authors, editors, and viewers at either the page scope, or the book scope. Click the ‘Edit’ button either on the page or book properties to modify the settings.

If you would like to restrict the viewing of the contents of this book to a select view, you can set the book viewers to a list of email addresses that refers to the only users who will be allowed to view any part of the book. Certain pages of the book may be made available to other users simply by adding their email addresses to the list of viewers for those particular pages.

The list of editors refers to those registered users who will be allowed to modify the contents of any existing page in the book. Remember that Pandora does not allow any anonymous, non-registered user to edit the contents of any page in the book.

This is an intentional departure from the traditional Wiki principle that advocates fully open editing, which has its own benefits, as well as issues. Pandora is meant to be a tool that enables the collaborative creation of books in a more ‘architected’ fashion by some identifiable users, rather than in an ‘organic’ fashion by many anonymous users. This principle, and the scriptability of Pandora pages, are the reasons that user registration is a fundamental part of the application.

Unlike book editors and viewers, book authors can be set only at the book scope. Book authors are those registered users who are allowed to create new pages.

Creating a new book or a new page

To create a new book, select the ‘New’ menu item, which will display the ‘Create New Page’ form. In the form, type in the name of the new book, chapter, and page. To create a new page in an existing book, simply specify the name of the existing book, and a new page name in the form.

Pandora promotes several conventions that you should follow when creating new books, chapters and pages.

• Pandora is a reserved book name and chapter name that you should never use.

• Users is a reserved chapter containing home pages of the registered users of the book.

• TableOfContents is a reserved page name, which Pandora uses to display a listing of the contents of a chapter or a book. So, for example, “MobyDick » Introduction / TableOfContents”, will display the listing of pages in the chapter Introduction of the book MobyDick. Pandora displays the book contents in the chapter that has the same name as the book, which means that “MobyDick » MobyDick / TableOfContents” will display the listing of the chapters in the book MobyDick.

• SideBar and Banner are reserved page names, which Pandora uses to display the side bar and banner contents of every page. Each chapter can have their own distinct SideBar and Banner pages.

Note: In a future version, Pandora will provide a mechanism for multiple chapters to share a common SideBar and Banner pages. As of now, you can use filesystem symbolic links to achieve the same effect.

• Book, chapter, and page names are mapped to filesystem directory names and file names in a CamelCase fashion.

Attaching files to a page

To create file attachments, select the ‘Files’ menu item. If you specify a new title for the attachment, it will be used to name the file to replace the original name.

Every page has its own file attachments. To refer to a file attachment within the containing page, you can use the following Silk Veil markups:

      file:"attachment title" 
      image:"attachment title" 

The first form will create a link to the attachment, while the second will display the contents of the attachment, which should be of an image type, in the page. Don’t forget the surrounding double quotes, they are required.

Using Textile and Silk Veil markups

When editing page contents, you can use Textile and Silk Veil to mark up the text.

Textile provides very simple and relatively few constructs for marking up plain text to produce richly styled contents. Silk Veil adds markups that make it easier to link and refer to contents within a Pandora site, as well as short hand notations to a few other HTML entities.

Viewing and restoring historical revisions

Select the ‘History’ menu item to list all prior revisions of a page.

In the list, select the ‘View’ action to display the revision contents, and the ‘Restore’ action to make that revision the current one.

What else and what next?

These are the some of the features planned to be implemented in Pandora:

• Page scripting with Ruby and Pandora’s Box framework;

• Print functions that use an alternate stylesheet and produce a PDF formatted file;

• Additional history actions to allow the pruning and truncating of page revisions;

• Additional files actions to allow updating and version tracking of attachments;

• Import and export functions to allow archival and restoration of books, chapters, and individual pages;

• User preferences pages and functions to allow user-centered personalization and customization;

• Administrative pages and functions to make it even easier to administer a Pandora site;

• And a few others…

Are there features that you would like to be added to Pandora? Contact us and let us know what they are, and maybe they can be incorporated into a future version. And don’t forget, you can help making Pandora better by contributing to the project through implementing code, writing documentation, donating resources, or spreading the news and educating others about Pandora.

Thanks again for using and supporting Pandora!