System Documentation - SCIPS CMS


Version History
Version Date Notes
1.2 2004-10-27 Additions and amendments as a result of Web Survey extension are denoted by a single border - Example
1.3 2005-12-07 Entire document is revised. Specific additions are annotated with a double border - Example

Contents

  1. Introduction
  2. Requirements Specification
  3. Maintenance
    1. Adding New Content Updated
      1. Challenge Document
      2. Subject Document
      3. Resources Document
      4. Learning Activity Information
      5. Subject and Challenge Document
      6. Case Studies Document
      7. Key Skill Document
      8. Question New
      9. Survey New
      10. Metadata/Properties
    2. Managing Users & Roles
    3. Searching for Members
    4. Back Up Procedures Updated
    5. Database Packing New
    6. Rotation of Log files New
    7. Trouble Shooting New
  4. Common Configuration Changes Updated
  5. Customisation
    1. Portal Properties
    2. Portal Actions
    3. Portal Types
      1. Plone defaults
      2. SCIPSType & Archetypes
      3. SCIPSTypeII New
      4. Other Portal Types
    4. Work Flow
    5. Additional Products/Plugins Updated
    6. Overridden Objects Updated
  6. Known Issues
    1. Disassociating all keywords from a document
  7. Future Improvements
  8. References
    1. Essential Reading
    2. Useful Web Resources
    3. Books
  9. Related Documentation

Introduction 

This document has been produced to complement the development work performed to create the SCIPS content management system (CMS). The SCIPS resource is based upon an open source CMS, Plone, which is built upon on the content management framework (CMF), Zope. Background information regarding the type of software behind this project can be found in the accompanying CMS overview.

Requirements Specification 

The requirements for this resource are detailed in the following documents.

Maintenance 

This section explains how to perform the common CMS maintenance tasks. Please also refer to the Plone and Zope manuals for further information.

Adding New Content 

To add SCIPSType content, such as Subject Documents, you must log into the SCIPS resource, with manager privileges, Log in Page. Please note that only items that have had their state changed to published can be viewed by normal members.

The Subject and Disability Document portal type have not been described individually below, please read through the Subject and Challenge Document type, and other types for a good understanding of how to create this type of document.

Challenge Document 

  1. Navigate to the Challenges folder
  2. Click Add New Item
  3. Select Challenge Document from the drop down list
  4. Now enter the data into the document
    Id
    This represents part of the page's URL. (Optional)
    Title
    This appears at the start of the page content, the title bar of the browser, in bookmarks and can contain spaces.
    Challenge
    Challenge name used to link document with other related document types.
    Resources
    The URL of the Resources Document. Normally this will reside in the resources subfolder. Relative addresses can be used, e.g. resources/organisation_resources.html (Optional)
    Subjects
    A list of one or more subjects associated with this challenge. It is important to be consistent and use the exact subject attribute set in the each of the corresponding Subject Documents. (Optional)
    Characteristics
    This attribute represents the Characteristics section of the document. This can be in plain text or HTML format. (Optional)
    Strategies
    This attribute makes the Strategies section of the document. This can be in plain text or HTML format. (Optional)
    Body
    This attribute makes up the remaining content of the page. This can be in plain text or HTML format. You can either enter text directly or upload the contents from a file on you computer. (Optional)
  5. Click the Save button

Subject Document 

  1. Navigate to the Subjects folder
  2. Click Add New Item
  3. Select Subject Document from the drop down list
  4. Now enter the data into the document
    Id
    This represents part of the page's URL. (Optional)
    Title
    This appears at the start of the page content, the title bar of the browser and can contain spaces.
    Subject
    Subject name used to link document with other related document types and appears in the Browse page Subject drop down list.
    Challenges
    A list of one or more challenges associated with this subject. It is important to be consistent and use the challenge attribute set in the each of the corresponding Challenge Documents. (Optional)
    Benchmark
    This should be a URL to an external resource, where the benchmark statement for this subject is. Please ensure the full address it used. For example; http://www.example.ac.uk/math/benchmark.html (Optional)
    Learning Activity Groups
    A list of one or more Learning Activity group names. It is important to be consistent when creating Learning Activity Information items and use the same wording for the group names. (Optional)
    Resources
    The URL of the Resources Document. Normally this will reside in the resources subfolder. Relative addresses can be used, e.g. resources/computing_resources.html (Optional)
    Body
    This attribute makes up main content of the page, and appears before the Learning Activities against Challenges matrices. This can be in plain text or HTML format. You can either enter text directly or upload the contents from a file on you computer.
  5. Click the Save button

