PBwiki Importing HOWTO

So you'd like to move your wiki into PBwiki, eh wot? This guide, written for programmers looking to export data in a PBwiki-friendly way, should help you import your wiki easily to PBwiki.

There are several main components to a wiki's information:

• Users: Who has access to the wiki? Are they an admin or a contributor? Who is receiving notifications on wiki changes?
• Wiki Meta: What's the wiki called? Are there any special keywords/tags? How would you describe the wiki? Is it French? Turkish? What is the default timezone for the wiki? Is the wiki accessible by way of a different domain name?
• Wiki Pages: What's the content of the wiki page? Is it in HTML or PBwiki format? Who last edited it? (name+email) When was it edited?
• Attachments: What files are attached to this wiki?
• Tags: What pages are tagged how?

Special page names in PBwiki world:

• FrontPage - this is the default front page of a wiki. it is MANDATORY.
• SideBar - this optional page is displayed as a sidebar on every page in the wiki.
• QuickStart - this optional page is shown as a tab in the sidebar.

Reserved page names: (you can't use these!)

• AllPages
• FindPage
• RecentChanges

If your wiki system uses a different page name for its front page, I suggest your export system rename that page to FrontPage and update any links that directly link to it. For instance, if your system uses "FirstPage" as its front page, update any pages that directly link to "FirstPage" to either link to "/" or "/FrontPage" and rename FirstPage to FrontPage.

PATH STRUCTURE

WIKINAME/meta.pbj           (contains the metainformation for the wiki)
         pages/             (contains all of the wiki pages)
               PAGENAME/    (contains all of the revisions of a page)
                        119238492 (unix timestamp-encoding of revision, filedesc later)
                        120389238
                        current (a symlink to the most recent revision)
                        ...
         discussion/           (comments on the page)
                 PAGENAME/
                        117112322 (unix timestamp-encoded revision, see below)
                        ....
         files/             (contains all attached files to the wiki)
               somefile.pdf (some attached file, stored raw, no metadata)
         tags/              (described below - see TAGS)
         scratch/           (described below - see NOTIFICATIONS)

META.PBJ

The meta.pbj is a file containing all of the meta information for the wiki. It consists of a sequence of key:value pairs, where the key is separated from the value by the first colon in the line (no spaces) and where pairs are separated by a Unix newline. Below is a sample meta.pbj. Explanations follow.

wikiname is mandatory and describes the name of the wiki. Namely, the wiki will be accessible at WIKINAME.pbwiki.com.
create_time gives the Unix timestamp time at which the wiki was first created.
pagetime is the Unix timestamp for when any page on the wiki was last modified.
email is the email address of the wiki's creator (and primary admin)
skin describes which skin the wiki uses (skin5 is the default - we could talk about creating a custom skin for your wiki)
passhash is a simple unsalted SHA1 hash of the admin password for the wiki.
creator_ip is the original creator's IP address
tz is the default timezone difference of the wiki from GMT given in hours. Half-hours are expressed as .5 and Quarter-hours as .25.
lang is the ISO 639 two-digit language code for the wiki.
title is the title of the wiki as displayed in the upper-left corner.
dir is the textual flow direction - either rtl or ltr. It should be ltr for all but wikis in Hebrew, Farsi, Arabic, or other right-to-left languages.
private is set to 1 for a private wiki (where a login is required in order to even view the pages) and 0 for a public wiki (where a login is required in order to make edits, but anyone can view)
about is the wiki's long description, displayed in a directory of wikis and shown to users at time of login.
notes is a freeform field not used by the code and not shown to users.

WIKI PAGES

The name of the file should be the timestamp of the revision. The file itself consists of a metadata header followed by the actual data of the page revision itself. A sample wiki page follows:

Here we see the same key/value pair format as used in meta.pbj, delimited by a
line that contains ONLY and EXACTLY the string "--- Data Follows ---", after
which the page data begins immediately. If the page data is not in PBwiki text
(which is the default) add to the key/value headers "content-type:text/html".

FILES

File attachments are stored raw with no metadata in the files/ subdirectory.

TAGS

Tags may be added to a page to assist navigation. They are not stored inline with the other page metadata, however, for efficiency's sake. WIKINAME/tags/tags_page/PAGENAME.tags contains a PHP serialized object containing the list of tags applicable to that page.

Here's an example tags file:

DISCUSSION

Discussion (comments on particular pages) are stored much like pages themselves

Contents of the file "discussion/FrontPage/1163281754"

USERS

Most PBwiki users simply use a wiki-wide access password to log into their wikis. This makes PBwiki unique, since on most wikis there is no concept of a user-specific login per se. We do have PBwiki Identities, which allow a user to log into all of their PBwikis at once, but this is less frequently used. Our user-specific access control system is our of band with our wiki data and is stored in a database.

The best way to import a list of users to us would be to give us a list of users in the following fashion, presuming you have some internal "USER ID" field (which could be the user's primary email address). Give a directory of files, each one of which represents a unique user, naming these files as your internal user ID. An example entry, if you have a user #415 named "John Doe" with email john@doe.org.

In userlist/415:

Where the passhash is an unsalted SHA1 of the user's password.

To express access controls, in useracl/415 could be:

perm is one of "deny","read","write","mod","admin","owner","invited", or "requested". "mod" means moderator-level, which allows a user to make irreversible changes, such as deleting pages, deleting files, and deleting revisions. But a moderator cannot change wiki-wide settings.

NOTIFICATIONS

Some users may wish to be notified via email when a wiki's content is updated. Other users may only wish to be notified when a specific page's content is modified.

All-wiki notifications are stored in WIKINAME/scratch/notification/AllPages as a PHP serialized array. Here is an example:

This indicates that the wiki has a single notification subscriber, that this subscriber has never gotten a notification before (last is 0), and that the maximum interval for notifications is once a second. No notifications have been skipped and this user was given a "welcome" email indicating their new subscription.

 Create your own business wiki!Support CommunityPublic, Platinum wiki Privacy Policy RSS