Everything In Between

If your project so much as pretends to have a profit motive, I will tell you to go fuck yourself and your project.

A web developer’s introduction to the Apple WikiServer (part 1)

10 comments

I absolutely love wikis, so when Apple introduced Mac OS X Server 10.5 “Leopard,” one of the new features I was really excited about was “WikiServer” (what the Apple marketing department calls “Teams”). I’m calling this specifically the Apple WikiServer in order to avoid confusion with the pre-existing wiki plus web server package called WikiServer.

Apple WikiServer: Mac OS X Server’s built-in Intranet builder

At work, I’m finally getting the opportunity to try the Apple WikiServer out. Its strongest asset, by far, is the integration it has with Apple’s Mac OS X permission scheme. Apple WikiServer makes heavy use of the OS’s built-in user accounts to define users and groups, and the permissions those users and groups have to edit, view, and comment on pages in the wiki you create with it. And, because Leopard Server has full support for Access Control Lists, those permissions schemes can be as complex as you like.

This is very important because many large (and small) organizations have sensitive material that they’d like to keep private, or restricted to certain groups. Historically, wikis are a free-for-all. Anyone and everyone who has access to any part of the wiki can change any other part of the wiki. Recent wiki implementations such as later version of MediaWiki and some other wiki software have implemented permissions systems to allow administrative users to control access rights, but these are often complicated or require code-level configurations.

With Apple’s WikiServer, all of these permissions can be managed via the Workgroup Manager application, and because you can take advantage of the built-in ACL support, you can model your organizations permissions scheme directly in the Server OS permissions structure, giving you a much easier way to control information access. Take note, however, that like almost all other things that have to do with your Apache configurations, your Server’s Web Service will likely need to be stopped and started again for any changes you make to a wiki’s permissions take effect.

The Workgroup Manager application is also where you go to create new wikis for groups. To enable a wiki, you need to already have created a group and assigned users to that group. For instance, I created a Developer Wiki where all of the in-house developers can share tech tips, so I created a group called “Developers” and assigned individual developers, as well as the company executives (by way of the “Executives” group) to that group. The group-within-a-group technique is key, because if the company executives change, the members of the Developers group does not need to change, too. In all of Apple’s publications, Apple refers to the wikis hosted by WikiServer as an “intranet website.”

It’s clear that Apple intended this product for use within small companies, and not necessarily out on the open Internet. What follows are just a few notes I’ve compiled about how the Apple WikiServer works.

Front-end Code Generation from the Apple WikiServer WYSIWYG Editor

The Apple wikis are very nice to use. Their functionality is relatively straightforward to find and activate. However, the HTML code that the Apple wikis generate can be a little confusing. By default, new page text is entered into a semantically meaningless <div> element. This can be changed by highlighting text and then selecting “Paragraph” from the formatting toolbar. Subsequent paragraphs that are typed seem to then use <p> elements. However, some paragraphs revert back to <div>s when I used it, and I’m still not sure why or when this occurred.

On the plus side, so far, all the browsers I’ve used with the Apple WikiServer function the same way. This include Firefox 2, Safari 3.1, and Internet Explorer 6 and 7.

Typing actual code and having it marked up as such can’t be done in the GUI formatting toolbar to select a <code> element. The “Monospace” item in the text formatting toolbar creates <pre> elements and <pre> elements only. However, Apple does provide a “Switch to HTML view” button (the arrow brackets button) and one can enter standard HTML, including <code>…</code> elements in that view, and then switch back. This behaves perfectly on all browsers except Internet Explorer, in which your text area field shows no line breaks whatsoever.

Apple’s WYSIWYG editor handles escaping special characters when those special characters have HTML entity reference equivalents, such as double quotes (“), arrow brackets (< and >), and ampersands (&). It does not seem to handle Unicode characters, such as the ellipses in the prior paragraph. However, such Unicode characters need not be escaped as long as the document’s character set is UTF-8 (or UTF-16), which the Apple WikiServer specifies and supports out of the box.

