Publishing Newspapers And Magazines Online With ProsePoint

Beng Tan

prosepoint.org

Revision History

RevisionDateNotes
729th November 2009Update requirements to exclude PHP 5.3.x.
610th November 2008Update for ProsePoint 0.08. General minor updates throughout.
53rd November 2008Add upgrade information for ProsePoint 0.07. This document is getting more and more out of date.
427th October 2008Amend requirements. Update upgrade notes. Add themeing section.
321st October 2008Add upgrade procedure and preliminary update for ProsePoint 0.04. Needs work.
217th September 2008Quick amendment to installation procedure for ProsePoint 0.03.
14th September 2008First revision

Note

This is the document history of this book, not the software package ProsePoint.

Chapter 1. Introduction

1.1. What is ProsePoint?

ProsePoint is a software package that lets you quickly and easily publish your own newspaper or magazine online. You can upload stories, edit stories online, and organise stories into editions, all through the user-friendly and convenient web interface. You do not need to know any programming or html to use ProsePoint.

Note

You or a friend will need to be familiar with web servers to install ProsePoint. More on this later.

For those who are not put off by technology jargon, ProsePoint is a newspaper content management system. There are many content management systems (CMS) available, all of which allow you to publish and manage the content of your website. ProsePoint is different from these general CMS's because ProsePoint specifically aims to meet the needs of those people who wish to publish newspapers or magazines online. ProsePoint has inbuilt features to support this objective out of the box.

1.2. Licensing and warranty

ProsePoint is free and open source software, licensed under the GNU General Public License ("the GPL") Version 2.

If you are unfamiliar with open source or the GPL, the following are some general guidelines for using ProsePoint:

  • You may use ProsePoint in any way you wish, whether that is for personal or commercial use.
  • You may give anyone an unmodified copy of ProsePoint.
  • You may modify ProsePoint in any way you wish, but you must retain all copyright notices.
  • If you modify ProsePoint and give or sell that modified copy to anyone else, you must also supply the source code to your modifications.

Please note that these are general guidelines only and do not constitute legal advice. For legal advice, please see an intellectual property lawyer.

Warranty

ProsePoint software is supplied on an “as is” basis. It comes with no warranty or assurances of functionality or suitability.

1.3. Why should I use ProsePoint?

You shouldn't use ProsePoint just because we said so.

You should use whatever best suits your needs. If that happens to be ProsePoint, then you should use ProsePoint. If another software system suits your needs better, then you should use that.

However, please consider the following.

Most content management systems are aimed towards building a wide range of websites. This means that they are necessarily general in nature, and can only offer general capabilities. Using a general CMS to build a website often requires further configuration and custom functionality to be added.

ProsePoint is a content management system targeted specifically for newspapers and magazines. Hence, ProsePoint has inbuilt features which are known to be useful for those types of websites. This dramatically reduces the amount of customisation and extra functionality that would be required to build your newspaper or magazine website. ProsePoint has already done most of that work, so you don't have to.

This is not to say that ProsePoint will not require any customisation, just that the amount of customisation is significantly reduced. In almost all cases, website owners will want to change something about ProsePoint. That is human nature, and we cannot cater for the infinite variations.