Resources Document 

This page represents a record of URLs to resources available for the associated Disability, Challenge or Subject. This is a freely formatted document.

  1. Navigate to the resources folder, a subfolder of the Subjects, Challenges or Disabilities folder
  2. Click Add New Item
  3. Select Document from the drop down list
  4. Now enter the data
    Short Name
    This represents part of the page's URL, e.g. computing_resources.html. (Optional)
    Title
    This appears at the start of the page content, the title bar of the browser and can contain spaces. For example, Computing Related Resources
    Description
    This summary appears directly before the body of a page. (Optional)
    Body text
    This attribute makes up main content of the page. You can select the format of the body - plain text, structured text or HTML format. You can either enter text directly or upload the contents from a file on you computer.
  5. Click the Save button

Learning Activity Information 

Each Learning Activity Information item represents an 'X' link on a Subject's Challenge and Learning Activity matrix. When the link is selected the body appears in the resulting pop up window. Please be aware that when there is learning activity information relating to several challenges, this will require multiple 'Learning Activity Information' items with the same title.

  1. Navigate to Learning Activity Information folder, a subfolder of the Subject folders
  2. Select the relevant subject folder
  3. Click Add New Item
  4. Select Learning Activity Information from the drop down list
  5. Enter data
    Id
    This represents part of the page's URL. (Optional)
    Title
    The actual Learning Activity name (row name in matrix)
    Learning Activity Group
    Enter the exact group name that this Learning Activity Information belongs to
    Subject
    Enter the Study Subject that this information relates to
    Challenge
    Enter associated Challenge name (column name in Challenge and Learning Activity matrix)
    Body
    Explanation of the Learning Activity. This can be in plain text or HTML format. You can either enter text directly or upload the contents from a file on you computer.
  6. Click the Save button

Subject and Challenge Document 

  1. Navigate to the Subjects and Challenges folder
  2. Click Add New Item
  3. Select Subject and Challenge Document from the drop down list
  4. Enter content
    Id
    This represents part of the page's URL. (Optional)
    Title
    This appears at the start of the page content, the title bar of the browser and can contain spaces.
    Subject
    Study subject name used when linking item to associated Challenge Document
    Challenge
    Challenge name, as used in the associated Challenge Document
    Case Studies
    The URL of the Case Studies Document. Normally this will reside in the casestudies subfolder. Relative addresses can be used, e.g. casestudies/computing_anxiety_case_studies.html (Optional)
    Body
    This attribute makes up main content of the page. This can be in plain text or HTML format. You can either enter text directly or upload the contents from a file on you computer.
  5. Click the Save button

Case Studies Document 

This free form document relates to a specific Subject and Challenge document and should have its location set in the associated item's Case Studies URL field.

  1. Navigate to the casestudies folder, a subfolder of the Subjects and Challenges folder
  2. Click Add New Item
  3. Select Pop Up Document from the drop down list
  4. Now enter the data
    Short Name
    This represents part of the page's URL, e.g. computing_anxiety_case_studies.html. (Optional)
    Title
    This appears at the start of the page content, the title bar of the browser and can contain spaces.
    Description
    This summary appears directly before the main content of the case studies page. (Optional)
    Body text
    This attribute makes up main content of the page. You can select the format of the body - plain text, structured text or HTML format. You can either enter text directly or upload the contents from a file on you computer.
  5. Click the Save button

Key Skill Document 

  1. Navigate to the Key Skills folder
  2. Click Add New Item
  3. Select Key Skill Document from the drop down list
  4. Enter content
    Id
    This represents part of the page's URL. (Optional)
    Title
    This appears at the start of the page content, the title bar of the browser and can contain spaces.
    Key Skill
    Succinct name used to populate the Browse page's Key Skill drop down list.
    Group
    Name used to group the key skills in the Browse page select box. Ensure consistent naming of the same group.
    Sample of Browse page select box - Excerpt of Key Skills drop down
    Resources
    The URL of the Resources Document. Normally this will reside in the resources subfolder. Relative addresses can be used, e.g. resources/concentration_resources.html (Optional)
    Challenges
    A list of one or more challenges associated with this key skill. It is important to be consistent and use the challenge attribute set in the each of the corresponding Challenge Document. (Optional)
    Body
    This attribute makes up main content of the page. This can be in plain text or HTML format. You can either enter text directly or upload the contents from a file on you computer.
  5. Click the Save button