Pressing the Return key twice causes the Apple wiki to generate an empty <div> or <p> element with an explicit break (<br />) inside of it. One can deduce that this is a design choice in order to help transition users who are used to plain <textarea /> inputs to Apple’s WYSIWYG editor. It’s also the only way to space paragraphs properly if the user hasn’t selected the “Paragraph” option in the text formatting toolbar. Otherwise, simply hitting the Return key once is enough to space paragraphs apart properly (i.e., the functionality is equivalent to the way Microsoft Word or Pages handles paragraph breaks).

Interestingly, the “Enter URL…” functionality form the toolbar is smarter than one might first assume. For instance, it recognizes email address and prepends a mailto: scheme to the link if it finds one. This is contrary to what the Apple-provided manual states, which tells you to enter the “mailto:” portion as part of the URL. In fact, you should omit this, else your final mailto link will actually read “mailto:mailto:your.email@address.com”.

This means linking to “mailto: links” is as simple as typing an email address. Similarly, the WYSIWYG doesn’t complain if your fully-qualified URL doesn’t include a scheme, so you can enter //apple.com/ and the subsequent link is generated as <a href="//apple.com/">Link text</a>. This is one step above and beyond even WordPress’s new WYSIWYG editor, which forcefully prepends an http: scheme to URLs without one.

For the most part, copy-and-paste works as expected, except in cases where the WYSIWYG editor does not understand the current formatting, such as a specific font and (and this is a biggie) for links. At first, the editor will appear to show that the formatting (including links) is saved, but when you actually save the page, only the formatting that the WYSIWYG editor understands is actually saved. Worse, all your links are turned into underlined—but unlinked—text. In short, this means that if you are copying and pasting page content that contains links, you need to do so in the HTML view of the page editor.

Inexplicably, the editor generates <i> and <b> tags for italics and bold, instead of the preferred <em> and <strong> elements. I’m not sure I understand why this is the case. There does exist a an “emphasis” option in the toolbar, as does an “important” option, but these generate strange spans instead. The “Important” item wraps the selected text inside a <span class=”Apple-style-span custom_forecolor_important”>…</span> and the “Emphasis” item wraps the selected text inside a <span class=”Apple-style-span custom_forecolor_emphasis”>…</span> element.

There’s also one other item, “Highlight,” which wraps the selected text inside of a <span class=”Apple-style-span custom_backcolor_highlight”>…</span> element.

The only explanation that makes sense to me, after much speculation, is that perhaps Apple does not want to encode semantic information such as what <em> and <strong> would imply from users who use a WYSIWYG editor. This shows either a blatant distrust of users or incredible foresight. I’m not sure which.

Page names and URLs

Currently, the search functionality built into Apple’s WikiServer only searches on the text of a page’s title.

Apple’s WikiServer generates unique page names for each new wiki page. These names consist of two parts, but only one seems to make any difference. For example, if you create a new Wiki page called “Hello”, you might get an address in your web browser’s location bar that looks like this:

http://your-server.local/groups/your-group-name/wiki/1d06a/Hello.html

Most of this is standard URL stuff (the protocol, the server address), and most of the rest is self-explanatory (the group name, the wiki section). The important bits in this URL are the last two:

  • 1d06a
  • Hello.html

Obviously, “Hello.html” came from the fact that you named your new page “Hello”. WikiServer appended “.html” on its own. The other bit, the short string of random characters, is a unique identifier used across all of this group’s web services (the wiki, blog, calendar, and mail list, if these other services are enabled) to uniquely identify this page. What’s interesting about this is that only the unique string of characters seems to matter in regards to accessing the page. That is, if you next ask for:

http://your-server.local/groups/your-group-name/wiki/1d06a/Some-Random-Page.html