However, if you are satisfied with the look and feel of ProsePoint "out of the box", and you do not wish to commit any additional resources at all (whether that's because of lack of time or lack of funding), then it is certainly possible to use ProsePoint without any modifications whatsoever, and it would still meet most of your needs.

Another factor to consider in evaluating ProsePoint is that ProsePoint is free and open source softare, but that has already been covered above.

1.4. Who is this book written for?

This user guide / book is written for anyone who:

  • Is a ProsePoint user or administrator,

  • Needs to install ProsePoint on a computer server,

  • Is evaluating ProsePoint for publishing their own newspaper or magazine website, or

  • Is curious about ProsePoint and wants to know more.

1.5. Outline of the rest of this book

To be filled in.

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas non risus. Etiam consectetuer ipsum ac lorem. Suspendisse diam neque, dapibus non, placerat eu, feugiat sit amet, erat. Nulla facilisi. Donec vehicula. Nam sit amet metus. Suspendisse potenti. Fusce at tortor. Nullam non nisl at dolor lobortis vehicula. Fusce sit amet velit. Aliquam nulla. In turpis justo, accumsan feugiat, pharetra sed, tempus et, neque. Vivamus vitae magna quis sapien scelerisque pretium. Ut arcu ligula, condimentum vitae, cursus vel, bibendum a, quam. Phasellus quis orci. Cras ante metus, mattis eu, imperdiet ullamcorper, tincidunt a, libero. Nulla aliquet, metus id molestie egestas, metus magna tristique turpis, accumsan eleifend ligula pede ac metus. Integer tincidunt est ut dolor.

1.6. A note about Drupal

Throughout this book and throughout the ProsePoint software itself, you may see references to something called Drupal. Drupal is the content management system and development platform which serves as a software base upon which ProsePoint is built. It is one of a number of software components (albeit the largest and most pervasive one) which comprises ProsePoint.

You do not need to know anything about Drupal to use ProsePoint or read the rest of this book.

You can find out more about Drupal at it's website http://drupal.org.

1.7. Applicable versions

Unless otherwise noted, this book refers to ProsePoint 0.08.

(Unfortunately, this document has not been updated for quite a while)

Part I. ProsePoint for Users

Chapter 2. ProsePoint Concepts

2.1. Users and roles

ProsePoint uses the concept of roles to distinguish between different levels of users. A user is assigned one or more roles, and each role defines what a user is permitted to do on ProsePoint.

Roles naturally tend to correspond to positions within your organisation. For example, a journalist or photographer would be assigned a Staff role. The person who puts together editions would be assigned the Editor role.

RoleDescription
Staff

A Staff role allows a user to post up pages, stories, images and media files, but they are not allowed to edit nodes created by someone else. Hence, a Staff user is able to create their own content for your magazine or newspaper.

This role is suitable for users such as journalists, photographers, or secretarial staff who need to post up content but are otherwise not involved at a higher level.

Editor

An Editor role allows a user to post up any type of content and edit any node. In addition to pages, stories, images and media files, an Editor user can also create writers, editions, and channels.

This role is suitable for users who oversee the production of editions or manage content created by others.

AdministratorAn Administrator role allows a user to administer the technical aspects of a ProsePoint site.

Note

The Administrator role was added in ProsePoint 0.04.

In addition to the newspaper centric roles explained above, ProsePoint also features two other general purpose roles. These roles are treated slightly differently as they are automatically assigned by ProsePoint when a visitor access the website or when they log in.

RoleDescription
Anonymous UserThis role is assigned to any website visitor who has not logged in. Anonymous Users are allowed to view public content but not allowed to do anything else.
Authenticated UserThis role is assigned to any website visitor who has logged in.

A single user account may have overlapping roles. For example, a journalist may be given temporary management duties so his or her Staff account is also assigned the Editor role. A person may be an editor and also a technical administrator, so his or her account has both Editor and Administrator roles.

A word about the first user

When ProsePoint is installed, it creates the first user account. This user account (usually called admin, but not always) is the superuser account and has full privileges and access to everything in ProsePoint. It is not to be confused with the Administrator role.

2.2. Parts of a ProsePoint page

The following screenshot shows the interesting areas of a ProsePoint web page.

Screenshot: Frontpage (logged in)

Note

If your ProsePoint installation has been customised with a different theme, then some of these areas may be in different locations or may not even be visible.

Note

You have to be logged in for some of these areas to be visible.

Some of these labels are self explanatory, so we will only describe the more interesting ones below.

2.2.1. Navigation Menu

This menu is used for navigating through your ProsePoint site. The navigation menu is special for a number of following reasons.

The available menu items change depending on the privileges of the user ie. an administrator would have more menu entries available than a junior staff writer because an administrator is allowed to perform more actions. (Actually, this is true for all menus, but it tends to happen more with the navigation menu)

The navigation menu tends to hold all menu items which don't fit anywhere else.

You can distinguish which menu is the navigation menu by the menu heading. The heading will always be your username, or Navigation for visitors who are not logged in.

2.2.2. Admin Menu

The Admin Menu only appears for users with partial or full administration privileges.

It contains the same menu items as those under the Navigation Menu's Administer and Create content menu items.

Since the Admin Menu is a subset of the Navigation Menu, it is not actually needed to administer ProsePoint. Everything that can be done through the Admin Menu can be done through the Navigation Menu (albeit with a few more clicks). The Admin Menu is purely for the convenience of users.

2.2.3. Local Tasks

The Local Tasks tabs contain additional context-sensitive links. If there are no context-sensitive links, then the Local Tasks will not appear.

2.2.4. Content Area

The content area is the "main" display area of ProsePoint.

2.3. Nodes

ProsePoint is a content management system (albeit one specifically focussed on newspaper and magazine websites). Let's break that down a bit further.

ProsePoint allows you to create content for, or upload content to, your website and manage it. Content is one of those words with a definition so broad it can cover almost anything. For our purposes, content is anything which has information. For example, a news story is content. An image, photo, or video on your website is content. A comment left on your website by an anonymous visitor is content.

Note

Content can also cover other things which are perhaps not as obvious, but let's not complicate the picture right now.

ProsePoint allows you to create these content things on your website. You can write stories, post stories (that perhaps you didn't write yourself, but someone else has emailed to you), upload photographs, videos, and so on and so forth.

ProsePoint allows you to manage this content online yourself. So, for example, you can edit content items, unpublish content items (ie. make them hidden from the general Internet public), delete content items and so on. This applies as much to textual content (ie. stories, articles, blogs) as non-textual content (such as images and videos).

Note

Trying to edit an image or video using ProsePoint doesn't really make sense, but the principle of managing image or video content remains the same.

In ProsePoint terminology, a node is a general term for a piece of content. A news story is a node. A photo is also a node.

Sometimes we talk not about nodes in general, but about a specific type of node or nodes ie. a story node, or an image node. The type of a node is called it's content type.

For example:

We can say that an article written by so and so is a story node. The content type of that node is story.

We can upload a photo of a public event to our website, and we would say we have created an image node. The content type of that photo is image.

In ProsePoint, there are a variety of different content types, and each is used to store information about a different type of content. Here are a list of content types in ProsePoint:

  • Edition
  • Image
  • Media
  • Page
  • Story
  • Source

2.4. Content types

Here we will explain the different content types found in ProsePoint, what they are used for, and how they relate to each other. We will begin roughly from the bottom up and provide a conceptual overview of each content type. The details of creating, editing and deleting each content type will be provided in the next section.

2.4.1. Page

A page node is used to store written content for a basic web page on ProsePoint. By default, a page node does not show authorship, date information or have comments, so it is best suited for content which rarely changes.

A very common use of page nodes is to show an "About Us" page.

If you are posting written content which does not need to be credited to an author, should not be dated, and/or should not have accept comments, then you are probably looking to create a page node.

2.4.2. Story

A story node is very similar to a page node but has additional features. A story node should be used to store written content when any of the following are desired:

  • Attribution of an author or source
  • A date
  • Comments (although comments can be enabled or disabled on an individual node basis)

A story node can display any of these optional elements.

If you are posting a news story, a blog post, or something similar, you are probably looking to create a story node.

Warning

If you are posting a news story or article, you must use a story node.

2.4.3. Image

An image node is used to store images such as photographs, figures, diagrams, and so on. Image nodes can be inserted into pages or stories.

ProsePoint has native support for images. What does this mean? When people think of images, they tend to think only of an image file. ProsePoint goes beyond this and treats images as nodes. This means you manage your images the same way you manage all your other content. Furthermore, image nodes have additional features which would not be possible if it were just an image file.

  • Image nodes have a title (which is distinct from the image filename)
  • Image nodes have a descriptive caption, and can be dated or show authorship (if your administrator has configured ProsePoint to do so).
  • Image nodes can be shown in different sizes ie. thumbnail, small, medium, large. These are automatically generated.
  • Image nodes can unpublished.

The power of natively managing images as nodes becomes more apparent when image nodes are inserted into pages and stories. Any updates or edits to an image node also affects any page or story ("the parent") which displays that image ("the child").

  • If you edit the child image node and use a different photo, that photo (or whatever size version you chose) will be updated in the parent page or story
  • If you delete the child image node, it will disappear from the parent page or story.
  • If you unpublish the child image node, it will also disappear from the parent page or story.
  • If you later republish the child image node, it will reappear in the parent page or story.

In all these instances, you do not have to edit the parent page or story. ProsePoint will take care of the changes for you.

2.4.3.1. Image file restrictions

Image files to be uploaded must be in jpeg, png, or gif format [1].

2.4.4. Source

A source node represents:

  • A person who is the writer of a news story, or
  • A source of a news story.

For the first case, a distinction needs to made between a writer of a news story, and an author of a story content item.

In ProsePoint, whenever a user creates a node or content item, whether that is a story, image or something else, that user is the author of that node. An author of a node can also be thought of as the owner of that node.

For newspapers, the source of a news story and the author of a news story may not be the same person. For example, Bob is the editor of a ProsePoint newspaper website, and Jane is a journalist in another city covering a particular news story. Jane composes her report and emails it to Bob. Bob then uploads the news story to his ProsePoint site.

For this news story:

  • Bob is the author because he created the node. The story is his node.
  • Jane is the source because she wrote the story. She deserves the credit for producing the story.

Furthermore, Jane may not even have a ProsePoint user account.

By distinguishing between the author and the source of a news story, ProsePoint accommodates for such a situation easily. It's just unfortunate that it may cause some initial confusion for a new ProsePoint user.

There are also some side benefits to this approach. Pseudonyms and fictitous writers can be handled. For example, you might have a journalist Jane who produces regular news stories, but also writes a weekly health column as Doctor Dorothy. For Jane's normal stories, the source would be Jane Surname. For her health stories, the source would be Doctor Dorothy.

And then when Jane goes on holidays, you can assign another journalist Mary to cover for Jane. Mary would create news stories with Doctor Dorothy as the source.

If your newspaper or magazine obtains news stories from a third party, you can create a source to represent them. For example, you might have a source node called Google News, or Associated Press, or even Guest Writer.

Note

Prior to ProsePoint 0.04, this content type was known as writer. For ProsePoint 0.04, writer was renamed to the more intuitive source.

2.4.5. Edition

An edition node is used to group selected stories into editions or issues of a publication.

Editions are identified by date, week, month, yearly quarter, or whatever label you wish to use.

Here are some examples. The edition identifier is bracketed.

  • MyLocal News (25th September 2008)
  • MyLocal News (22nd-28th September 2008)
  • MyLocal News (Christmas Eve 2008)

or

  • Cats (September 2008)
  • Cats (Vol 1, Issue 2)
  • Cats (Winter 2008)

The title of an edition should always be the same as the title of the associated publication. The only way to distinguish between editions of the same publication (aside from looking inside the contents of each edition) is by looking at the edition identifier.

An edition is associated with a publication series through a channel. This is explained in a later section.

2.4.5.1. Editions contain stories

An edition contains lists of story nodes, which are the stories to be published in that edition.

There are currently two lists in each edition, and they differ only in how they are displayed.

Headlines

This list contains stories which are more important and are presented with more prominence when the edition is shown.

If an edition is displayed in full view, Headlines stories are shown as a teaser with photo (if there is a photo).

If an edition is displayed in shortened teaser view, Headlines stories are listed by title.

Other Stories

This list contains stories which are less important and are presented with less prominence when the edition is shown.

If an edition is displayed in full view, Other Stories stories are listed by title.

If an edition is displayed in shortened teaser view, Other Stories stories do not appear at all.

2.5. Channels

ProsePoint uses the concept of channels to categorise editions and stories sharing a common topic or feature. Channels are a flexible but abstract idea, so they may be confusing at first. A channel can represent any of the following:

  • A recurring periodical publication.
  • A recurring section of a publication (such as a weekly newspaper column).
  • A pipeline of editions or stories sharing a common topic (ie. sports or cats), or common author (ie. a blog).

Note

Channels are not nodes. In older versions of ProsePoint prior to 0.07, channels were implemented as nodes, but not anymore. In techspeak, channels are taxonomy terms. However, you do not need to know what terms are to use channels in ProsePoint.

The following are examples of channels.

Example 1

You run a small weekly local newspaper online called MyLocal News. Since it's volunteer driven and community focussed, there are only a handful of news stories every week so there's no need to split your newspaper up into different sections. You would create one channel called MyLocal News to represent your newspaper.

Example 2

MyLocal News grows over time, and soon enough, it has many news stories every week. You decide to partition your newspaper into separate sections. The largest topics in MyLocal News are sports, and community events, so you decide to split those two up.

You would create a channel called Sport and a channel called Community, and another channel called News to cover stories which are neither sports or community events related. These three should be represented by channels because they are recurring sections of your publication.

You then repurpose MyLocal News to show stories which are front page headlines.

Note

You can show a story in more than one channel. In fact, front page stories are also often shown in their respective section channel.

Example 3

You publish a monthly online magazine for cat lovers called, unsurprisingly, Cats. You would create one channel called Cats to represent your magazine.

Example 4

Later, you publish another monthly online magazine for dog lovers on the same website. Unsurprisingly, you call this magazine Dogs. You would create another channel called Dogs. Your website now has two channels, one for each magazine.

2.5.1. Channel Modes

In ProsePoint, channels work in one of two ways:

  • Story listing, or
  • Scheduled editions.

2.5.1.1. Story listing

A story listings channel displays stories with the most recently posted appearing first. This is essentially a blog format. Editions are not used at all.

This is the default channel mode.

2.5.1.2. Scheduled editions

A scheduled editions channel displays the most recently published edition of that channel. It uses scheduling to decide which edition to show (scheduling is explained in a later section).

This channel mode requires a bit more work as it uses editions. However, it provides more control over when stories are displayed (by using scheduling), and allows for complex layouts (by using editions).

In this mode, you can think of a channel as a series of editions.

2.6. Scheduling of editions

Scheduling is used in channels to decide which edition to display. This only applies to channels in scheduled editions mode.

Editions are inextricably linked to its channel. Each edition must belong to a channel. To use a real world analogy, it doesn't make sense that a newspaper issue can exist if it doesn't belong to a newspaper publication.

Each edition has a Schedule For property, which schedules when that edition will be shown as the current edition of its channel. When a visitor to your website “views” a channel, they will see the most recent published edition for that channel. This is how ProsePoint accomplishes scheduling of editions in an easy, intuitive way.

Here is an example scenario.

Let's pretend it is September 4th 2008, and you are the owner of MyLocal Daily, a daily newspaper website. You have already decided on the stories that will be published on September 5th and 6th, so you have two editions, MyLocal Daily (September 5th) and MyLocal Daily (September 6th), created and ready to go.

The Schedule For of MyLocal Daily (September 5th) is September 5th, and the Schedule For of MyLocal Daily (September 6th) is September 6th.

Tomorrow comes around, and it is September 5th. When your website visitors view the MyLocal Daily channel, they are shown MyLocal Daily (September 5th) because that is the most recent edition. MyLocal Daily (September 6th) is in the future so it is not eligible.

Another day passes, and it is now September 6th. When your website visitors view the MyLocal Daily channel, they are shown MyLocal Daily (September 6th) because that is now the most recent edition.

Another day passes, and it is now September 7th. It is also a Sunday, and your newspaper doesn't publish on Sundays. When your website visitors view the MyLocal Daily channel, they are shown MyLocal Daily (September 6th) because that is still the most recent edition.

Note

If you have a news story that is to be shown over several editions, you include the story in those editions.

For example, if you had a news story that you wanted to show on September 5th and 6th, you would include that story in both MyLocal Daily (September 5th) and MyLocal Daily (September 6th).

2.7. Publishing workflow

A workflow is a sequence or process of steps that achieve an end result. In the case of ProsePoint, the main objective is to publish news stories, and it is important to understand how ProsePoint facilitates this by supporting publishing workflows.

The following workflows are suggested ways of using ProsePoint within your organisation. However, since every organisation and situation is different, feel free to adapt them to your particular circumstances.

2.7.1. Single person workflow

If you are using ProsePoint for publishing a small newspaper or magazine and you are the doing all the work yourself, it is easy for you to keep track of everything. The publishing workflow is pretty straightforward and should be similar to the following.

  1. Create a story:

    • Source your news story, either by writing it yourself or obtaining it from another party.
    • Add it to ProsePoint, including adding any required images or video files.
    • If this story is from a new source, you may need to create a new source node.
    • Select the channel(s) that the story belongs to.
    • Mark your story as Published.

      Warning

      You must mark your story as Published, otherwise it may not appear in its channel, or you may have difficulty adding it to an edition.

    If your story is to appear only in story listing channels, this is all you need to do.

    If your story is to appear in scheduled editions channels, please continue to the next step.

  2. Add the story to an edition:

    • Either create a new edition, clone an edition, or edit an existing edition.
    • Add the story to the edition's Headlines or Other Stories list.
  3. Schedule the edition to be published (if it isn't already).

2.7.2. Multiple staff workflow

When there is more than one person using ProsePoint, the workflow is a little bit more complex because of the need to facilitate coordination and communication between various staff. The duties which were previously assumed by the same person are now spread amongst more than one person. However, the general idea of first creating stories and then optionally adding stories to editions remains the same.

  1. Staff create a story:

    • Users with Staff privileges add a story to ProsePoint, including adding any required images or video files.
    • If this story is from a new source, an editor user may need to create a new source node beforehand.
    • The story's channel(s) need to be selected.
    • The story is marked as Published.

      Warning

      You must mark your story as Published, otherwise it may not appear in its channel, or you may have difficulty adding it to an edition.
  2. An editor adds the story to an edition:

    • A user with editor privileges creates a new edition. Or optionally, he or she may clone or edit an existing edition.
    • The editor user adds the story to the edition's Headlines or Other Stories list.
  3. The editor schedules the edition to be published (if it isn't already).

Note

The user who posts a story may also be the user who adds it to an edition.

2.7.3. Multiple staff workflow with peer review

This workflow builds upon the previous one by incorporating an additional review step in the process.

  1. Staff create a story for review:

    • Users with Staff privileges add a story to ProsePoint, including adding any required images or video files.
    • If this story is from a new source, an editor user may need to create a new source node beforehand.
    • The story is marked as Ready for review.
  2. The story is reviewed by another user:

    • Another user selects the story from a list of stories marked Ready for review, and reviews it. He or she may make changes to the story, or communicates suggestions to the original poster.
    • This step repeats until all parties are satisfied, and then the story is marked as Published.

      Warning

      You must mark your story as Published, otherwise it may not appear in its channel, or you may have difficulty adding it to an edition.
  3. An editor adds the story to an edition:

    • A user with editor privileges creates a new edition. Or optionally, he or she may clone or edit an existing edition.
    • The editor user adds the story to the edition's Headlines or Other Stories list.
  4. The editor schedules the edition to be published (if it isn't already).

2.7.4. Revision control

To facilitate workflows involving more than one person, ProsePoint contains revision control functionality for page and story nodes. This allows easy tracking of the changes of a node over time.

2.8. Miscellaneous topics

2.8.1. Shortcuts

To be continued.

2.8.2. Teaser images

To be continued.



[1] Future versions of ProsePoint may handle more image file types.

Chapter 3. Tutorials

3.1. Publishing your first story

Warning

This tutorial is a work in progress and may contain inaccuracies. In particular, the screenshots have not been created, and likely won't be created until the relevant editing screens have stabilised. As of writing, this tutorial is reasonably accurate for ProsePoint 0.08.

Warning

If your ProsePoint website is not using the default theme, some pages may appear different from what's shown in the screenshots. Furthermore, the ordering of some fields may also be different.

This tutorial will lead you through a number of steps leading up to posting a news story, including creating a source node and inserting images. Many of the steps are self explanatory, so only interesting parts will be detailed.

Setup

Before you begin, please make sure you have the following available:

  • The text of your story (also known as copy).
  • An image or photo to upload, preferably between 500x500 and 1000x1000 pixels in size. This image should be available as a file stored on your local computer.

Note

If you don't have a passage of text handy, you can copy and paste the following paragraph one or more times. A lot of people do this.

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas non risus. Etiam consectetuer ipsum ac lorem. Suspendisse diam neque, dapibus non, placerat eu, feugiat sit amet, erat. Nulla facilisi. Donec vehicula. Nam sit amet metus. Suspendisse potenti. Fusce at tortor. Nullam non nisl at dolor lobortis vehicula. Fusce sit amet velit. Aliquam nulla. In turpis justo, accumsan feugiat, pharetra sed, tempus et, neque. Vivamus vitae magna quis sapien scelerisque pretium. Ut arcu ligula, condimentum vitae, cursus vel, bibendum a, quam. Phasellus quis orci. Cras ante metus, mattis eu, imperdiet ullamcorper, tincidunt a, libero. Nulla aliquet, metus id molestie egestas, metus magna tristique turpis, accumsan eleifend ligula pede ac metus. Integer tincidunt est ut dolor.

3.1.1. Creating a source

First, we will create a new source node to represent you. You don't have to do this step for every story you post, only when there is a new source or author.

Note

If you trying out this tutorial on a ProsePoint installation where you only have Staff access, you won't be able to create source nodes. In this case, you'll have to skip this step and use an already existing source.
  1. Visit the Create Source page
    • You can do this by using either the Navigation Menu or the Admin Menu.
    • If you choose to use the Navigation Menu, click on Create content, and then click on source.
    • If you choose to use the Admin Menu, select Content Management => Create content => Source.

      Note

      If you don't know what the Navigation Menu or the Admin Menu are, please have a look at Parts of a ProsePoint page.
    • You should see a page like the following:

      Screenshot: Create Source page

  2. Enter a name for the new source node.
    • You can use your own name for this.
    • For now, please ignore the other fields and values. They are all optional. You only need a name to create a source.

      Screenshot

  3. Click Save.
    • You should now see your newly created source

      Screenshot

3.1.2. Creating a story

Next, we will create the story node.

  1. Visit the Create Story page
    • Again, this can be done by using either the Navigation Menu or the Admin Menu.
    • If you choose to use the Navigation Menu, click on Create content, and then click on Story.
    • If you choose to use the Admin Menu, select Content Management => Create content => Story.
    • You should see a page like the following:

      Screenshot

  2. Enter a title and subtitle for the new story node.
  3. Leave the status as Draft.
  4. Select the channel(s) this story is to appear in. You can select more than one channel by holding down the CTRL key and clicking.

    Note

    If you are using editions for your channel, you should still select the channels for your story here.
  5. Enter a source for the new story node.
    • Enter the first letter of the name of the source you created in the previous stage. A drop down list should appear presenting the available options.
    • If you didn't create a source in the previous stage, try entering 'J' or 'M' and see what you get.

      Screenshot

      Note

      The textfield for the By field is known as an autocomplete textfield. You will encounter these a lot in ProsePoint. To use them, just enter the first few letters of what you're after, and a drop down list of available values should then automatically appear.
  6. Enter a date for the story.
    • Upon clicking in the Date textfield, a date selection calendar should appear (if javascript is enabled in your browser). You can either use the calendar to select your date, or you can enter the date in dd-mm-yyyy form yourself.

      Screenshot

  7. Enter the text of the story into the Body field.
    • You can experiment with formatting options (such as bold, underline, bullets etc.) if you wish.

      Screenshot

      Note

      Some formatting options (particularly tables and sometimes indenting) require the input format of the story to be set to Full HTML. To do this, click on Input format (just below the Body textarea) and select Full HTML.

      If you do not see Input format or a Full HTML option, then you do not have sufficient privileges to do this.

  8. Click Preview.
    • For now, please the rest of the options and scroll down to the bottom of the page to find the Preview button.
    • You should now see a preview of your story.

      Screenshot

    • Notice that the preview shows your story twice. At the top, it shows your story in teaser view. Below that, it shows your story in full view.
    • Previewing is an optional step. It is particularly useful if you find yourself clicking Save and then Edit a lot.
  9. Click Save.
    • You should now see your newly created story.

      Screenshot

3.1.3. Creating and inserting an image

Now, lets assume you forgot to insert your image, so we'll go back and edit your story to do that.

Normally, nodes in ProsePoint are created through a Create ... page. In this stage, we'll show you another way to create nodes that only applies for insertion of images and media files.

  1. Click on Edit to edit your newly created story.
  2. In the visual editor, move the cursor so it is just before the first letter of the first word of a paragraph.
    • Inserting an image causes a paragraph break ie. the surrounding text is broken into two paragraphs. Hence it is a good idea to insert at the beginning of a paragraph.
  3. In the visual editor, click on the tree icon (without the red cross).
    • This activates the image insert wizard as a popup window
  4. In the popup window, click on Upload a new image.
    • This takes you to an Upload image page. This page is very similar to the Create image, but with many extra options removed to keep things simple.
  5. In the Upload image page, enter a title, browse for your image file, and enter an optional caption.
    • These values apply to the soon-to-be-created image node.
  6. Click Save.
    • This will create your new image node and then take you to the Insert image node page.
  7. In the Insert image node page, fill in the fields as desired.
    • Image title, Caption, Size and Alignment are self explanatory.
    • Link Url is the destination web page that the image will link to. A destination value is suggested, but this is optional. If you leave this field empty, the image will not link to anything.
    • Link Target controls whether clicking on the image opens a new window for Link Url. If Link Url is empty, this setting has no effect.
    • Teaser Image specifies whether the inserted image should be shown in the teaser of the parent story. For more information, see blah.
    • The values on this page apply to the image insertion as it appears in the parent story. They do not have to be the same as the values of the image node itself.
  8. Click Insert into post.
    • This will insert your image into your story and close the popup wizard. You should now see the image in the visual editor.
    • Now you want to save your story.
  9. Click Save.
    • You should now see your story with the inserted image. (ToDo: Insert screenshot)

3.1.4. Marking as Published

After a couple of rounds of editing, your story is complete and ready for publishing. You need to mark your story as Published.

  1. Click on Edit to edit the story.
  2. In the Status drop down list, select Published.
  3. Click Save.

If your organisation's policy requires peer review of stories, then instead of marking your story as Published, you would mark it as Ready for review. Your peer, manager or editor would review the story and when all parties are satisfied, it is marked as Published.

Marking a story as Published does a number of things:

  • It allows the story to be viewed by visitors to your website (but if the story was not assigned to a channel, visitors will not be able to find it).
  • If the story was assigned to a story listings channel, the story immediately appears in the channel's story list. Congratulations, your story is now published.
  • If the story was assigned to a scheduled editions channel, the story does not immediately appear in the channel. Instead, it is now eligible for inclusion in an edition.

    When an edition's Headlines or Other Stories list is being edited, your story will now appear in the list of available stories that can be added.

    Your story needs to be added to an edition before it will appear in the channel. That is for another tutorial.

Chapter 4. To be continued

To be continued . . .

Part II. ProsePoint for Administrators

Chapter 5. System Requirements

Installing ProsePoint requires a moderate level of familiarity with computer servers and internet technology. If the information in this chapter doesn't make sense to you, please find a friend or colleague who can follow it. Alternatively, you can seek commercial help in installing ProsePoint.

Note

Some of the content in this chapter is loosely derived from Drupal documentation.

5.1. Technology Stack

ProsePoint operates on top of other software and computer technologies. You must already have these other components of the “technology stack” in order to install and use ProsePoint. They are briefly described here, from the bottom up.
Server
A server is a computer or electronic device which provides services or information to other computers on a network.
Operating System
Basic software which is needed to run the server. Examples of operating systems are Unix, Linus, BSD, and Windows.
Database
A structured collection of records. ProsePoint uses a database to store most of the content of your site.
Web Server
Software which accepts web page requests and sends web pages to other computers. The most cited example of this is Apache.
PHP
A programming language used to write programs to generate dynamic web pages.
Drupal
An open source content management and development platform for building websites.

Note

ProsePoint uses a modified version of Drupal. This is included with ProsePoint, so you shouldn't obtain Drupal separately.

5.1.1. Recommendations

If you have the luxury of choosing your own server setup, this is the recommended technology stack for running ProsePoint:

  • Apache 2.0.x or 2.2.x with the mod_rewrite extension enabled.
  • MySQL 5.x
  • PHP 5.2.x

Please read on for detailed requirements information.

5.2. Database

The recommended database is MySQL 5.0.

5.2.1. MySQL 4.1 or MySQL 5.0

ProsePoint supports MySQL 4.1 or higher, though MySQL 5.0 is recommended.

ProsePoint makes use of some features not available on some inexpensive hosting plans so please check that your host allows database accounts with the following rights:

SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES

Note

If your system/host is running MySQL 4.1 or newer and you receive the error "Client does not support authentication protocol requested by server", address the problem by following the instructions provided by MySQL AB. There is a minor OS issue with some MySQL 5+ installations primarily on Windows but affecting some versions of Unix/Linux as well.

5.2.2. PostgreSQL 7.4 or higher

ProsePoint supports PostgreSQL 7.4 or higher, although it is not as widely tested.

5.3. Web Server

The recommended web server is Apache 2.x.

ProsePoint requires a web server that supports clean urls. This usually means an Apache web server with the mod_rewrite extension enabled.

5.3.1. Apache

ProsePoint supports Apache 1.3 or 2.x. The majority of ProsePoint development is done using Apache 2.x so there is more testing performed on this plattform.

The Apache mod_rewrite extension is the usual way of supporting clean urls.

mod_security

Please ensure Apache is not running mod_security. mod_security interferes with the execution of PHP programs and has been known to cause ProsePoint to intermittently mysteriously fail.

5.3.2. Microsoft IIS

ProsePoint should work with Microsoft IIS6 or IIS7 (though it is not recommended), provided you can get clean urls to work. For clean urls with IIS, you will need a third party product. This is outside the scope of ProsePoint.

5.4. PHP

The recommended version of PHP is PHP 5.2.

ProsePoint will work with PHP versions 5.1.x and 5.2.x. ProsePoint does not yet work with PHP 5.3.x.

PHP Configuration Requirements

  • PHP memory of 64MB or higher is recommended. Depending on whether you configure ProsePoint to accept larger file sizes for image uploads, you may need PHP memory of 96MB or higher.
  • The PHP extension for connecting to your chosen database needs to be installed and enabled. ProsePoint currently supports database connectors: mysql (the original MySQL extension), mysqli (an improved connector for newer MySQL installations), and pgsql (for PostgreSQL).
  • ProsePoint requires the following PHP non-default configuration directives to work:
    • session.save_handler: user
    • error_reporting set to E_ALL & ~E_NOTICE.
  • The following setting is recommended: session.cache_limiter: nocache
  • If you wish to use the TinyMCE compressor in ProsePoint, you must ensure zlib compression is off (it is off by default in most installations).
  • PHP Safe mode is off or disabled.

.htaccess

Some of the above settings are contained in the default .htaccess file included with ProsePoint so you don't need to set them yourself if:

  • You are using Apache,
  • Apache has been configured to read .htaccess files ie. AllowOverride is not None, and
  • PHP is installed as an Apache module.

See the PHP manual for how to change configuration settings for other interfaces to PHP.

In some shared hosting environments, access to these settings is restricted. If you cannot make these changes yourself, please ask your hosting provider to adjust them for you.

5.5. Troubleshooting

If you meet these requirements but still have problems with your site, you might find some help in the Drupal Webhosting Troubleshooting FAQ.

5.5.1. CPanel with site builder component

Some web hosting providers use CPanel on their servers with a site builder component that clashes with ProsePoint.

CPanel (or the site builder component) intercepts all references to files with zen in the pathname and redirects it to their own directories. This interferes with any PHP program or files which reside in, or use, a zen directory.

For example, if you wanted to write about Zen buddhism in a file named about-zen-buddhism.html, you can't. CPanel interferes.

Unfortunately, ProsePoint does have a zen directory so CPanel interferes with its correct operation.

If you are so affected, please ask your hosting provider to turn off the site builder component or else, change hosting provider.

Chapter 6. Installing ProsePoint

6.1. Before installing

Installing ProsePoint requires some familiarity with computer servers and internet software. If any of the following doesn't make sense to you, please don't try it. Get someone else to do it for you.

What follows is one way of installing ProsePoint using the command line. It is not the only way, and technology experts are free to adapt the steps as they see fit.

A guide to installing ProsePoint using graphical front-ends is outside the scope of this book as such methods are highly dependent on the hosting provider and server setup.

Note

Before you install ProsePoint, please ensure you have met all the necessary system requirements.

6.2. Creating a database

You need to create a database with the appropriate user, password, and user privileges. Please follow the sample script below, adapting to your server operating conditions.

  • Execute the mysql command line. In the command below, you may change root to some other mysql username with sufficient privileges.

    $ mysql -u root -p

  • In the mysql command line, create a database. Substitute your_database with the desired name of your database.

    mysql> create database your_database;

  • Create a database user. ProsePoint will act as this username for accessing the database. Substitute your_database, your_username and your_password with the desired values.

    mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES ON your_database.* TO 'your_username'@'localhost' IDENTIFIED BY 'your_password';

    Please do not forget the single quotes nor the semicolon.

  • Refresh database privileges and quit out of the mysql command line.

    mysql> flush privileges;

    mysql> \q

6.3. Installing the source code

The next step is to copy the ProsePoint source code to the appropriate location and ensure directory and file permissions are correct.

ProsePoint can be installed at your webroot or in a subdirectory underneath. If you install at your webroot, ProsePoint will be accessible by a web address like http://yoursite.yourdomain.com. If you install in a subdirectory, ProsePoint will be accessible by a web address like http://yoursite.yourdomain.com/your_subdirectory.

Decide where you will install ProsePoint. For the purposes of this section, we will call this directory the ProsePointRoot.

Note

You can recognise the ProsePointRoot because it will, after following this procedure, contain subdirectories such as includes, modules, scripts, misc, and sites.

Note

Depending on your web server configuration, your webroot may be /var/www or /var/www/html or something else entirely. You need to know where your web server's webroot is located.
  • Uncompress the ProsePoint compressed archive into any directory on your server.

    $ tar fxz prosepoint-0.03.tar.gz

  • Create the ProsePointRoot directory if it doesn't already exist.

    $ mkdir ProsePointRoot

  • Move the extracted files to your ProsePointRoot and remove the (now-empty) prosepoint-0.03 directory. Enter your ProsePointRoot.

    $ mv prosepoint-0.03/* prosepoint-0.03/.htaccess ProsePointRoot

    $ rmdir prosepoint-0.03

    $ cd ProsePointRoot

    The rest of the steps below assume your current directory is the ProsePointRoot.

  • Create a settings.php file. This file is updated during installation by the ProsePoint install process and tells ProsePoint how to access the database.

    $ cp sites/default/default.settings.php sites/default/settings.php

  • Ensure files and directory permissions are correct. During installation, ProsePoint needs to make changes to a few files and directories underneath ProsePointRoot.

    $ chmod 777 sites/default

    $ chmod 666 sites/default/settings.php

Note

Older versions of ProsePoint had an image_import directory which also need extra permissions. This no longer applies from ProsePoint 0.03 onwards.

6.4. Continuing the installation

Open your web browser and visit the web address that corresponds to ProsePointRoot. You should see a web page titled Database Configuration.

6.4.1. Database configuration

Screenshot: Database Configuration

Please enter the MySQL database related values you chose for your_database, your_username and your_password when you created your database.

6.4.2. Configure Site

Screenshot: Configure Site

After the database has been setup, you will be presented with a form for filling out a list of other installation parameters. Most of them are self explanatory, but some deserve some explanation.

Note

At the top of this page, you may be asked to write-protect sites/default and sites/default/settings.php. You can either do this before proceeding or afterwards in the post-installation step. If you write-protect sites/default, please be careful not to accidentally write-protect sites/default/files in the process.
Site name
The name of your website.
Site e-mail address
Self-explanatory.
Username, E-mail address, Password, Confirm password
These are account settings for the first ProsePoint account (which is also the administrator account and usually called admin).
Default time zone
Self-explanatory.
Clean URLs
If your web server supports clean URLs, you will be given the option to enable clean URLs for your website.
Update notifications
Self-explanatory.
File system path
This is where ProsePoint will store uploaded files. The default value should be sufficient. If you change this to point to another directory, please make sure the directory exists and is writable by the web server before proceeding.
Temporary directory
This is where ProsePoint will store temporary uploaded files. The default value should be sufficient. If you change this to point to another directory, please make sure the directory exists and is writable by the web server before proceeding.

Warning

Both File system path and Temporary directory must refer to directories on your computer server which exist and are writable by your web server.

6.4.3. Choose ProsePoint variant

Screenshot: Choose ProsePoint Variant

On this page, you can choose which variant of ProsePoint you would like to install. Please make your selection and continue.

6.4.4. Installation complete

Screenshot: Installation Complete

At this page, ProsePoint has been installed on your server. If there were any problems encountered, error messages will appear. If all goes well and there are no errors, you will see a list of messages describing what was done as part of the installation. You can ignore these messages and proceed to the next step.

6.5. Post installation steps

After successfully installing ProsePoint, you should write-protect your sites/default directory and settings.php file. This is highly recommended.

$ chmod 755 sites/default

$ chmod 644 sites/default/settings.php

Important

Write-protecting sites/default and settings.php is necessary for keeping your ProsePoint website secure.

Congratulations! You have successfully installed ProsePoint.

Note

If you have followed these instructions, but still run into problems with installation, you might find some help in the Drupal Webhosting Troubleshooting FAQ.

Chapter 7. Upgrading ProsePoint

Upgrading ProsePoint follows a general sequence of steps which is explained in the next section. In most cases, the general procedure is all you need to follow. However, if there are special considerations for upgrading to specific versions of ProsePoint, they will be described in a separate section.

7.1. General upgrade procedure

Note

The screenshots in this procedure were taken during an upgrade from version 0.03 to 0.04 of ProsePoint. If you are upgrading a different version, you may see slightly different pages.

7.1.1. Backup your database

Upgrading ProsePoint will change your database and in case of emergency, or something goes wrong, you may need to roll back.

Warning

It is very important that you backup before attempting an upgrade. Never assume that an upgrade will always work first time.

For instructions on how to backup your database, please ask your hosting provider.

7.1.2. Backup your filesystem

It is recommended that you backup your filesystem (from the webroot downwards) as well, or at least, make a copy of it somewhere. This is not as critical as backing up your database, but is good practice nonetheless.

For instructions on how to backup your filesystem, please ask your hosting provider.

7.1.3. Place your site offline

Log into your site as the first user and place your site offline.

  • Once you are logged into your site, visit Administer => Site configuration => Site maintenance, select Off-line, and click Save configuration.

Once the site is offline, you should see a message Operating in off-line mode. when you visit the other pages of your site.

Tip

If you log out while the site is offline, visit the page ?q=user of your site to log back in. Note that only users with administrative privileges are allowed to log in while the site is offline.

7.1.4. Upgrading the source code

Next, you want to replace the old source code of ProsePoint with the new source code, but in such a way that the file .htaccess and the subdirectory sites is preserved.

It is recommended that you completely replace the entire ProsePoint directory. If you only copy or upload changed files, obsolete files may not be deleted and this may confuse ProsePoint.

The exact process of updating the source code will depend on your hosting provider and account privileges. However, a sample command line scenario is presented below.

Note

For the sample procedure below, it is assumed you are executing from a privileged account ie. root. If not, you may need to prepend sudo for some commands.

Whenever you see prosepoint-0.04 in the sample procedure, please substitute with the version of ProsePoint you are upgrading to.

  • Move the directory tree into a separate location backup, where backup is a directory which already exists ie. /tmp, home/user etc.

    # mv ProsePointRoot backup

  • Extract the new ProsePoint source code, and make it the new ProsePointRoot.

    # tar fxz prosepoint-0.04.tar.gz

    # mv prosepoint-0.04 ProsePointRoot

  • Copy .htaccess and sites from the backup into the new ProsePointRoot.

    # cp backup/ProsePointRoot/.htaccess ProsePointRoot

    # rm -rf ProsePointRoot/sites

    # cp -rp backup/ProsePointRoot/sites ProsePointRoot/sites

    Note

    You may need to check and ensure that your ProsePoint filesystem (which defaults to sites/default) is still readable and writable by the web server.

Once the source code has been updated, the layout of your site may be broken. That is normal, and do not be alarmed. The next step will address this.

7.1.5. Run update.php, part 1

Visit the update page of your site. The update page is the file update.php from your webroot

For example, if your site is www.example.com, visit www.example.com/update.php.

You should see a page similar to the following:

Screenshot: Update.php, part 1

  • Click Continue to proceed.

7.1.6. Run update.php, part 2

You should now see a page similar to the following:

Screenshot: Update.php, part 2

  • Click Update to proceed.

If you're curious, you can expand the fieldset and look at what updates will be applied.

Screenshot: Update.php, part 2 expanded

However, unless you know what you're doing, please don't change anything here. Just click Update to proceed.

7.1.7. Run update.php, part 3

You should next see a page with a progress bar showing the state of the updates.

Once this has finished, you should see a page similar to the following:

Screenshot: Update.php, part 3

This page describes what was attempted, and the results. If you do not see any error messages here, then your database was successfully updated.

7.1.8. Verify your site and place it back online

Visit various pages of your site to verify that the upgrade was successful. Once you are satisfied, place your site back online.

  • Visit Administer => Site configuration => Site maintenance, select Online, and click Save configuration.

7.1.9. Cleaning up

During this procedure, you would have made backups of your database and your filesystem. You may like to keep these backups for a period of time before deleting them.

7.2. Partially upgrading the source code

In some cases, a ProsePoint upgrade will only affect files underneath the profiles directory. If so, instead of updating the entire source code tree, you may substitute a simpler procedure that updates just the profiles directory (and everything below it).

The upgrade notes for each new version of ProsePoint will state if a partial source code upgrade is permissible. If you are unsure, or if there is no mention of partial source code upgrades, then always update the entire source code tree.

A sample simpler procedure is as follows:

  • Backup the directory tree into a separate location backup, where backup is a directory which already exists ie. /tmp, home/user etc.

    # cp -rp ProsePointRoot backup

  • Extract the new ProsePoint source code.

    # tar fxz prosepoint-0.04.tar.gz

  • Copy profiles from the new source code into ProsePointRoot.

    # rm -rf ProsePointRoot/profiles

    # cp -rp prosepoint-0.04/profiles ProsePointRoot

7.3. Upgrading from 0.03 to 0.04, 0.05 or 0.06

These are extra notes for upgrading ProsePoint from version 0.03 to one of 0.04, 0.05 or 0.06.

Note

This section was originally written for upgrading from 0.03 to 0.04 but also applies to upgrading to 0.05 or 0.06. In the rest of this section, wherever you see 0.04, treat it as 0.05 or 0.06.

7.3.1. Content types are reconfigured

ProsePoint 0.04 made significant changes to the ProsePoint main content types, and the settings for these content types are reconfigured during the upgrade from 0.03 to 0.04. In addition, the content type writer was renamed to the content type source.

If you made any customisations to the affected content types, you will need to go back and re-customise them to your liking.

7.3.2. Permissions are reconfigured

Similarly, permissions are also reconfigured during the upgrade from 0.03 to 0.04. However, only those permissions which were using default values are reconfigured. If you did not make any of your own changes to permissions, you can ignore this.

If you did make changes to permissions, you will need to go back and review them. The update results page will tell you which permissions were reconfigured, and which were not.

7.3.3. Themes are disabled

Upgrading ProsePoint from 0.03 to 0.04 will disable all your themes. This is due to a bug which will be fixed in the near future. In the meantime, you can re-enable your theme(s) yourself.

  • Visit Administer => Site building => Themes, tick the Enabled checkbox for all themes you want to re-enable, and click Save configuration.

7.4. Upgrading from 0.04 to 0.05 or 0.06

These are extra notes for upgrading ProsePoint from version 0.04 to 0.05 or 0.06.

ProsePoint versions 0.05 and 0.06 are bugfix versions with no new features. Hence, versions 0.04 to 0.06 are very similar to each other.

7.4.1. Themes are disabled

Upgrading ProsePoint to 0.05 or 0.06 will disable all your themes. This is due to a bug which will be fixed in the near future. In the meantime, you can re-enable your theme(s) yourself.

  • Visit Administer => Site building => Themes, tick the Enabled checkbox for all themes you want to re-enable, and click Save configuration.

7.5. Upgrading to 0.07 or 0.08

ProsePoint versions 0.07 and 0.08 are very similar. For the purposes of upgrading, they can be treated as the same. In the rest of this section, everything that applies to version 0.07 below also applies to 0.08.

7.5.1. Upgrading from 0.03

Unfortunately, upgrading directly from 0.03 to 0.07 is not supported. Due to the differences between these versions, it is not possible to upgrade in one step. Instead, please first upgrade to 0.06, and then upgrade again to 0.07.

7.5.2. Upgrading from 0.04-0.06

To upgrade from any of versions 0.04, 0.05 or 0.06 to 0.07, please follow the general upgrade procedure.

7.5.3. Themes are disabled

Upgrading ProsePoint to 0.07 will disable all your themes. This is due to a bug which is still present. As a workaround, you can re-enable your theme(s) yourself.

  • Visit Administer => Site building => Themes, tick the Enabled checkbox for all themes you want to re-enable, and click Save configuration.

Chapter 8. To be continued

To be continued, with information on customising, administering etc.

Part III. ProsePoint for Developers

Chapter 9. Themeing

9.1. Themes

ProsePoint is based upon Drupal so ProsePoint themes are also Drupal themes. The difference between the two lies in the level of themeing features available in the theme.

A generic Drupal theme may not have customisations for things which are specific to ProsePoint. For example, a Drupal theme won't have themeing for the extra fields in story nodes, or won't know anything about the ProsePoint visual editor.

These differences are mostly cosmetic. If you use generic Drupal themes on a ProsePoint website, it will still work. It just might not look as polished.

9.1.1. Required knowledge

Developing a theme for ProsePoint requires some knowledge of CSS, html, and Drupal themeing. Please refer elsewhere for information on these topics.

9.1.2. Directory for storing themes

If you add any themes to your ProsePoint installation, please place them underneath sites/all/themes or sites/default/themes.

If you add a theme which is meant to override a theme already included with ProsePoint, please place them underneath sites/default/themes.

Note

Please do not place anything underneath profiles/prosepoint/themes. This directory is overwritten when ProsePoint is upgraded.

9.2. Customising a Drupal theme for ProsePoint

This section suggests areas in which a generic Drupal theme can be further customised for better integration with ProsePoint. None of these are mandatory, they are all optional.

Expanded and new content types
ProsePoint expands upon the default Drupal content types and adds additional ones. When developing a theme for use with ProsePoint, theme designers may choose to implement special themeing for nodes of these types.
Visual editor
ProsePoint uses a visual editor purposely written for ProsePoint. It is advisable for theme designers to include themeing for the editor such that the editor is as close to wysiwyg as possible. Please refer to the default ProsePoint theme (The Morning After, Rev 2) for an example of how this is achieved.
Composite layouts
ProsePoint editions can be configured to display content in multi-column layouts. When developing a theme for use with ProsePoint, theme designers may choose to include themeing for these composite layouts.

Note

Prior to ProsePoint 0.08, a ProsePoint theme would use a local tasks block to replace the Drupal local tasks tabs. That is no longer necessary. From ProsePoint 0.08 onwards, this requirement can be dropped.

9.3. Customising the default theme

It is likely that some users will use ProsePoint with the default theme (as of writing, this is tma2), but with some modifications. Users should not edit files which are part of the default theme. Their changes will be lost when these files are overwritten by future ProsePoint upgrades.

Instead, there are two ways of safely making customisations to the default theme. The first is to make a higher priority copy of the theme and customise the copy. The second is to create a subtheme of the default theme and customise the subtheme.

9.3.1. Customising a copy of the default theme

  • Make a copy of the default theme and place it under sites/default/themes.
  • Visit Administer => Site building => Themes with your web browser.

    Visiting this page will prompt ProsePoint to rescan the file system for themes.

  • Make any desired customisations to this copy of the theme. You should change the version number to distinguish your copy from the original theme.

Themes found under sites/default/themes have a higher priority than those found under profiles/prosepoint/themes. Your copy of the theme (with your customisations) will be used by ProsePoint in preference to the original theme.

9.3.2. Customising a subtheme

Users can create a subtheme which inherits the behaviour of the default theme, and then make their own customisations. This has the following advantages:

  • It is simpler as the developer only needs to implement theme changes - Much can be achieved by just a few CSS declarations.
  • Any improvements to the parent theme in future versions of ProsePoint will also apply to the subtheme.

The subtheme should be placed under sites/all/themes or sites/default/themes.

For detailed information on creating subthemes, please see the Drupal 6 Theme guide and the Zen theme documentation.

9.3.2.1. Example customised subtheme

Instead of creating a subtheme from scratch, developers may prefer to download a sample subtheme and work from there.