Question 

  1. Navigate to the Feedback folder
  2. Click Add New Item
  3. Select Question from the drop down list
  4. Enter content
    Id
    This represents the last part of the individual Question's URL. (Optional)
    Title
    Within the individual Question view, the title appears at the start of the page content, the title bar of the browser and can contain spaces. When the Question is viewed as part of a Survey, the title appears as a introductory header to each Question.
    Multiple Choice Question
    Enter the question text here. Only used when a multiple-choice question is needed. (Optional)
    Multiple Responses Allowed
    Check this box if you want to allow users to select more than one answer to a multiple choise question.
    Multiple Choice Answers
    Enter a list of possible responses, each on a new line. Only required when using a multiple-choice question. (Optional)
    Open Feedback Question
    Where a free text response is required, enter the question here. This question can be used in conjunction with a multiple-choice question or separately. (Optional)
  5. Click the Save button

Survey 

  1. Navigate to the Feedback folder
  2. Click Add New Item
  3. Select Survey from the drop down list
  4. Enter content
    Id
    This represents part of the Survey's URL. (Optional)
    Title
    This appears at the start of the Survey page, the title bar of the browser and can contain spaces.
    Introduction
    This section is shown before the questions on the survey
    End Statement
    Enter a message to be shown after a user has completed the survey.
    Questions
    Questions that exist within the same folder as the survey will populate this select box. Only Questions that have been explicitly selected will appear in the survey. (Optional)
  5. Click the Save button
Referencing Additional Questions

As well as the above mentioned method of associating Questions with a survey, it is possible to reference Questions that are not stored in the same folder as a Survey.

  1. Navigate to the Question(s) required
  2. Copy the item(s)
  3. Navigate to the Survey
  4. Click on the References tab
  5. Paste the Question items

Metadata / Properties  

Every document type can have additional metadata associated with it. This data can be used to improve categorising and searching of your data. Visit the Dublin Core - Metadata website for more information.

  1. Navigate to object you wish to change
  2. Click the Properties tab
  3. Enter metadata
    Allow Discussion on this item / Allow Discussion?
    When activated, you can attach threaded discussions to the object. If you allow discussion, there will be a 'Add Comment' button that appears at the bottom of the content.
    Keywords
    A list of all existing keywords is available for selection and new subjects can also be added. NB: When no documents refer to a specific keyword it will be removed from the list of existing keywords. See PloneKeywordManger product for more information about keyword maintenance.
    Effective Date
    Date from which this object can become visible, given that it is published.
    Expiration Date
    A mechanism to limit the amount of time an object is available
    Format
    Change the MIME type of document. Not recommended. (Not available from SCIPSTypes, e.g. Subject Documents)
    Language
    Select the language the item is written in
    Description
    This summary appears directly before the body of a page. (Found on the edit tab for some portal types)
    Copyrights
    Copyright information, entry will appear at the footer of the item, above the author's name.
    Contributors
    Where the item has been produced in collaboration, list all author names here.
  4. Click the Save button

Managing Users & Roles 

The following user maintenance functions can be using performed from within the Plone or Zope Management Interface.

User Configuration - via the Plone interface

User Configuration - through the ZMI

Searching for Members 

You can search for users by the following parameters;

Location of Member Search - via the Plone interface

Back Up Procedures 

The frequency of backup of your database is dependant upon the frequency in which it changes. See the Zope and or Plone manual for more information relating to backing up the database.

To create a Windows specific backup of Zope instance including your SCIPS Plone website you should make a copy of your Data.fs file. Normally found in the C:\Plone 2\Data\var folder of the web server. However, to create a remote backup that is platform independent exporting the Plone object is recommended.

Please note that in windows based installations the Plone service must be stopped to back up the entire database, Data.fs. The service can be stopped from the Services window of the web server Start > Administrative Tools > Services . Please ensure your restart the service once you are finished.

Exporting your SCIPS web site 