you’ll still get the same “Hello.html” page from before, even though you’re seemingly asking for “Some-Random-Page.html”. In fact, it doesn’t seem to matter what you replace “Some-Random-Page” with. So long as there is some text in that part of the URL, that the URL ends with “.html” and that the unique identifier remains untouched, you’ll always end up retrieving the “Hello.html” page.

This means that if you change this page’s name later to, for instance, “Hello world”, old links that point to “…/1d06a/Hello.html” will continue to work, even while new links will start to point at “…/1d06a/Hello_world.html”. From a usability perspective, this is simple and effective; it ensures that users have a reminder of what the page is about by looking at the last part of the URL. However, once page names change, it becomes a bit non-optimal, because the same page can be referred to by multiple names—a “no-no” in the SEO world and a practice discouraged by most semantic-web types.

I would imagine that Apple made this design decision because the company envisioned their WikiServer to be used, again, primarily in intranet and SOHO environments, and as a result are not too concerned with search engine optimization. As an aside, this unique string is also how Apple’s WikiServer identifies the stored content on the filesystem. Read on for more details.

Hacking the Apple WikiServer

There isn’t a lot of information out on the Web right now about how to work with the WikiServer, especially for developers. Therefore, some digging is needed. After a bit of research, I discovered the following key directories that the WikiServer uses. They are as follows:

  • /usr/share/collaboration - This has a few developer tool support files as well as the majority of the client-side code for the Wiki (javascripts, etc).
  • /usr/share/wikid - This directory holds the Python sources and compiled bytecode for all the “Teams” components (including wiki, blog, calendar, etc.). It seems to run on Twisted and a number of other familiar-sounding components.
  • /Library/Application Support/Apple/WikiServer - This is where most the data is stored, inside of plist files and a few others. The Themes subdirectory here is where Apple recommends that look-and-feel changes be made.
  • /Library/Collaboration – This is the default data storage location for all the “Teams” components. The actual content of the wikis and blogs will be kept somewhere in this directory, which means that this is the directory you want to backup to backup the content of your wikis. This location is the only user-configurable one of the bunch. To change it, change the “Data Store” value in Server Admin. (A more detailed listing of this directory hierarchy is available on page 62 of the Mac OS X Server Web Technologies Administration For Version 10.5 Leopard manual.)

If you take a peek at the /Library/Collaboration directory, and follow that into the Groups/your-group-name/wiki directory, you’ll find a list of all the pages in your wiki stored as .page bundles, identified with the unique character string WikiServer generated when it first created the page.

It should be noted that anything in the /usr/share directory will likely be overridden whenever Apple releases an update that modifies the WikiServer. As a result, any and all changes you make to WikiServer’s templates or themes should be done by creating new files in the /Library/Application Support/Apple/WikiServer/Themes directory.

It’s interesting to note that the WikiServer seems to use Python for its back-end processing. This may open up some interesting integration possibilities for Python programmers in the future.

More help eslewhere

Even though Apple WikiServer is relatively new, there’s a load of helpful information about it on the web. Most of the good stuff is on Apple’s own Discussions boards, but more and more info is beginning to show up on blog posts. A Google search should give you what you need. For the really lazy, however, here are a few helpful items:

This was just a brief introduction to WikiServer from some notes I’ve been collecting in my experimentations, but I hope it’s helpful to someone somewhere. Cheers. Or, continue to Part 2.

Written by Meitar

April 5th, 2008 at 5:10 am

10 Responses to 'A web developer’s introduction to the Apple WikiServer (part 1)'

