Apple Mac OS X Server User Manual

0 (0)

Mac OS X Server

Extending Your Wiki Server

For Version 10.5 Leopard

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. is not responsible for printing or clerical errors.

Because Apple periodically releases new versions and updates to its software, images shown in this book may be different from what you see on your screen.

Apple

1 Infinite Loop

Cupertino, CA 95014-2084 408-996-1010 www.apple.com

The Apple logo is a trademark of Apple Inc., registered in the U.S. and other countries. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws.

Apple, the Apple logo, iCal, iTunes, Leopard, Mac, Mac OS, and Macintosh are trademarks of Apple Inc.,

registered in the U.S. and other countries. Finder, Safari, and Time Machine are trademarks of Apple Inc.

UNIX is a registered trademark of The Open Group.

Other company and product names mentioned herein are trademarks of their respective companies. Mention of third-party products is for informational purposes only and constitutes neither an endorsement nor a recommendation. Apple assumes no responsibility with regard to the performance or use of these products.

019-1252/2008-04-24

5 Preface:  About This Guide

5 Getting Additional Information

7 Chapter 1:   Customizing How the Wiki Looks

7 Theme File Structure Overview

9Variant Theme File Structure Overview

10Wireframe Theme File Structure Overview

12Creating a Theme

13Editing CSS Files

14Editing Property List Files

14About Property List Editor

15About Property List Files

17Changing General Theme Settings

18Creating Sidebars

22Overview of the Example Sidebars

23Using the Example Sidebars

25Adding JavaScript and XSL Files

26About JavaScript

27About XSL

30Chapter 2:  Allowing Specific Protocols, CSS Styles, and HTML Tags and Attributes

31Creating a Custom Whitelist

32About the Custom Whitelist’s Structure

32Allowing Specific URL Protocols

32Allowing Specific CSS Styles

33Allowing Specific HTML Tags and Attributes

34About the Built-in Whitelist

34Protocols Allowed in the Built-in Whitelist

35CSS Styles Allowed in the Built-in Whitelist

35 HTML Tags and Attributes Allowed in the Built-in Whitelist

37 Chapter 3:   Managing Wiki Content

37 Migrating Wiki Content From Other Websites

37 Backing Up the Wiki Server

39Wiki File Structure Overview

40Manually Editing Raw Content

41Viewing a Wiki’s Administration Settings

44Viewing a Page’s Metainformation

45Managing Attachments

4	Contents

About This Guide

Preface

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 example, you’ll learn how to:

ÂÂ Create custom themes

ÂÂ Enable JavaScript, YouTube, and Flash

ÂÂ Automate migration from other sources, such as wikis and non-wiki websites

The tasks described in this guide can be used on standard, workgroup, and advanced configurations of Leopard Server.These tasks require administrator access and in some cases programming skill.You must be able to edit files on the server, which aren’t accessible to most users. Be careful when editing these files, as an incorrect or untested change could cause problems.

Getting Additional Information

Information about setting up, administering, and using Wiki Server is covered in detail in several places.

For information about setting up web service, see:

ÂÂ Getting Started—if you’re using Server Preferences

ÂÂ Web Technologies Administration—if you’re using Server Admin

You can find both guides at the Mac OS X Server Resources website: www.apple.com/server/macosx/resources

	5

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.

6	Preface    About This Guide

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, if you have special needs—for example, if you want to use a specific organization’s style, or if you want to change the appearance and names of the default sidebars on the front page—you must edit files located on the server.

Theme File Structure Overview

A theme is composed of Cascading Style Sheet (.css) files, property list (.plist) files, image files (usually .png and .jpg), and sometimes JavaScript (.js) and Extensible Stylesheet Language (.xsl) files.

All themes use the CSS files located at: /usr/share/collaboration/css/required/

	7

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/

theme_name/

compressed/

screen.css

/usr/share/collaboration/themes/

Imports

theme_name/

screen_compressed.css

If the theme has a /compressed subfolder, it imports the CSS files located at:

/usr/share/collaboration/themes/theme_name/screen_compressed.css

The screen_compressed.css file combines the many individual CSS files located in the theme_name/screen/ folder. These are provided in the prebuilt themes to improve overall performance.The screen_compressed.css file isn’t created automatically or dynamically, so any changes to .css files located in the theme_name/screen/ folder don’t affect the screen_compressed.css file.

8	Chapter 1    Customizing How the Wiki Looks

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
CSS file	Imports
CSS file
theme_name/
screen.css
screen/	Imports
CSS files

For example, the block theme has its shared CSS files located in:

/usr/share/collaboration/themes/block/screen/

Variants of the block theme all use these shared CSS files. Each variant also uses CSS files located in another folder such the following:

/usr/share/collaboration/themes/block.green.banner/screen/

/usr/share/collaboration/themes/block.red/screen/

/usr/share/collaboration/themes/block.red.banner/screen/

These CSS files all serve only as examples, since the prebuilt themes use the screen_ compressed.css file instead of these individual files.