Objects within Zope can be exported and imported. This is especially handy if you wish to duplicate your site for testing purposes or for general backup purposes. From the ZMI objects can easily be exported to another Zope server. Please note to import objects the zexp file must be first placed in the import folder of the Plone instance, usually found C:\Plone 2\Data\import on a standard installation of Plone on Windows.

  1. Log into the Zope Management Interface, ZMI http://scips.worc.ac.uk:8080/manage
  2. Select check box next to Plone the folder contents
  3. Click Import/Export
  4. Choose between downloading the file onto your PC - Download to local machine or the web server's PC - Save to file on server.
  5. This will allow you to export the entire SCIPS database, including member information.

Database Packing 

The Plone CMS contains a history of all changes made to the database. This excellent facility allows you to undo any erroneous changes. However, it is suggested that you pack/trim the historical database periodically. It is suggested that at least once a month you pack the database to the last 30 days worth of history, to avoid ultimately running out of space on your server. This section can be found in the Zope Management Interface;

You should decide on the frequency of your database packing, and the length of history you wish to keep. For example, pack once a week and keep 30 days worth of history.

Rotation of Log files 

Log files, i.e. event.log and Z2.log, found in the C:\Plone 2\Data\log folder, should be periodically rotated/renewed in order to maintain a reasonable file size. If no automatic method is employed to rotate your log files you can safely delete the event.log file and restart the Zope server, from the ZMI - /Control_Panel. The server will automatically recreate a fresh log file. Whether or not you save your old log files is dependant upon your own requirements.

Trouble Shooting

If you receive an out of memory error:

  1. Restart your Zope server
  2. Pack your Zope Database, ZODB, regularly, at least once a week.
  3. Restart your Zope server, again if necessary.
  4. If problems persist, you may need to reduce the size of your log files

Common Configuration Changes 


Mail Host

This setting must be updated to refer to the SMTP mail server. The default setting is SMTP Host: localhost and port: 25.

Mail Host Configuration - via the Plone interface

Mail Host Configuration - through the ZMI

Without a valid mail host 'password reminders' and 'Send this page to somebody' links will not function. Resulting in an error message being shown.

Member folder creation

This feature controls whether new users registering with the resource for the first time, will automatically have their own member folder created upon first login or not.

The setting should look like the example below;

 

Member Folder Configuration - through the ZMI

Portal Properties

Site wide portal properties can be configured from here. Such as;

Portal Properties Configuration - via the Plone interface

Portal Properties Configuration - through the ZMI

How to update the main navigation 

All the information regarding the main navigational links, for example Home, Contact, Help, etc. can be found in the following templates, within the /Plone/portal_skins/custom folder

header
Left vertical icon-style navigation bar
footer
The bottom row of plain navigational link

If any changes to the main navigation is required, e.g. a new location, ensure that changes are made to both template files and to all references of the changed item.

Customisation  

Plone is a ready to use multi-functional CMS. To fulfil the specific requirements of the SCIPS project several steps were taken to tailor the default Plone portal. The main configuration changes are detailed below.

Portal Properties 

On the properties tab of the /Plone object in the ZMI you can specify which slots appear in the portal. Slots are self-contained items that appear on the left or right of the main page content. For example the Quick Links area and the Log in box are slots.

Current Slots

Log in Box
here/portlet_login/macros/portlet
Visible if user is not logged in
Review
here/portlet_review/macros/portlet
Visible if user has a Reviewer role and there is pending content, awaiting approval
Quick Links
here/portlet_quick_links/macros/portlet
A custom collection of navigational links
Favourites
here/portlet_favorites/macros/portlet
Visible if user has a personal folder and has added one or more documents to favourites

Available Slot Items

The following slots can be activated within your Plone portal by adding references to either the left or the right slot.

Navigation
here/portlet_navigation/macros/portlet
A folder content tree, similar to a List View in Windows Explorer
Related
here/portlet_related/macros/portlet
News
here/portlet_news/macros/portlet
Listing of recent news items
Events
here/portlet_events/macros/portlet
Listing of up and coming events
Recent
here/portlet_recent/macros/portlet
A listing of recently modified/published items
Calendar
here/portlet_calendar/macros/portlet
Calendar of past and future events

Portal Actions 

Portal Actions define the conditions and functionality available through tabs and buttons for the given scope. For example actions can be defined for portal, folder or object level scope. The items that appear in the Personal Link bar, are governed by Portal Membership Actions.

Location of Action Settings within the ZMI.

Action Categories

Portal Types 

Plone defaults 

Plone provides a number of built in content types, ready for use;

See the Plone manual for more information regarding these content types.

Archetypes & SCIPSType 

