Mac OS X Server Extending Your Wiki Server For Version 10.
KK© 2008 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 5 5 Preface: About This Guide 7 7 9 10 12 13 14 14 15 17 18 22 23 25 26 27 Chapter 1: Customizing How the Wiki Looks 30 Chapter 2: Allowing Specific Protocols, CSS Styles, and HTML Tags and Attributes 31 32 32 32 33 34 34 35 35 Creating a Custom Whitelist About the Custom Whitelist’s Structure Allowing Specific URL Protocols Allowing Specific CSS Styles Allowing Specific HTML Tags and Attributes About the Built-in Whitelist Protocols Allowed in the Built-in Whitelist CSS Styles Allowed
37 37 37 39 40 41 44 45 4 Chapter 3: Managing Wiki Content Migrating Wiki Content From Other Websites Backing Up the Wiki Server Wiki File Structure Overview Manually Editing Raw Content Viewing a Wiki’s Administration Settings Viewing a Page’s Metainformation Managing Attachments Contents
Preface About This Guide This guide explains how to create custom themes, allow specific protocols, CSS styles, and HTML tags and attributes, and manage wiki content. The default Wiki Server 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. This guide shows you how to customize and extend the wiki to suit your needs.
For information about administering wikis, see Directory Help. You can view Directory Help by opening Directory (located in /Applications/Utilities/) and choosing Help > Directory Help. For information about using the wiki, see Wiki help. You can view Wiki help by clicking the Help link located at the bottom of any Apple Wiki page.
Customizing How the Wiki Looks 1 This chapter describes how to customize a wiki’s appearance. You can use a wiki’s admin settings to do the following: ÂÂ Change the wiki’s title ÂÂ Change the wiki’s theme ÂÂ Add a custom tag-search sidebar to the main page ÂÂ Choose who can make comments and which comments are moderated ÂÂ Create a podcast and integrate it with iTunes These settings are sufficient for most wikis.
However, CSS files located in individual theme folders take precedence and override the settings in this folder. Individual theme folders are subfolders with a .wikitheme extension that are located within this folder: /Library/Application Support/Apple/WikiServer/Themes/ /Library/Application Support/Apple/WikiServer/Themes/ theme_name/ compressed/ screen.css /usr/share/collaboration/themes/ Imports theme_name/ screen_compressed.
Variant Theme File Structure Overview Prebuilt themes have several variants, which all 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. /usr/share/collaboration/themes/ theme_name.variant/ screen.css screen/ Imports Imports CSS file theme_name/ screen.
Wireframe Theme File Structure Overview The wireframe theme is a good example theme to customize, because unlike the other built-in themes, its CSS files are all located in its main theme folder (in the /Library location and not in the /usr location). It was designed as a bare-bones theme, which you can easily add to without having to remove unwanted elements. /Library/Application Support/Apple/WikiServer/Themes/wireframe.wikitheme/ preview.png print.css screen.css theme.plist screen/ CSS files img/ banner.
File or Folder Name Purpose screen/calendar.css Sets the colors for the web calendar. screen/comments.css Sets various appearance attributes (such as padding, borders, and positioning) for comment entry and display. screen/footer.css Sets footer attributes, such as the margin, padding, color, and font size. screen/forms.css Sets the margin for the search field. screen/general.
Creating a Theme The easiest way to create a theme is to take the existing wireframe theme, make a copy of it with permissions intact, and then customize the copy. If you edit the included themes instead of copying them to new themes, your edits may be overwritten later by a software update. To create a copy of the wireframe theme with permissions intact: 1 In Terminal, enter the following commands: $ cd /Library/Application\ Support/Apple/WikiServer/Themes/ $ sudo ditto wireframe.wikitheme/ theme_name.
6 Restart the web service by doing one of the following: ÂÂ Restart the server. ÂÂ In Server Preferences, click Web, move the slider to Off, and then to On. ÂÂ In Server Admin, open the disclosure triangle for your server, select Web, click Stop Web, and then click Start Web. ÂÂ Enter the following in Terminal: $ sudo serveradmin stop teams; sudo serveradmin start teams; If prompted, enter your administrator account password.
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. Editing Property List Files Every theme has a theme.
Property List Editor doesn’t show comments, so if you want to see the example sidebars provided in the wireframe’s theme.plist, you’ll need to open the theme.plist file in a text editor and remove the comment markers surrounding the example sidebars. About Property List Files The theme.plist file is structured like an XML file. If you understand XML, editing the theme.plist is straightforward. If not, read the following sections for basic editing information.
Here is the sidebars array in a plain text editor: sidebars sidebar keys and values sidebar keys and values 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.
Changing General Theme Settings The wireframe theme’s theme.plist 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.
Creating Sidebars If you haven’t created a sidebar before, it might be easier to customize an example sidebar to suit your needs. In the wireframe theme’s theme.
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 urls Not applicable An array of dictionary entries, each representing a single link Required Because links include several values, such as the name of the link and the URL itself, every link is represented by a dictionary entry. headerURL http://example.
Key Example Value Possible Values Optional or Required Description 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 .snippet{ display:none; } Search Unique Keys Search sidebars list search results using tag-based or text-based searching. “What’s Hot” and “What’s New” are examples of search sidebars.
Key Example Value sort modifiedDate, createdDate, One or more of the title, author following in the same array: Possible Values ÂÂ ÂÂ ÂÂ ÂÂ ÂÂ ÂÂ ÂÂ ÂÂ ÂÂ ÂÂ sortDirection reverse Optional or Required Description Optional Entries are sorted based on these fields. The first field listed is sorted first, then the entries are resorted by subsequent fields. The last field listed takes precedence over all previously listed fields.
Tag Unique Keys Tag sidebars list wiki, blog, and mailing list entries that use a specific tag or set of tags. The most recently modified entries are listed first. Tag sidebars have the following unique keys: Key Example Value Possible Values Optional or Required Description tag hot A single string or several strings all in the same array Required Tags associated with the sidebar. Pages using all of these tags are added to the sidebar.
Using the Example Sidebars The wireframe theme’s theme.plist file includes several sidebar examples. All of these examples are commented out by default. You’ll need to remove the comments marks if you want to use the example sidebars as custom sidebars. If you don’t add any custom sidebars, the default sidebars are used. If you use at least one custom sidebar, the default sidebars don’t appear. Consider commenting out all sidebars you don’t want to use, and leaving uncommented all sidebars you want to use.
5 For each sidebar that you want to comment out, do the following: a Add after the tag of the sidebar you want to comment out.
Adding JavaScript and XSL Files The wiki server supports the use of custom JavaScript and Extensible Stylesheet Language (XSL) files. JavaScript and XSL change the content you’re displaying, whereas CSS controls the presentation of content. For example, you use could use JavaScript or XSL to add a “digg it” link to your blog entries, which would then tie the blog entries to digg.com. Carefully choose whether you want to use JavaScript, XSL, or both.
2 Restart the web service by doing one of the following: ÂÂ Restart the server. ÂÂ In Server Preferences, click Web, move the slider to Off, and then to On. ÂÂ In Server Admin, open the disclosure triangle for your server, select Web, click Stop Web, and then click Start Web. ÂÂ Enter the following in Terminal: $ sudo serveradmin stop teams; sudo serveradmin start teams; If prompted, enter your administrator account password.
JavaScript Example The following example JavaScript function adds a header link next to the magnifier button that points to www.apple.com, and changes the “Other Wikis” link to point to www.apple.com: Event.observe(window, 'load', function() { // add another header link (to apple.com) by manipulating the DOM // using script.aculo.us Builder // we'll just insert it before the search button if ($('linkSearch')) { $('linkSearch').parentNode.insertBefore(Builder.node('li', {id:'linkApple'}, [ Builder.
If you edit a copy of the default.xsl file, you must also make copies of all of the XSL files that include the original default.xsl file, and then change them to include the edited default.xsl file. Viewing Dynamic XML The wiki server dynamically generates XML content, which is called context. Context is transformed by XSL files into HTML. Before you view context, familiarize yourself with the XSL files located in: /usr/share/wikid/lib/apple_templates/ The XSL files correspond to specific pages in the wiki.
3 Restart the web service by doing one of the following: ÂÂ Restart the server. ÂÂ In Server Preferences, click Web, move the slider to Off, and then to On. ÂÂ In Server Admin, open the disclosure triangle for your server, select Web, click Stop Web, and then click Start Web. ÂÂ Enter the following in Terminal: $ sudo serveradmin stop teams; sudo serveradmin start teams; If prompted, enter your administrator account password.
Allowing Specific Protocols, CSS Styles, and HTML Tags and Attributes 2 This chapter describes how to enable specific protocols, CSS styles, and HTML tags and attributes. The default wiki server setup simplifies administration by automatically removing potentially harmful protocols, CSS styles, and HTML tags and attributes. The wiki server is capable of allowing all protocols, CSS styles, and HTML tags and attributes.
Creating a Custom Whitelist To create a custom whitelist, create a plain text file named whitelist.plist in: /Library/Application Support/Apple/WikiServer/ The following sections describe this example whitelist.plist in detail: PAGE 32About the Custom Whitelist’s Structure The following lines are required in the custom whitelist: PAGE 33For example, to allow the use of the font-size style attribute, create the following block: styles font-size To allow the HTML “style” attribute, add the “style” attribute to the “_all_” tag, which is described in the following section. Allowing Specific HTML Tags and Attributes YouTube, Flash, and other advanced web formats usually require HTML tags and attributes that aren’t allowed by default.
src type width height About the Built-in Whitelist You can’t change the built-in whitelist. However, a software update could change the allowed elements in the built-in whitelist.
Protocol tel telnet vnc webcal xmpp CSS Styles Allowed in the Built-in Whitelist The built-in whitelist allows these CSS styles: Style text-decoration font-weight font-style HTML Tags and Attributes Allowed in the Built-in Whitelist The built-in whitelist allows these HTML tags and attributes: Tag Attributes _all_ class, title a href, name, ref b blockquote cite body br caption dd div dl dt em h1 h2 h3 h4 h5 h6 html i img src, alt, name, width, height, longdesc li Chapter 2 Allowing Specific
Tag Attributes node ol p pre q cite span strong table tbody tfoot th colspan, rowspan thead td colspan, rowspan tr u ul 36 Chapter 2 Allowing Specific Protocols, CSS Styles, and HTML Tags and Attributes
Managing Wiki Content 3 This chapter describes how to manage wiki content using tools and the command-line. Using tools and the command line allows you to migrate, back up, and edit raw wiki content. Migrating Wiki Content From Other Websites AppleWikiImporter is a tool that can traverse a website that has a page listing all other pages in the site, and create wiki pages based on the website contents. If the website uses tags, AppleWikiImporter can import those tags.
To manually back up the wiki, copy the wiki data store with its permissions intact. For example, to copy the wiki data store to a folder on a different volume, enter the following in Terminal and then authenticate as an administrator when requested: sudo ditto /Library/Collaboration/ /Volumes/volumename/foldername/ If you created or edited themes, copy the theme folder with its permissions intact.
Wiki File Structure Overview By default, the wiki server stores group wikis in /Library/Collaboration/Groups/. The illustration below shows group wiki files and folders. /Library/Collaboration/Groups/ group_name/ index.db metadata.plist wiki/ page_uid.page/ page.html page.
The Groups folder in the wiki data store includes the following critical wiki files and folders: File or Folder Name Purpose group_name/ Enabling web services for a group creates a folder with the group’s short name. group_name/index.db Automatically changed when you edit wiki content. If you manually edit raw content, erase this file so that it will regenerate based on raw content. group_name/metadata.plist Contains wiki administration settings. group_name/wiki/ Stores all pages in the wiki.
For more information about AtomPub, see: Website URL RFC 4287: The Atom Syndication Format atompub.org/rfc4287.html RFC 5023: The Atom Publishing Protocol tools.ietf.org/html/rfc5023 To regenerate the index after editing raw wiki content: 1 Delete /Library/Collaboration/Groups/group_name/index.db. To delete this file, enter: sudo rm /Library/Collaboration/Groups/group_name/index.db Replace group_name with the group’s short name.
The metadata.plist file includes the following keys: Key Example Value Description GUID 28CC6BE9-11C1-456C-A3B2-8FCF5520A1DB Uniquely identifies the wiki. This value must correspond to the group record’s GUID in the directory domain. To view a group record's GUID, use Workgroup Manager. For more information, see User Management at www.apple.com/server/macosx/resources/. LongName Wiki Name Name of the wiki. By default, this name is displayed in the top left of every wiki page.
To manually edit wiki administration settings: 1 Stop the web service by doing one of the following: ÂÂ In Server Preferences, click Web and move the slider to Off. ÂÂ In Server Admin, open the disclosure triangle for your server, select Web, and click Stop Web. ÂÂ Enter the following in Terminal: $ sudo serveradmin stop teams; If prompted, enter your administrator account password.
6 Start the web service by doing one of the following: ÂÂ In Server Preferences, click Web and move the slider to On. ÂÂ In Server Admin, open the disclosure triangle for your server, select Web, and click Start Web. ÂÂ Enter the following in Terminal: $ sudo serveradmin start teams; If prompted, enter your administrator account password.
Key Example Value Description tombstoned , Originally set to false, this is set to true when a page is temporarily deleted. If a page is permanently deleted, the entire page_uid.page/ folder is removed. uid groups/group_name/wiki/page_uid/ Unique identifier for the wiki page and its location. versioned , Wiki pages are versioned; blog and mailing list entries aren’t. After manually editing this file, delete the group’s index.db file and restart the server.
