Introduction

Project pages are typically used to introduce a project and explain its purpose along with links to various resources such as downloads, docs, wikis, forums, mailing lists, issue trackers, source code repositories and build systems.

They are a natural starting point for new and old users alike as they provide a way to get involved from a well known, central location. As such it's important that they contain all the relevant information in an easy to consume and attractive manner. It's also important that they're kept up-todate to show that the project is active and attract new users. In a sea of open source projects a well designed set of project pages can help it stand out from the crowd and reach its intended market.

In order to provide the most flexibility in terms of page layout and to ease maintainence, by reducing the amount of duplicated content, a CMS was chosen over a plain wiki. This also allows our Visual Design Team to have greater control over page styles using CSS and enables the creation of multiple look & feels if desired. Content can still be added using wiki markup if desired but RichText and HTML are also available for greater convenience and control.

Our requirements for a Java-based open source CMS that focusses on web page creation within a browser led us to Magnolia.

What is Magnolia?

Magnolia is a Content Management System (CMS) that focusses on the creation and publication of web pages from within a browser.

Based on the Java Content Repository (JCR) specification it allows a website to be created as a hierarchical set of web pages with each page corresponding to a JCR node. The URL to any particular page is created by simply concatenating the relevant JCR node names separated by slashes:

e.g. http://jboss.org/help/projectpageguide consists of two nodes called help and projectpageguide that have a parent-child relationship.

Content

Web pages are constructed from one or more blocks of content refered to as paragraphs. Different types of paragraphs allow content to be entered in different ways to suit the task at hand. For example a Wiki Markup paragraph allows users to quickly enter content using wiki markup. Alternatively an RSS Reader paragraph allows users to enter an RSS feed URL along with the number of posts they wish to see in order to display the feed. Paragraphs use the information they contain to render HTML at runtime and are therefore the core mechanism used to create web pages. Behind the scenes each paragraph is stored as a JCR node underneath the corresponding web page node.

Layout

The layout of paragraphs within a page is initially determined by the page template. This is chosen when the page is created but can be changed at a later time if necessary. A template essentially divides up the page into a number of columns into which you can add paragraphs. You can choose to subdivide these columns further or hide them entirely when editing your page for greater control over the final layout.

Style and Behaviour

The style and behaviour of the content within a web page is also determined by the template as it specifies the CSS and JavaScript to use at runtime. This includes things like headers and footers that may appear above and below the content in addition to fonts and colours for any headers and text that are displayed.

Templates

To get project teams up and running quickly we've created a 'Project Page' template that already includes the 'JBoss Community' header and footer, a place for the project banner to be displayed and a project navigation bar with common links and site navigation. Users are then free to choose whichever paragraphs they want to include in the main content area which initially displays 3 columns.

About this Guide

This Guide is designed to take you through all the necessary steps to create useful and attractive project pages.

In the first section, Getting Started, we'll quickly take you through the main steps for creating, editing, and publishing a page. This can be used as a quick reference later on if you need to remind yourself of how things work.

In subsequent sections we go into more detail about each of these steps to show you all of the features:

  • Managing pages - How you create, copy, move, and delete pages within the website. How you publish them to the internet, restore previous versions, and choose templates.
  • Editing pages - How you configure page properties, alter the style/layout, and add, edit, move, and delete content. How content is inherited between pages.
  • Uploading files - How you upload image, audio, and video files to use in your pages.
  • Paragraph Guide - A reference guide to all available paragraphs.
  • Image and Style Guide - A reference guide to all available images and CSS styles.
  • Example Project - An example of how project pages are intended to be used.

Let's get started!