Mac OS X Server Wiki Server Administration Version 10.
KKApple Inc. © 2009 Apple Inc. All rights reserved. The owner or authorized user of a valid copy of Mac OS X Server software may reproduce this publication for the purpose of learning to use such software. No part of this publication may be reproduced or transmitted for commercial purposes, such as selling copies of this publication or for providing paid-for support services. Every effort has been made to ensure that the information in this manual is accurate. Apple Inc.
Contents 7 7 8 9 10 11 11 12 12 Preface: About This Guide 13 13 14 14 14 Chapter 1: About Wikis, Blogs, Web Calendars, and Mailing Lists 15 Chapter 2: Enabling and Configuring Wikis, Blogs, Web Calendars, and Mailing Lists 15 15 16 18 19 20 22 23 24 26 26 Setting Up Wiki Server Setting Up and Starting iCal Service on the Wiki Server Setting Up iCal Service on a Different Server than the Wiki Server Configuring Wiki Settings for All Websites Configuring Other Servers for Web Calendars and Mail Ru
30 32 33 34 35 35 38 39 45 45 47 47 51 52 52 54 56 Wireframe Theme File Structure Overview Creating a Theme Editing CSS Files Editing Property List Files About Property List Editor About Property List Files Changing General Theme Settings Creating Sidebars Overview of the Example Sidebars Using the Example Sidebars Adding JavaScript and XSL Files About JavaScript About XSL Customizing My Page Changing Text Shown in Wikis and Blogs Lists Changing the My Page Theme Testing Wiki Code Changes 57 Chapter 4:
DraftVersion 73 74 75 78 79 80 83 Wiki File Structure Overview Manually Editing Raw Content Viewing a Wiki’s Administration Settings Viewing a Page’s Metainformation Managing Attachments Configuring Wiki Server Settings from the Command Line Choosing Who Can Administer Wiki Server 84 Index Contents 5
Preface About This Guide This guide explains how to set up, customize, and extend wiki services. Mac OS X Server includes wiki services, which allow you to set up personal and group wikis, blogs, and web calendars. The default wiki services configuration makes it easy for groups to collaborate and communicate. Users can create and edit wiki pages, tag and cross-reference material, upload files and images, add comments, and search content.
ÂÂ Quick Look support. Users can use Quick Look to preview attached files without downloading the files. By default, users can use Quick Look to preview any file types that can be previewed in Finder, such as Keynote, Pages, and PDF files. You can enable Quick Look for more file types. For more information, see Chapter 5, “Allowing Specific File Types for Quick Look.” ÂÂ Improved iPhone support. Wiki tools look and work better than ever on iPhone. For more information, see Wiki Help on iPhone.
Using Onscreen Help You can get user help while using the wiki tools on your computer or iPhone, or administration task instructions in the Help Viewer application while you're managing Snow Leopard Server. You can view administration help on a server or an administrator computer. (An administrator computer is a Mac OS X computer with Mac OS X Server administration software installed on it.) To get user help while using wiki tools on your computer: mm Click the “help” link.
Documentation Map Mac OS X Server has a suite of guides that cover management of individual services. Each service may depend on other services for maximum utility. The documentation map below shows some related guides you may need to fully configure Wiki Server to your specifications. You can get these guides in PDF format from the Mac OS X Server resources website: www.apple.com/server/macosx/resources/ Getting Started Explains how to set up collaboration services using Server Preferences.
Viewing PDF Guides Onscreen While reading the PDF version of a guide onscreen: ÂÂ Show bookmarks to see the guide’s outline, and click a bookmark to jump to the corresponding section. ÂÂ Search for a word or phrase to see a list of places where it appears in the guide. Click a listed place to see the page where it occurs. ÂÂ Click a cross-reference to jump to the referenced section. Click a web link to visit the website in your browser.
Getting Documentation Updates Periodically, Apple posts revised help pages and new editions of guides. Some revised help pages update the latest editions of the guides. ÂÂ To view new onscreen help topics for a server application, make sure your server or administrator computer is connected to the Internet and click “Latest help topics” or “Staying current” in the main help page for the application. ÂÂ To download the latest guides in PDF format, go to the Mac OS X Server Resources website at: www.apple.
About Wikis, Blogs, Web Calendars, and Mailing Lists 1 Learn about the tools provided by Wiki Server. Wiki Server provides several web-based wiki tools that allows users to express themselves or to easily form, coordinate, and organize teams. About Wikis A wiki is a web-based collaborative editing environment for groups. Depending on how the wiki administrator sets permissions, anyone who can view wiki content can also add or edit content.
About Blogs A blog is like an online journal. Entries are arraned chronologically with the newest entries listed first. The blog and the wiki share the same simple editing toolbar and thus share a lot of the same advantages. The biggest difference between a blog and a wiki is that the blog has a sense of time but the wiki doesn’t. In a blog, new content is found more easily than older content. In a wiki, content is found by need or by navigation, rather than by time.
Enabling and Configuring Wikis, Blogs, Web Calendars, and Mailing Lists 2 Learn how to use Server Admin to enable and configure websites with wiki tools. You use Server Admin to enable and configure websites with wiki tools. Websites with wiki tools have My Page, which is a portal page that allows users to create wikis, blogs, web calendars, and mailing lists. Setting Up Wiki Server Here is an overview of the basic steps for setting up wiki server. Step 1: Set up and start iCal service.
The default settings are: Setting Default Data Store /Library/CalendarServer/Documents/ Maximum Attachment Size 1 MB User Quota 100 MB Authentication Any Method Host Name The host name of the Wiki server Secure Sockets Layer (SSL) Don’t Use HTTP Port Number 8008 Log Level Warning Push Notification Server None For information about changing these settings, see iCal Service Administration. To start iCal service: 1 Open Server Admin and connect to the server.
7 In the Calendar Server field, enter the address of the iCal server. 8 If SSL is enabled, select SSL. 9 Click Done. To use a different server for iCal service from the command line: 1 On the server running wiki services, in Terminal, open /etc/apache2/httpd_webcalendar.conf in a text editor. To open this file in a command-line text editor, enter: $ sudo nano /etc/apache2/httpd_webcalendar.conf If prompted, enter your administrator account password.
Configuring Wiki Settings for All Websites Wiki settings apply to all websites and thus all wikis hosted on a server. The default settings should work for most users. Wiki settings include: Setting Default Description Data Store /Library/Collaboration/ Wiki, blog, web calendar, and mailing list pages are stored in this location. To change this location, copy the contents of /Library/Collaboration/ to the new location with permissions intact.
Setting Default Description Wiki Creators Empty (anyone can create wikis) This lists who can create wikis. You can include users or groups in this list. If you leave this list empty, anyone with access to the wiki server can create wikis. SMTP Relay None If you’re not hosting mail service on the same server as the wiki server, click Configure and enter configuration information for a SMTP server. This is used to forward mail sent to group mailing lists, and for mail notifications.
To configure external servers for web calendar and mail rules: 1 Open Server Admin and connect to the web server. 2 Click the triangle at the left of the server. The list of services appears. 3 If Web is not listed, select the server and click Settings; then click Services, select Web, and then click Save. 4 From the expanded Servers list, select Web. 5 Click Settings, then click Wiki. 6 Click Configure next to External Web Services. 7 Enter the host name of calendar or mail servers.
To configure external servers for hosting wikis: 1 Copy wikis from the main web server to another server. Wikis are stored in /Library/Collaboration/Groups/. For more information about the wiki file structure, see “Wiki File Structure Overview” on page 73. 2 Edit the /etc/apache2/httpd_groups.conf file on the main web server: a To edit this file in Terminal, enter: sudo nano /etc/apache2/httpd_groups.conf If prompted, enter your administrator account password.
In the example scenario, you’d enter the following lines: ProxyPass /RPC2 http://science.example.com:8086/RPC2 retry=5 ProxyPass /RPC2 http://math.example.com:8086/RPC2 retry=5 4 Edit the /etc/wikid/wikid.conf file on every external web server: a To edit this file in Terminal, enter: sudo nano /etc/wikid/wikid.
The list of services appears. 3 If Web is not listed, select the server and click Settings; then click Services, select Web, and then click Save. 4 From the expanded Servers list, select Web. 5 Click Sites, then select a site in the list. 6 To enable SSL, click Security, select Enable Secure Sockets Layers (SSL), and choose a certificate. For more information about enabling SSL, see Web Technologies Administration. 7 Click Web Services. 8 To enable group wikis, select “Wikis.
To restart web service in Server Admin: 1 In Server Admin, click the triangle at the left of the server name hosting the web service and select Web. 2 If web service is running, shown by a green status icon at the left of “Web,” click Stop Web, then click Start Web; otherwise, click Start Web. To restart web service in Server Preferences: mm In Server Preferences, click Web, move the slider to Off, and then to On.
Name URL Description Calendar page /ical/ This page is a personal calendar for the user. The user can send and receive invitations on this calendar. Settings page /settings/ This page includes personal settings, such as account preferences, password, and mail rules. Every wiki links to several pages: Name URL Description Wiki pages /groups/wikiname/wiki/uid/ pagename.html Any member of a wiki can create or edit wiki pages. Blog pages /groups/wikiname/blog/uid/ pagename.
Configuring Individual Wikis A wiki administrator can change wiki settings.
Customizing How the Wiki Looks 3 Learn how to customize a wiki’s appearance.
/Library/Application Support/Apple/WikiServer/Themes/ If the theme has a /compressed subfolder, it imports the CSS files located at: /usr/share/collaboration/themes/theme_name/screen_compressed.css The following shows how the /compressed folder imports screen_compressed.css. /Library/Application Support/Apple/WikiServer/Themes/ theme_name/ compressed/ screen.css /usr/share/collaboration/themes/ Imports theme_name/ screen_compressed.css The screen_compressed.
Variant Theme File Structure Overview Prebuilt themes have several variants, which share the same layout but might have different banners or color schemes. Shared CSS files are in the main theme’s folder, while variants have separate CSS files located in other folders. The following shows how theme variants import the main theme’s CSS and CSS files located in the main theme and theme variant’s /screen folder. /usr/share/collaboration/themes/ theme_name.variant/ screen.
Wireframe Theme File Structure Overview The wireframe theme is a good example theme to customize, because unlike other built-in themes, its CSS files are located in its main theme folder (in the /Library location and not in the /usr location). /Library/Application Support/Apple/WikiServer/Themes/wireframe.wikitheme/ preview.png print.css screen.css theme.plist screen/ CSS files img/ banner.jpg comment.png rss.png It is a bare-bones theme, which you can easily add to without removing unwanted elements.
File or Folder Name Purpose theme.plist Affects general settings (such as the theme’s name), and sidebar attributes (such as the maximum number of entries and types of sidebars shown). screen/ Includes all CSS files used when displaying the wiki on screen. screen/calendar.css Sets the colors for the web calendar. screen/comments.css Sets appearance attributes (such as padding, borders, and positioning) for comment entry and display. screen/footer.
File or Folder Name Purpose screen/toolbar.css Sets the editing toolbar’s color, background color, and margin. screen/weblog.css Sets blog display attributes, such as which elements are displayed. screen/img/ Contains graphics used in the theme. screen/img/banner.jpg Default banner for the theme. Its dimensions are 950 x 140 pixels. screen/img/comment.png Displayed in the upper right of every comment. Its dimensions are 16 x 15 pixels. screen/img/rss.
You can use any command-line text editor, as long as you precede the command to run the text editor with sudo. If you’re using Property List Editor or a non–command-line tool, open the theme.plist located in your Documents folder. 4 Remove the selectable key and its value and then save the plist. To remove the key using Property List Editor, select the selectable key and then click Delete.
Website URL World Wide Web Consortium w3.org CSS3 css3.info QuirksMode quirksmode.org Position is Everything positioniseverything.net The WebKit OpenSource Project webkit.org A List Apart alistapart.com CSS Zen Garden csszengarden.com Here are some published CSS guides: ÂÂ CSS: The Definitive Guide, 3rd Edition, by Eric Meyer. O'Reilly Media, Inc. 2006. ÂÂ CSS Mastery: Advanced Web Standards Solutions, by Andy Budd, Simon Collison, and Cameron Moll. Friends of ED. 2006.
About Property List Editor Property List Editor (shown below) is a specialized editor for property list files. To edit a theme.plist file using Property List Editor, copy it to your Documents folder. When you finish editing theme.plist, copy it back to /Library/Application Support/Apple/WikiServer/Themes/theme_name.wikitheme/. Property List Editor is located on the Mac OS X Server v10.5 Administration Tools CD, in /Utilities/. You can run it from the CD or copy it to another location.
To halve the height of the banner image in a text editor, change the following lines in theme.plist: bannerImageHeight 99 to: bannerImageHeight 50 About Strings Most of the values in theme.plist are character sequences called strings. About Dictionaries A dictionary, or dict when viewed in a text editor, is an assortment of values of different classes. In theme.plist, a sidebar is represented by a dictionary.
Here is an example of an array with a single string: value Here is an example of an array with multiple strings: value value 2 About Comments The theme.plist file includes comments to help provide editing instructions and example keys and values. Comments are ignored when theme.plist is read by the wiki server. Comments start with “.
Changing General Theme Settings The wireframe theme’s theme.plist file includes keys and values for the following general settings: Key Default Value Possible Values Optional or Required Description bannerImageHeight 99 Any number, 0 or more Optional The amount in pixels alloted to the height of the banner image. Images you upload are scaled to this size. If you define bannerImageHeight but not bannerImageWidth, the width scales proportionally.
Key Default Value Possible Values Optional or Required Description mobileHeaderColor #848c64 # followed by a Optional hexadecimal color code The background color shown behind the name of the wiki and navigation bar when you view the wiki on iPhone. name com.apple.wireframe Any string with no spaces Required Uniquely identifies the theme. selectable Optional Displays a theme in the theme chooser, if the selectable key and value are removed.
Understanding the Types of Sidebars There are several types of sidebars, each with a specific purpose and set of keys: Sidebar Type Description Related Section static A list of URLs. “Static Unique Keys” on page 41 search A list of search results using tag- “Search Unique Keys” on based or text-based searching. page 42 calendar A list of upcoming events. tag A list of search results using tag- “Tag Unique Keys” on page 44 based searching.
Static Unique Keys Static sidebars list predefined URLs. “Useful Links” is an example static sidebar. Static sidebars have the following keys: Key Example Value Possible Values Optional or Required Description headerURL http://example.com/ groups/groupname/se arch/?sort=modifiedDa te&kind=wiki&kind=w eblog&kind=mailinglis t&sortDirection=revers e&excludePages=wiki/ welcome Fully qualified URL Optional A URL that is linked to from the sidebar’s header. feedURL Fully qualified URL feed://example.
Key Example Value Possible Values Optional or Required Description uid serverhome, groups Any string Required Identifier for the URL. This value must be unique. url /, /groups/ A relative or absolute path to a web page Required Contents of the link. snippet Click here to see your server’s homepage. Any string Optional Used for the link’s tool tip. To enable tool tips, comment out the following block in the theme’s grouphome. css file: .grouphome .
Key Example Value Possible Values Optional or Required Description q annejohnson, wiki, 2008-03-17 One or more strings in the same array Optional The text query used to search for entries. fields title, content, author One or more of the following in the same array: Optional The fields the text query is applied to.
Calendar Unique Keys Calendar sidebars list upcoming events. “Upcoming Events” is an example calendar sidebar. Calendar sidebars have the following unique keys: Key Example Value Possible Values Optional or Required Description howManyDays 5 Any number, 1 or more Required Maximum number of days until an event for it to be listed in the sidebar. Events occurring after this number of days aren’t shown in the sidebar. emptyListString There are no matches.
Overview of the Example Sidebars The wireframe theme’s theme.plist file provides several example sidebars: Sidebar Name Description What’s Hot Lists the five most recently modified pages tagged with “hot.” What’s New Lists the five most recently created pages. This includes wiki, weblog, and mailing list pages. Useful Links Lists several predefined links. Upcoming Events Lists events occurring within the next five days. Using the Example Sidebars The wireframe theme’s theme.
If you’re using a non–command-line tool, open the theme.plist file located in your Documents folder. 4 If there is a comment marker before version. 5 For each sidebar that you want to comment out, do the following: a Add