Subscribe to comments with RSS or TrackBack to 'A web developer’s introduction to the Apple WikiServer (part 1)'.

  1. Very nice! Thanks!

    Jon

    6 Apr 08 at 3:12 AM

  2. Great infos.

    It doesn’t seem that Apple is promoting Leopard server quite heavily or is so in the US ?

    Just a technical question …

    In our case, the wiki and blog activation doesn’t work in the Services and Groups panel. We are able to check it there but if you try to set a group there it doesn’t stay (after a while it clears up).
    Going in the workgroup manager the sites with the wikis allowed doesn’t appaers in the enable the following services …

    Didi you allready came accross something similar ?

    Thanks for the (possible) answer !

    Didier

    Didier

    6 Apr 08 at 9:27 AM

  3. Didier,

    In our case, the wiki and blog activation doesn’t work in the Services and Groups panel.

    I’ve not encountered an issue with a setting “not sticking.” Are you sure you’ve hit “Save” at the bottom of the window? Apple’s Server Admin and Workgroup Manager are notorious for not applying saves like the rest of the GUI tools.

    Going in the workgroup manager the sites with the wikis allowed doesn’t appaers in the enable the following services …

    You have to ensure that both the Web Service in Server Admin and the appropriate groups in Workgroup Manager have the wiki “turned on.” You can get a step-by-step guide to doing this (which first requires setting up your Mac OS X Server a regular web server) in the Web Technologies Administration manual I linked in my post.

    Hope this helps.

    Meitar

    6 Apr 08 at 9:44 AM

  4. Obviously, I did save it. Well in fact, I did click save but the admin didn’t keep the info supposed to be saved !

    Didier

    6 Apr 08 at 10:41 AM

  5. Its very cool – but I can’t get the www. prefix to work.

    I have to give the url as http://blair.com.au and not http://www.blair.com.au

    Any idea how I can get the www alias to work?

    Hamish

    7 Apr 08 at 2:42 AM

  6. Hamish, the www part of URLs is generally considered redundant and useless. HTTP already assumes “www” so why should you have to restate it? See No-WWW! for details.

    If you still want to get the “www” hostname to respond to web queries you need to set up name resolution (probably DNS) as well as a proper Apache VirtualHost. Both of these tasks can be accomplished within the Server Admin application. Check Apple’s Mac OS X Server Documentation for details.

    Meitar

    7 Apr 08 at 10:06 AM

  7. Didier,

    I discovered recently that in order for the Workgroup Manager application to allow you to select a web site in the “Enable the following services for this group on” drop down menu, you have to create your groups in an LDAP-exported directory. That is to say your server needs to be either an Open Directory Master or an Open Directory Replica or else you’ll never be given an option other than “(None)” in that drop down.

    This seems silly to me as I don’t understand why that should be the case, but it clearly is.

    Hope that helps!

    Meitar

    16 May 08 at 2:20 AM

  8. I’d like to ensure that users enter their username and password entries only via the secured side of our web server (https: on port 443). I noticed that to enable weblogs and wikis on the port 443 site, one also has to select the “wiki and blogs” services for groups under the “Web Services” tab in the “Sites” portion of the Web part of ServerAdmin. This has the unfortunate side effect that a mangled version of the “groups” page shows up if you navigate to the http://(site)/groups url instead of the https one.

    Is there a redirect rule we can set up so that the only way to get to the groups or user blog pages is through the https site?

    ScienceMan

    9 Aug 08 at 7:34 AM

  9. Hi ScienceMan. I’m not entirely certain what you’re set up is, and I should caveat that I’ve never used Mac OS X Server web serving over the public Internet (so I’ve therefore never used HTTPS with Apple’s Teams Server/WikiServer since it’s all been intranet stuff), but if all you’re trying to accomplish is a force-redirect from the http: scheme to the https: scheme, you can try this:

    <IfModule mod_rewrite.c>
        RewriteEngine On
        RewriteCond %{HTTPS} ^off$
        RewriteCond %{REQUEST_URI} ^/groups
        RewriteRule ^/groups(.*)$ https://my-server-address.com/groups$1 [R=301,L]
    </IfModule>
    

    As usual, note that I haven’t tested this or anything, but I believe this should be what you want. Naturally, you’ll have to put this in the appropriate configuration file for your set up. See also the Apache mod_rewrite manual page, as well as Apple’s WikiServer discussion list for more help.

    Meitar

    10 Aug 08 at 2:57 AM

Leave a Reply