Chapter 1    Customizing How the Wiki Looks	9

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.jpg

comment.png

rss.png

The wireframe theme’s folder includes the following files and folders:

File or Folder Name	Purpose
preview.png	Displayed when users are choosing which theme to use.
	Its dimensions are 128 x 128 pixels.

print.css	Applied when wiki pages are printed. If you don’t
	remove the import line from this file, printing uses the
	print.css file located at:
	/usr/share/collaboration/default/print.css

screen.css	Applied when wiki pages are displayed on screen. This
	file simplifies organization and file structure by using
	the CSS files in /screen instead of containing all the CSS
	code in one file.

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 of the CSS files used when displaying the
	wiki onscreen.

10	Chapter 1    Customizing How the Wiki Looks

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.css	Sets general blog and wiki display attributes, such as the
	font size and color, background colors, heading margins,
	and list styles.

screen/grouphome.css	Sets display attributes for the sidebar located on the
	main wiki page, such as its size, margins, and font size.

screen/header.css	Sets display attributes (such as the font size, margin,
	and padding) for the wiki, blog, calendar, and mail links
	located at the top of each page.

screen/layout.css	Sets display attributes (such as the margin and size) for
	the wiki and blog editing interface.
	Customizing the editing interface is an advanced task;
	depending on what you’re trying to do, you may need
	to write JavaScript.

screen/metadata.css	Sets display attributes for fields in page histories, such
	as the margin and font size.

screen/tables.css	Sets display attributes for tables and table headers, such
	as the color, border styles, and font size.

screen/tags.css	Sets display attributes for the tag list shown on each
	page, such as the margins, padding, and separators.

screen/thumbnail.css	Sets display attributes for image thumbnails, such as
	the border styles, color, padding, and the magnification
	graphic.

screen/toc.css	Disabled. Don’t edit.

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.png	Displayed in the upper right of the What’s Hot and
	Recent Changes sidebars on the main page. Its
	dimensions are 12 x 12 pixels.

Chapter 1    Customizing How the Wiki Looks	11

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.wikitheme/

Replace theme_name with the name of the theme you’re creating. If prompted, enter your administrator account password.

2If you’re going to use Property List Editor or a non–command-line tool, copy the theme.plist file to your Documents folder.

To copy this file, enter:

$ cp theme_name.wikitheme/theme.plist /Users/user_name/Documents/

Replace user_name with the short name of the user you’re logged in as. For information about Property List Editor, see “About Property List Editor.”

3 Open theme.plist in Property List Editor or a text editor.

To open this file in a command-line text editor, enter: $ sudo nano theme_name.wikitheme/theme.plist

If prompted, enter your administrator account password.

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.

4Remove 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.

To remove the key using a text editor, remove the following lines:

<key>selectable</key>

5 If you copied theme.plist to your Documents folder, copy it back to the theme folder.

To copy this file, enter:

$ cp /Users/user_name/Documents/theme.plist theme_name.wikitheme/

12	Chapter 1    Customizing How the Wiki Looks

6Restart 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.

Restarting the server and restarting web service can disrupt users, so send out a notification that the server will be temporarily down before doing this.

Editing CSS Files

Cascading Style Sheet (.css) files control how the wiki looks. By editing these CSS files, you can easily change display attributes for specific page elements. For example, you can change:

ÂÂ Color

ÂÂ Background color ÂÂ Margin

ÂÂ Padding ÂÂ Font size

If you’re skilled at editing CSS files, you can completely overhaul the look of the wiki by changing its layout, removing unwanted visual elements, and adding your own visual elements.

When you edit a CSS file, your changes occur immediately; you don’t have to restart the server or web service after editing. Because you might disrupt users by changing

CSS files, you should create, edit, and test them with a theme that isn’t currently in use.

There are many online sources of information about Cascading Style Sheets. These websites should help you get started:

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

Chapter 1    Customizing How the Wiki Looks	13

Here are some published CSS guides:

ÂÂ CSS:The Definitive Guide,3rd Edition, by Eric Meyer. O’Reilly Media, Inc. 2006.

ÂÂ CSS Mastery:AdvancedWeb Standards Solutions, by Andy Budd, Simon Collison, and Cameron Moll. Friends of ED. 2006.

Editing Property List Files

Every theme has a theme.plist file, which controls:

ÂÂ The name of the theme

ÂÂ Whether the theme is publicly available ÂÂ The height and width of the banner

ÂÂ Sidebar properties such as the name, type and number of links, and sort order

After making changes to the theme.plist file, you must restart the web service or restart the server. Because this can disrupt users, you should create, edit, and test themes on a test computer and then copy them over to the server.

About Property List Editor

Property List Editor is a specialized editor for property list files.

In order to edit a theme.plist file using Property List Editor, you must copy it to your Documents folder.When you finish editing the theme.plist file, you must 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 AdministrationTools CD, in

/Utilities/.You can run it from the CD or copy it to a different location.

14	Chapter 1    Customizing How the Wiki Looks

+ 31 hidden pages