Archetypes is a framework for constructing new content types in Plone, using the Python programming language. It provides a bootstrapping mechanism to ease the creation of fully customised content types.

SCIPSType and SCIPSTypeII are both based upon Archetype and form a Zope product that consists of Python content type definitions and Zope Page Templates with accompanying Python scripts. The resulting portal types are listed below;

SCIPSTypeII 

This product extends the customised portal types available for the SCIPS project.

View the list of custom portal types' attributes Updated.

Other Portal Types 

The following portal types were based on the Plone Document portal type. They were created to either alter the default view template used to display the document. In some cases derivative types were also created to dictate which documents were shown to non-members.

Work Flow 

An additional workflow was created to govern the SCIPS portal. The new workflow, scips_workflow, ensures that only a few specific content types are visible by anonymous users and that members can only view them when they are published.

The following custom portal types use the default workflow and are visible by anonymous users.

Additional Products/Plugins  

The following third party Zope Products where installed in addition to the default Zope products bundled with the Plone 2.0.3 installer.

Overridden Objects 

Several built-in templates and scripts were modified to achieve the desired result. All of the customised files can be found in the /Plone/portal_skins/custom folder within the ZMI, with the exception of getNotAddableTypes which is also required in every subfolder.

Please note for purposes of migration to newer versions of Plone or other Zope products, the following built-in objects were overridden and should be checked for compatibility upon upgrades.

Plone Core

Third Party Product Overrides

Archetypes
PloneSiteMap

All additional, newly created files, such as images and scripts can also be found in the /Plone/portal_skins/custom folder.

How to customise a page template Updated

Further modifications can be made to any of the page templates, (cascading style sheets, images or scripts) used in the SCIPS.

  1. Find the object you wish to customise - use the ZMI search
    • Select the Find tab from the /Plone object
  2. If the item is found in not found in the /Plone/portal_skins/custom
    • Select item
    • Click the button on the Customise tab of the item to be changed
  3. Edit your item

More information regarding custom page templates can be found in the Page Template Description document.

Subject and Challenge Document
challenge_and_subject_view
Challenge Document
challenge_view
Subject and Disability Document
disability_and_subject_view
Disability Document
disability_view
Key Skill
key_skill_view
Learning Activity Information
learning_information_view
Subject Document
subject_view
learning_information_view

Additional template views created for SCIPSTypeII can initially be found within the ZMI folder /Plone/portal_skins/scipstypeii.

Question
question_view
question_result_view
Survey
survey_view
survey_result_view

Known Issues 

Disassociating all keywords from a document 

If all keywords are deselected and no new keywords are associated with a document, after saving the changes the previous keywords will be again selected. Hence it is impossible to deselect all keywords from an object once keywords have been associated with it. See the official Plone bug list to check on the progress of this issue.

Future Improvements 

Extend Help Section

Create additional sections within the user tutorial for the following topics;

Add More Explanatory Text

Advanced Search
When not logged in, display within the search form and search results
You will not be able to search for content, whilst you are not logged in
Site Map
When not logged in, display within the site map
You will not be able to view the full site map, whilst you are not logged in

Caching Policy

Ensure that the current caching policy is effective for the subset of files it is associated with. See /Plone/HTTPCache in the ZMI.

Pop Up Documents

Open pop up type documents and Learning Activity information items, launched from the site map and search results, in a new window. Related files /Plone/portal_skins/custom/sitemap and /Plone/portal_skins/custom/search, respectively, are accessible through the ZMI.

User Selected Style sheets

To better suit a wide range of users the ability to re-skin the site, with a selection of style sheets should be offered. Further customised style sheets need to be created/installed.

Upgrade Plone & Zope

As upgrades become available it is advisable to assess the benefits of upgrading the Plone installation. Where factors such as improved security, performance and new features should be taken into account. At the time of writing SCIPS was based on Plone version 2.0.3.

References 

Essential Reading 

Local copies of the online books accompany this documentation, in PDF format.

Useful Web Resources 

There are many external web resources available to aid Plone and Zope customisation.

Books 

There are several books available for the CMF, Zope, which are useful for advanced customisation of your Zope instance. Recommended reading, as an additional resource for managing your Plone site are;
The Definitive Guide to Plone, ISBN: 1590593294 Online Version

Plone Live!, ISBN: 0976553406 Online Version

See the Plone website for an up to date list of available books.

Related Documents 

System Documentation, version 1.3.1