Try It Yourself

Purpose

This how-to provides a sample course zip file and basic instructions to allow users to experiment with content creation within eduCommons.

Prerequisities

This how-to assumes some familiarity with basic content management systems. For a more detailed set of instructions, please see eduCommons: A Guide to Getting Started.

Import a Basic HTML Course

See how well you understand eduCommons by building a test course inside your own installation of eduCommons.

    1. Download this zip file to your desktop
    2. Login to your installation of eduCommons
    3. Create a Department
    4. Create a Course called “Test1”
    5. Import zip file content from your desktop
    6. Design the Course
    7. Move it through the workflow… don’t forget to move the Department through as well.
    8. Publish the course and log out

If you were successful, you should be able to view the course without logging in.

Build Your Own Course

    1. Assemble course materials on your desktop. Use relative links to link pages together and eduCommons will automatically rewrite all the links.
    2. Login to your installation of eduCommons
    3. Create a Department
    4. Create a Course
    5. Import the course from your desktop
    6. Design the Course
    7. Monkey around with the content until it displays how you like
    8. Move materials through the workflow
    9. Publish the course and log out of the system.

If you were successful, you should be able to view the course without logging in.

Skinning eduCommons

Left Skin Documentation

Overview

First of all it may help to begin by going over some general strategies to skinning a website. The main strategy when you skin a site is to balance the amount of image and UI information that needs to be downloaded with making your site appear appealing. If you have large images with a huge file size, your site will appear to be sluggish to end users, especially those with poor connectivity to the Internet. If you have no images or styling, your site will load very fast, but may not be very appealing to end users. When you design a look and feel for a web site both of these aspects must be considered. Although Left Skin gives you control over many of these aspects, it leaves the responsibility of choosing the correct balance to you.

Left Skin allows you to set colors in many parts of the page. When setting the colors you can use the default web standard names like “white” or “pink” etc. You can also use a hex coded RGB value. If you are using a hex value it must be preceded by a “#”. For example if you wanted pure red you would enter “#FF0000” in the color field. If you want to experiment more with colors, use the popup color control provided by left skin to set colors, shades, hues, etc.

In many areas you can experiment with background images that you may want to appear in various places in the site. Use the form controls that Left Skin provides to upload these images to various areas. If however you decide that you do not want an image to appear in a background after all, a trick you can use to reset a section back to its default setting is to create a 1×1 pixel %100 transparent gif and upload it as an image. This will allow the solid background color to appear, and the image will be out of the way.

The Control Panel

The Left Skin control panel is where you make the majority of changes to the look and feel of your website. It can be navigated to by clicking on the “Site Setup” link found at the top right of your page. Note that you must be logged in as a manager in order to see the link. Once you are into the general control panels page look for the section titled “Add on product configuration.” In this section you should see two entries titled “Left Skin CSS settings” and “CSS Settings.” Click on the “Left Skin CSS Settings” to get to the main Left Skin control panel.

Once you are into the main control panel you will notice that you are now given a form with a bunch of settings. This form is prefaced with a number of tabs across the top. Each of these tabs control a portion of the page that is displayed. Refer to the following sections for detailed instructions on the settings and how they work.

Before we launch into explaining all the settings in the control panel and how to use them, I figured it would be good to mention that there is a way to reset any changes you make back to the default settings. This gives you an extra safety net when you are making changes to the theme, and gives you a way of getting back to a known working setting if you have gone too far. To reset the skin to the default look that comes with Left Skin, simply click on the “Reset to Default” button at the bottom of the form.

General Tab

The general tab controls settings that are not necessarily specific to certain areas. These are mostly miscellaneous settings that do not fit in the other categories. Some of them are vital to how you will interact with Left Skin, so it is important to understand the settings found here.

Development Mode

Development mode is the name given to the mode you will need to be in when you are making any changes to Left Skin. First a little background on what is going on behind the scenes in your Plone site. Plone manages all the many CSS and javascript files associated with your site by compiling them together into one big CSS file that it then compresses and caches very agressively. This is primarily to increase the performance of your site. When you make changes to Left Skin, often many of the settings will not take effect when your site is in production mode. This is because the CSS files that the settings control have already been cached throughout your system all the way to the browser.

In order to see your changes immediately, you need to temporarily take Plone out of production mode, which will then treat all the CSS files individually, and will not send caching headers with them, so that the browser and any corresponding servers that may sit in front of your Plone site will not cache the pages. You can get into this mode by selecting “Development Mode” and then “Save” at the bottom of the page. Be aware, you will want to exit development mode as soon as you are through making changes, as it will cause quite a large performance hit on your site while in this model.

The portal logo setting allows you to upload a new logo that will appear in the top left of the site. It will replace the default logo that currently appears there (titled “Left Skin Put your logo here”). Note that even in development mode sometimes the portal logo image will still be cached. When you upload your new graphic, if you do not see it immediately, then simply browse to the home page of your Plone site and do a full reload on the page. In most browsers this can be done simply by holding down the shift key and clicking on the reload icon in the browser header.

Portal Favicon

The portal favicon is the little icon that appears next to the URL listing in the browser header. This little icon is cached even more heavily than the portal logo, and can be a little tricky to get it to appear once you have uploaded it. Again like the portal logo, being in development mode does not help much here. The best strategy for this one is to completely clear your browser cache once you have uploaded the icon. You can normally do this through the preferences or options setting in your browser.

Fluid Fixed Width

The next four settings allow you to control both the width of your website and how the text flows in your pages. If you do not have “Fluid Fixed Width” set, your site will dynamically resize to the full width of the browser window. This is normal default behavior for a Plone site. If “Fluid Fixed Width” is set, a fixed width is applied to your site. Regardless of how you resize your browser window, the text layouts will remain the same. If you resize too small scroll bars will appear in the browser to allow you to continue to navigate. If you size your browser bigger than the fixed width of the site, a background will appear in the area that is not within your site.Both of these site layout strategies have strengths and weaknesses. Left Skin allows you to choose between either of these strategies.

The next three settings allow you to control the look and feel of the background created when “Fixed Fluid Width” is selected. Note that these settings do not do anything if you do not have “Fixed Fluid Width” set. The first setting allows you to repeat vertically any image you may have uploaded to appear on the background. This is useful if you are trying to create a pattern to appear in the background area. It is also a good idea if you want styling on your background, but do not want to increase the bandwidth needed to download a page by using a larger image on the background.

The “Body Background Color” allows you to set the color of the background. If you want the background to appear as a plain solid color, you can set it here. Alternatively you can upload an image to appear on the background instead using the “Body Background Image” field. Note that you can use both these settings in conjunction if your background image is using alpha channels or transparency. Also if you want to remove a background image, use the “Reset to Defaults” option to set the entire site back to default Left Skin settings, or use the 1×1 transparent gif strategy explained above.

Header Tab

The header tab controls how the top banner section of your website appears. It includes any banner images you would like to go across the top of the site, as well as colors of fonts and links that may appear in the header section. The first option in the Header tab is to upload a portal banner. This will appear on the background of the full header section, so make sure any images you may want to upload here work with the portal logo and other controls that appear in the top of the site. In the description area of the portal banner field, suggestions are given as to what the size of the uploaded banner should be. Also if you are not using a “Fluid Fixed Width” strategy you will want to take into account what will happen if a user opens a browser wider than your banner. You may want to use some sort of fading in conjunction with the header background color to make sure that it will work.

The rest of the controls in the header tab control the colors of text that appear in the header. Use the Font Color, Link Color and Active Link Color to control how text will appear in the header. At this point I should also mention that the footer of the site is set to automatically pick up the same colors that are set for the header. This is done to maintain some consistency between the header and footer, and to cue the user as to where the UI ends and the content begins. Some designs may require that your footer, or text contained in the footer be a different color. If this is the case for you, then you can use the top background image field to create a different background to the footer in the header. Note that this is also a good strategy if you are using a banner for the header. Just pick a background color that matches your portal banner, and the footer will then blend well with the header, and still give the necessary cue to the user where the content will be.

Top Nav Bar

The “Top Nav Bar” is similar to the Header tab, except it controls the section just under the header. Typically this is the main horizontal navigation area provided by your site. You may want to simply leave the background color solid, or provide a subtle effect by uploading a background image. If you do upload a background image, do note that it will repeat on the horizontal axis. This is to facilitate subtle shading effects which you may want to appear in the background, and to give you a strategy to be able to keep the size of your images down.

In this section you can use the “Active Link Color” setting to give a hover effect over links that are moused over. Simply make the link lighter or darker than the Link Color, and when a user mouses over the link it will change slightly and cue the user that what is being moused over is an active option they can select.

There is a more subtle effect that occurs with the background color assigned to the top nav bar. Highlights, which include thin lines, hrules, etc. will use the same color as the background of the top nav bar. This is to help break up the content area colors and blend them better with the rest of the site. If for some reason you need to have these highlighted colors in the content area separate from the background of the top nav bar, then use a background image for the top nav bar, and then set the color you want the content highlights to be as the top nav background color.

Left Nav

This section controls the left hand column of the page. It is similar in functionality to the top nav bar, with the same basic settings. Differences in functionality between the top nav bar are that the background will repeat on the vertical axis instead of the horizontal one. Typically most designs will not require a background image here, but it is included anyway just in case.

A larger consideration you will want to make when stying this area of the page is how pronounced you want the left hand navigation to be. If your site requires a strong navigational presence in the left hand column, you may want to chose a darker background with lighter text to complment the neighboring content area. If you require a minimal presence or want to minimize the boldness of the left hand content it is better to choose a lighter color scheme with darker text. It may be worth starting here to experiment and then build the rest of the sections around whatever scheme you decide to go with.

Content

The content area is the main focus of the page, and colors for it can be controlled under the “Content” tab. Typically unless your design calls for something completely different, you will probably only tweak things slightly here. Examples of things you may want to do are making the text color not fully black, change the colors of links in the page, etc. You may want to change slightly the background color to a little less white. More drastic changes here require careful thought and planning to make sure the rest of the areas will work together with them.

CSS Helper Control Panel

Left skin also has a separate control panel which exposes many of the settings controled by Plone at lower levels. It is basically a grouping of settings that get plugged into the CSS files. Left Skin exposes this control panel to allow you to make further changes to some aspects of the UI that are not integrated into the main Left Skin control panel. If you can not gain access to the settings you would like either through the main left skin control panel, or via the CSS Helper control panel, then it is time to start looking into the more traditio

Old Migration Instructions

Purpose

This how-to is meant to help systems administrators who need to upgrade eduCommons from an earlier version and preserve existing content.

Prerequisities

This how-to requires a high level of technical expertise. We recommend attempting the migrations on a staging server first if possible. You will need to identify your current version (2.3.1-final or 3.0.2-final), start at that point in the instructions, and migrate step-by-step through each subsequent migration until you are up to the latest version. If you are starting with a version prior to 2.3.1-final, you will first need to migrate to 2.3.1 final before following these steps. Earlier migrations instructions are available in the the source code repository (http://educommons.com/dev/browser/old/eduCommons/tags).

Migrating from eduCommons 2.3.1-final to 3.0.2-final

Preparation

A few things you should do before beginning the migration:

  1. VERY IMPORTANT: SAVE A BACKUP OF YOUR Data.fs FILE, which is located in the [old instance home]/var directory of your eduCommons site. This file contains all of the content for your site. (This way you will able to restore your file from this Data.fs file if anything goes wrong.)
  2. Using the Zope Management Interface (ZMI), export any customizations you have made in your [old site] –> portal_skins –> custom folder and then delete all files in the custom folder. You can re-import these customizations once you have migrated the site.
  3. Verify that your current instance is eduCommons-2.3.1-final.

Migration Steps

The migration eduCommons from version 2.3.1-final to version 3.1.1-final includes the following:

  1. Pre-migration of Data.fs in version 2.3.1-final
  2. Movement of Data.fs file to a new 3.0.2 instance
  3. Migration of Plone 3.0.4
  4. Migration of the eduCommons 3.1.1-final instance
  5. Final steps

1. Pre-migration of Data.fs in version 2.3.1-final

For this step, you will need to copy the migration source code found in version 3.1.1-final. The file is located at eduCommons/extras/PreMigrate.py . Copy this into [old instance]/Products/eduCommons/Extensions.

Run the migration script by following these steps:

  1. Open your 2.3.1-final eduCommons site in the ZMI. (click educommons Setup, then click Zope Management Interface.)
  2. From the drop down menu, select “External method” and click the Add button.
  3. Enter the following parameters:
    • Id: Pre_Migrate_eduCommons3.0.2
    • Title: Pre_Migrate_eduCommons3.0.2
    • Module Name: eduCommons.Migrate
    • Function Name: pre_migrate_2_3_1_to_3_0_2
  4. Click Add
  5. Click on the Pre_Migrate_eduCommons3.0.2 script you just added
  6. Click the test tab.
  7. Verify that the method ran successfully. (It should give you feedback.)

2. Movement of Data.fs file to a new 3.0.2 instance

For the next step you will move the Data.fs file from the old instance to the new instance. First of all, install an eduCommons-3.0.2 instance using the installations instructions found in [new instance home]/eduCommons/docs/. Stop both sites. Then copy the Data.fs file from the var directory of the old site to the var directory of the new site:

sudo cp -rvfp [old instance home]/var/Data.fs [new instance home]/var/

3. Migration of Plone

The following steps need to be performed in the ZMI, as eduCommons-3.1.1-final utlizes Plone 3.0.4, instead of 2.5.x:

  1. Open your 3.0.2 eduCommons site in the ZMI. (click educommons setup, then click Zope Management Interface.)
  1. Run portal_migration migration (click the upgrade button on the migrate tab)

4. Migration of the eduCommons 3.0.2 instance

Run the migration script included with the 3.1.1-final instance by following these steps:

  1. Copy the migration script found in Products/eduCommons/extras/Migrate.py to [new_instance]/Extensions/
  2. Open your 3.1.1-final eduCommons site in the ZMI. (click educommons Setup, then click Zope Management Interface.)
  3. Navigate to the root of the ZMI (click the Root Folder link located in the upper left portion of the page)
  4. From the drop down menu, select “External method” and click the Add button.
  5. Enter the following parameters:
    • Id: Migrate_eduCommons3.0.2
    • Title: Migrate_eduCommons2.0.2
    • Module Name: Migrate
    • Function Name: migrate_2_3_1_to_3_0_2
  1. Click Add
  2. Click on the Migrate_eduCommons3.0.2 script you just added
  3. Click the test tab.
  4. Verify that the method ran successfully. (It should give you feedback.)

5. Final Steps

Your site should now be migrated. Navigate to your site in the browser and ensure it has migrated. Based on the nature of the changes from Plone 2.5.x to Plone 3.0.4, if you performed major customizations, you may or may not need to refactor those changes to work properly in a Plone 3 environment.

Here are some additional steps you may need to follow after migration, depending on how you have customized your site:

  1. Check Course Homepage and About the Professor pages to see if the images render. In past versions of eduCommons, some of these image links may be broken, but rendered due to acquisition. The course folder appears twice in the link (i.e. department/course/course/page).
  2. The Site homepage links to the Courses List, Frequently Asked Questions, and Help will need to be modified as follows:
    • OLD: <a title=”List of Courses” href=”/Courses_listing/”>list of courses</a>.
    • NEW: <a title=”List of Courses” href=”/courselist/”>list of courses</a>.
    • OLD: <a title=”Frequently Asked Questions” href=”/Help/”>Frequently Asked Questions</a>
    • NEW: <a title=”Frequently Asked Questions” href=”/help/”>Frequently Asked Questions</a>
    • OLD: <a title=”Feedback” href=”/Feedback/”>feedback</a>
    • NEW: <a title=”Feedback” href=”/feedback/”>feedback</a>
  3. The Site’s About page links to the Terms of Use and Privacy Policy will need to be modified as follows:
    • OLD: <a title=”Terms of Use” href=”../About/terms_of_use”>Terms of Use</a>
    • NEW: <a title=”Terms of Use” href=”../about/terms_of_use”>Terms of Use</a>
    • OLD: <a title=”Privacy Policy” href=”../About/privacy_policy”>Privacy Policy</a>
    • NEW: <a title=”Privacy Policy” href=”../about/privacy_policy”>Privacy Policy</a>
  4. The top banner, portal logo, and top nav color setting can be checked and adjusted by managers and administrators via Site Setup –> Left Skin Settings. Any changes made to these settings must be done after having checked the Development Mode box. In order to change the background color in the top nav color, a 1px x 1px transparent gif needs to be loaded first to hide the top nav background image. Be sure to uncheck the Development Mode box after Left Skin changes have been saved to improve site performance.
  5. In order to restore the “Join” link, login to the site as manager and click Site Setup –> Security. Then check the “Enable self-registration” box and click save.

Migrate between eduCommons versions

Older migration instructions available here.

Migrating to eduCommons 3.2.1-final

Preparation

A few things you should do before beginning the migration:

  1. VERY IMPORTANT: SAVE A BACKUP OF YOUR Data.fs FILE, which is located in the [old instance home]/var directory of your eduCommons site. This file contains all of the content for your site. (This way you will able to restore your file from this Data.fs file if anything goes wrong.)
  2. Verify that your current instance is eduCommons-3.1.1-final.

Migration of eduCommons 3.1.1-final to 3.2.1-final

The migration eduCommons from version 3.1.1-final to version 3.2.1-final includes the following:

  1. Pre-migration of Data.fs in version 3.1.1-final
  2. Movement of Data.fs file to a new 3.2.1-final instance
  3. Migration to the eduCommons 3.2.1-final instance
  4. Delete Old site and rename new site
  5. Repackage Course Downloads
  6. Final steps

Pre-migration of Data.fs in version 3.1.1-final

For this step, you will need:

  • contentmigration Plone Add-on Product, available at http://pypi.python.org/packages/source/P/Products.contentmigration/Products.contentmigration-1.1.zip
  • to copy the migration source code found in version 3.2.1-1.
  • IMPORTANT UPDATE: The pre-migration script has been updated, and can be found here: https://educommons.com/svn/eduCommons32/enpraxis.educommons/trunk/enpraxis/educommons/extras/PreMigrate.py
    • Copy this into [old instance]/Products/eduCommons/Extensions

IMPORTANT UPDATE: In your 3.1.1-1 final instance a python library needs to be updated:

  • Library Location: /instancehome/lib/python/
  • Library Name: plone.app.linkintegrity
  • Old Version :: 1.0.5
  • New Version :: 1.1
  • Download here: http://pypi.python.org/packages/source/p/plone.app.linkintegrity/plone.app.linkintegrity-1.1.zip#md5=7bb10d39fc422b3e6f22b7706532fe57

Add contentmigration product by following these steps:

  1. Download the product from the aforementioned URL (http://pypi.python.org/packages/source/P/Products.contentmigration/Products.contentmigration-1.1.zip)
  2. Unzip the product. Products.contentmigration needs to be placed in the Products directory of your 3.1.1 instance. For example: /opt/Zope-2.10.6/edu311/Products
    In addition, since it is currently only available as an egg, you will have to extract only the contentmigration directory into the aforementioned products dir.
    When you unzip the package from http://pypi.python.org/packages/source/P/Products.contentmigration/Products.contentmigration-1.1.zip, it will look like a typical python egg:
    Products.contentmigration-1.1
    –Products
    —-contentmigration
    That is the actual ‘Zope2 Product’ that needs to be moved into your 3.1.1 Products directory.
  3. Restart zope

Run the migration script by following these steps:

  1. Open your 3.1.1-final eduCommons site in the ZMI. (click educommons Setup, then click Zope Management Interface.)
  2. From the drop down menu, select “External method” and click the Add button.
  3. Enter the following parameters:
    • Id: PreMigrate
    • Title: PreMigrate
    • Module Name: PreMigrate
    • Function Name: pre_migrate_3_1_1_to_3_2_1
  4. Click Add
  5. Click on the PreMigrate script you just added
  6. Click the test tab.
  7. Verify that the method ran successfully. (It should give you feedback.)
  8. IMPORTANT UPDATE: If you receive the following error during PreMigration related to a LanguageIndex, you need to update [old instance home]Products/LinguaPlone/LanguageIndex.py. You can download the latest from here: http://svn.plone.org/svn/plone/Products.LinguaPlone/trunk/Products/LinguaPlone/LanguageIndex.py

Movement of Data.fs file to a new 3.2.1-final instance

For this step, you will move the Data.fs file from the old instance to the new instance. First of all, install an eduCommons-3.2.1-1-final instance using the installations instructions found in [new instance home]/eduCommons/docs/. Stop both sites. Then copy the Data.fs file from the var directory of the old site to the var/filestorage directory of the new site:

sudo cp -rvfp [old instance home]/var/Data.fs [new instance home]/var/filestorage

Migration to eduCommons 3.2.1-final instance

eduCommons 3.2.1-final uses the portal_setup tool to perform the necessary upgrade from 3.1.1 to 3.2.1-final. Due to the fact that eduCommons and it’s dependencies were moved to python eggs, we must start with a new eduCommons site. The migration script will then copy and past content and relevant settings to the new installation:

  1. IMPORTANT UPDATE: The pre-migration script has been updated, and can be found here: https://educommons.com/svn/eduCommons32/enpraxis.educommons/trunk/enpraxis/educommons/upgrades/v3_1_1_to_3_2_1.py
  2. Navigate to the root of your ZMI instance and create a new eduCommons site called eduCommons321
  3. Open your new 3.2.1-final eduCommons site in the ZMI. (click educommons Setup, then click Zope Management Interface.)
  4. Navigate to portal_setup
  5. Press the ‘Upgrades’ tab
  6. From the drop down menu, select ‘Products.eduCommons:default’ and click Choose Profile button.
  7. Choose the ‘Migration :: 3.1.1 to 3.2.1’ option
  8. Press Upgrade

Delete old site and rename new site

To tidy up your Data.fs, do the following:

  1. Stop the new site
  2. Copy the Data.fs back to the old site:
    sudo cp -rvfp [new instance home]/var/filestorage/Data.fs [old instance home]/var/
  3. Start the old site
  4. Delete the instance with the id of ‘eduCommons’
  5. Stop the old site
  6. Copy the Data.fs to the new site
    sudo cp -rvfp [old instance home]/var/Data.fs [new instance home]/var/filestorage
  7. Start the new site
  8. If desired, rename your imported eduCommons321 site to eduCommons.

Repackage Course Downloads

You should now repackage the IMS Course Packages. This can be down via an External Method. If you have version 3.2.1, you will need to download this file from the source code https://educommons.com/svn/eduCommons32/enpraxis.educommons/trunk/enpraxis/educommons/extras/repackage_fss_courses.py

  1. Place the file in /instancehome/parts/instancename/Extensions
  2. Navigate to the roote of your eduCommons site in the ZMI
  3. Enter the following parameters:
    • Id: repackage_fss_courses
    • Title: repackage_fss_courses
    • Module Name: repackage_fss_courses
    • Function Name: repackage
  4. Click Add
  5. Click on the repackage_fss_courses script you just added
  6. Click the test tab.

Final Steps

Your site should now be migrated.

Dependent on how customized your 3.1.1 instance is, you should check for the following:

  1. If the style of the site is off (background images have ‘shifted’, for example), your custom CSS is likely conflicting with the default CSS in eduCommons 3.2.1
  2. If you have modified your safe_html portal_transform you may need to manually update the transform in the 3.2.1 instance
  3. Prior versions of Plone offer a linkintegrity feature that provides useful feedback if you delete an object that has been linked to. This feedback allows you to decide whether or not to delete the object, now knowing it has inbound links to it. Unfortunately, the feature also creates redirects to linked-to content that has been moved, without informing the user. This is problematic for eduCommons and reusing content, as the mappings for those redirects are not portable outside of Plone. To mitigate this, during the migration, we have programmatically rewritten any of these mapped links to the current location. To further standardize links, we suggest you perform the following conversion:
    1. Navigate to Site Setup
    2. Navigate to Visual Editor
    3. Click the Link tab
    4. For each of the following types in the select widget (Page, Folder, Folder), do the following:
      1. Click ‘relative path –> uid’

      2. Once the preview is generated, you can analyze the changes that will be made

      3. Once satisfied with the selection process press ‘Commit’.

      4. Now all links will be linked by uid, which will always render as a relative path to the actual location of the object.

Localizing eduCommons

LinguaPlone Translation Instructions

In the context of Department, Course, and ECObjects, translations must occur in a ‘top down’ manner. A Department must be translated prior to translating a Course, which must be translated prior to any objects in the Course being translated.

By default, LinguaPlone will tag newly created content objects in the default language setting for the instance. Objects that exist in the ZODB prior to LinguaPlone being installed will be ‘neutral’, in terms of their language setting. In order to maintain the correct relationships between languages, existing objects must have their language ‘set’.

To set an existing object’s language, click translate into on the management toolbar, and then click manage translations…. This interface will allow you to change the content language setting from neutral to the appropriate setting for your instance.

Localization with eduCommons 3.2.1-final

Overview

If you want to translate eduCommons into your language, here are instructions on how to get started, as well as some guidelines that you should follow when performing a translation. You do not need to know anything about programming to create an eduCommons translation. This has been adapted for eduCommons from the plone translator guidelines. Please see our eduCommons Localization Team page for a list of our volunteer translators.

Introduction

Since eduCommons is customized from Plone, it has built-in support for internationalization. As of June 2006 Plone has 56 different translations. eduCommons requires some additional translation work, but follows the same process as Plone. Adding an eduCommons translation is much less time consuming because most of the translation work has already been done in Plone.

There are about 470 strings needed for a translation of eduCommons (compared to about 1600 strings for a Plone translation). Some of these are sentences or paragraphs, but the major part are one or two words. These strings are scattered around in Plone, for example in page templates. Other items to translate are widget labels, and workflow states. All those strings are collected in master files. These are called .pot files. Each language requires its own .po files that corresponds to the strings or message ids declared in the .pot files. The .pot is the blueprint for the .po files.

Tools

When creating the .po files, we strongly recommend using a specialized tool called poEdit (http://www.poedit.net). This makes the translation process very easy. poEdit exists for both Linux and Windows, and Mac OS X. When you open a .po file with PoEdit, you will see a list of translations in English and four boxes below. As you click on a line to highlight it, you will see that the top two boxes are for English and Default translations. Type your translation in the lower left box. Do not change the naming of the individual translation files. Just send them back when you are done (you may zip them up if you like).

You can also use a normal text editor if you prefer (both vim and emacs are great for this, and have special modes for PO files). If you use a plain text editor instead of a dedicated tool, you should make sure you use utf-8 as your charset, even if your country usually uses iso-8859-* or similar. The reason for this is that Plone uses a few characters (like the ellipsis) that don’t have representations in other charsets. Please review the step-by-step instructions below for more information about the actual translation process.

Step-by-step guide

    1. Check if somebody is working on your language already. Even if they do, contact them and offer to help with testing. There’s no way the eduCommons team can know what is a high-quality translation in a language they don’t know, so your input is very valuable to us. We want good translations, not just a translation. So if you think something is badly done, tell us. Give polite feedback if something feels wrong with the translation to your language. A translation can always be made better.
    2. Be sure that you have used eduCommons enough to grasp the general concepts and how they interact. eduCommons is an advanced system, so be sure you know enough before you start translating key concepts like workflow. Check the language specific terms for your language, or create one if it doesn’t exist. This will help you keep consistent translations for your language.
    3. Download the files to base your translation on. We recommend that you always use the English language files as your starting point, both because they are always the most current ones (other translations will usually lag a bit behind), and because you should try to match the original text. Translating between similar languages may be tempting (like Danish and Norwegian), but will usually result in a lower quality translation. Of course, if the only language you understand is Italian, and you want to provide a Chinese translation, we prefer this translation compared to not getting one at all 🙂
    4. Each product in eduCommons has .po files located in the locales directory. We have combined all these files in a single location of ease of translation. It can be accessed here: http://educommons.com/localization/localization-files.zip If you wish to translate a language for which we do not currently have translation files, please contact us at info [at] educommons [dot] com.
    5. Open poEdit or your editor of choice and load the first of the master files. In poEdit select File –> Open (for existing .po translation files) or File –> New catalog from POT file. (to create a new translation from a .pot file). Be sure to set the language and language code in Catalog –> Settings. With poEdit or other editors you will need to save your new translation files as <product>-<language-code>.po (e.g. for a French translation: plone-fr.po, eduCommons-fr.po, etc). Have a look at http://www.i18nguy.com for the correct language code.
    6. In poEdit, the first line shows the exact string that you have to translate. Your translation is entered in the area below the original string. It’s easy. This is why we recommend poEdit.
    7. In other text editors things will look a little different. An example section can look like this:
#. Default: "Export"  
#: ../skins/eduCommons/Export_form.cpt  
msgid "Export"  
msgstr ""

The first line (marked with Default) shows the exact string that you have to translate. Message attributes in the form ${foo} have to be included in the translated string exactly as they are. These are variables that will be filled in the rendering process. Do not touch this.

The next lines (marked with 🙂 list which templates inside eduCommons use this string. There might be several templates re-using the same string, but it is normally in the same context. Do not touch this.

The next to last line (starting with msgid) holds the unique identifier for the string. Do not touch this.

Finally, the last line is where your job starts. Enter the text in your language, be careful to keep the same casing (where appropriate, some languages have different rules that should be applied).

 

  1. If there is programming code in a string, only translate the string, not the code. For example in, Default: “${number} items matching your criteria.” you would only translate “items matching your criteria.” The code in the first part should be left as it is, so the translation will look like this: ${number} TRANSLATION. 
  2. Keep translating (but take breaks, this isn’t done in one sitting – it’s repetitive (but rewarding) work. After you have translated all of plone.pot, you should start on eduCommons.pot. Don’t worry, you have already completed the biggest part. 
  3. If you can, test your files. Get other people from your own country to test. This means having other people check your file and putting your file in an eduCommons test instance, browsing it in your language. 
  4. If you are unsure about the best translation of a message, you can set it to fuzzy, so others can look at these. Setting a message to fuzzy means adding a “#, fuzzy”-line directly above the line starting with msgid (poEdit has a button for this). 
  5. Since some of the translation files are hosted on the Plone Collective, if you know how SVN works, you can get an account with Plone (Here’s how to request write access to the Collective.) and maintain the files in SVN yourself (see next section). If not, no problem, just e-mail your translation to us at info [at] educommons [dot] com, and we will add it for you and put it into the eduCommons distribution in the next release. We will also add you to our our `eduCommons Localization Team page, here: http://educommons.com/documentation/how-to/educommons-localization-team 
  6. Please check on your translations periodically to keep them updated as new versions are released. A quick search for “” will reveal any new or missing stings that need to be translated. 
  7. If you have other questions or about contributing a translation to eduCommons please contact us at info [at] educommons [dot] com. Thank you for you help!

Join the eduCommons Localization Team!

Thank you to all of our translator worldwide! As of eduCommons 3.2.1-final we have 15 translations either completed or under way, but localization is an ongoing process and we always need more help. There have been many changes with the eduCommons 3.2.1 release, and the translations need to be updated. To join our team, please review the instructions found on the Localizing eduCommons page. To submit translations or direct inquiries, please contact info [at] educommons [dot] com. You are also welcome to join the educommons_loc Yahoo group for up-to-date information about eduCommons localization.

Current translations (version 3.2.1-final)

eduCommons 3.2.1 recent contributors:

  • Simplified Chinese translation (zh-cn) Credit: Jessie Zhu, Utah State University
  • Traditional Chinese translation (zh-tw) Credit: Haishuo Lee, NCTU OCW Office
  • Spanish translation (es) Credit: Guillermo de la Torre, UPM
  • Japanese translation (ja) Credit: Takeshi Yamamoto
  • Turkish translation (tr) Credit: Nergis A. Gurel, Instructional Technology Support Office, Middle East Technical University and Beril Ceylan, Department of Computer Education and Insructional Technology, Ege University
  • Hindi translation (hi) Credit: Jyoti Bawane, Ph.D CES, Indian Institute of Education
  • Italian Translation (it) Credit: Antonio Fini, LTE, University of Florence

Additional languages coming soon!

A language pack with additional translations will be available soon. Here is a list of expected language translations that will be included:

  • Brazilian Portuguese (pr-br) Credit: Universidade Metodista de São Paulo
  • Dutch translation (nl) Credit: Robert Schuwer, Open Universiteit Nederland
  • Catalan translation (ca) Credit: Enric Blasco Avellanas, Centre Recursos per l’Aprenentatge i la Investigació (CRAI), Universitat de Barcelona
  • French translation (fr) Credit: Olivier Turlier, Formation & Métiers CRP La Rouguière
  • Nepali translation (ne) Credit: Hempal Shrestha
  • Russian translation (ru) Credit: Ilya Gelfenbeyn, Russian OpenCourseWare
  • Korean translation (ko) Credit:  Gyutae Kim, Korea University
  • Afrikaans translation (af) Credit: Dr. Jacques du Plessis, School of Information Studies, University of Wisconsin
  • Vietnamese translation (vi) Credit: Professor Nguyen Hoa, PhD, President, University of Languages & International Studies, Vietnam National University

We are looking looking for more translator volunteers, especially for Portuguese (pt), Brazilian Portuguese (pt-br), German (de), Bengali (bn), and other languages. Please contact us if you are interested in contributing. Email: info [at] educommons [dot] com. Thank you!

Past translations

Here is a list of contributors to past eduCommons translations. We appreciate them as well!

  • French 2.3.1 translation (fr) completed by Olivier Turlier, Formation & Métiers CRP La Rouguière
  • Dutch 2.3.1 translation (nl) completed by Robert Schuwer, Open Universiteit Nederland
  • Simplified Chinese translation (zh-cn) 2.3.1 completed by Peter Gong at CORE, QA by Jessie Zhu, Utah State University MA student
  • Traditional Chinese translation (zh-tw) 2.3.1 completed by Jessie Zhu, Utah State University MA student
  • Traditional Chinese, Hong Kong translation (zh-hk) 2.3.1 completed by Jessie Zhu, Utah State University MA student
  • Arabic translation (ar) produced by Abbass Sharrif, Utah State University PhD student
  • Spanish translation (es) produced by Pedro Pernias, Universidad de Alicante
  • Japanese translation (ja) Credit: Takeshi Yamamoto
  • Nepali translation (ne) produced by Hempal Shrestha and his team
  • Korean translation (ko) produced by Gyutae Kim, Korea University

eduCommons: A Guide To Getting Started

eduCommons: A Guide to Getting Started contains nine tutorials to help eduCommons content producers create courses and add content. These sections are also available individually as screencasts. The guide covers the following areas:

  • Logging In
  • Adding a Department
  • Adding a Course
  • Adding a Page
  • Uploading a ZIP File
  • Adding a Link
  • Workflow Roles
  • Adding an Image
  • The Contents Page

eduCommons Setup Instructions

Table of Contents

How To Setup eduCommons

Add/Remove Products

Customizing eduCommons Skin

Mail Settings

Site Settings

Setting the Default Language for your Site

Search Settings

Adding Users/Assigning Roles

Customizing Default Pages

Setting a Default Site-Wide Copyright License

Other Customizations

This documentation assumes that you have already successfully installed eduCommons and are now ready to set it up for use. If you have not yet have a running instance of eduCommons, you may want to refer back to the installation instructions first. They can be found here, or in a file titled “INSTALL.txt” in the root of the eduCommons software tarball. Check to make sure that the version of the documentation matches the version of software you are attempting to install.

How To Setup eduCommons

Most of the settings described below can be found by clicking on the Site Setup link found in the upper right corner of every page. If you do not see this link, it is most likely because you are not logged in as an administrator, or a manager. Also some of the links described below are only available to managers, and will not appear when logged in as an administrator. If you have not yet done any configuration on the site, use the username and password you used to create your Zope instance during installation. This account should automatically assume a manager role. More information about users and roles can be found below in the section titled Adding Users/Assigning Roles.

Add/Remove Products

By default when you install eduCommons all additional addons and products will be installed at the same time. It may be necessary to integrate additional Plone packages into eduCommons. If this is the case for you, use the Add/Remove Products link to do so. You should note that this is definitely within the realm of advanced functionality, and it is likely that more work will need to be done to make any additional packages work correctly with eduCommons. The good news is that for the majority of users, there is no need to add any additional products in order for your instance of eduCommons to function correctly.

Customizing eduCommons Skin

You can customize the look and feel of your eduCommons site by selecting the Left Skin link from within Site Setup. This is a great place to add any institutional branding that may be required for your site. From here you can adjust the colors and images of your eduCommons instance, as well as provide replacement banners and images. Details as to what can be set, and how to set it are included in the form. Any changes made to these settings must be done after having checked the Development Mode box. In order to change the background color in the top nav color, a 1px x 1px transparent gif needs to be loaded first to hide the top nav background image. Be sure to uncheck the Development Mode box after Left Skin changes have been saved to improve site performance.*Remember: you may need to clear your browser’s cache in order to see updates made using this form*.

Mail Settings

eduCommons has a couple of ways to record and verify user email addresses. It also uses email as a primary mechanism for providing you with feedback from users of your site. In order to take advantage of this functionality, it is necessary configure eduCommons to be able to use an email server, and to provide a username/email address which can receive email.

Registration

By default, eduCommons provides a Log in link, but not a Register link. To enable registration on the site, you much login as a manager or administrator. A Site Setup link will appear in the top right corner of the screen. Click on the Security settings link and check the box next to “Enable self-registration.” Be sure to set the Mail Settings in the section below.

Mailhost Settings

eduCommons provides email settings via the Site Setup link found in the upper right corner. You must be logged in as a manager or administrator in order for the appropriate settings to appear. Once you have clicked on the Site Setup link, there should be a list of configuration options available. In the list should be a link titled Mail.

When you click on this link, eduCommons will give you the opportunity to specify an email server to use to send mail through. By default it is set to connect to a mailserver over the localhost network interface. It also contains extra fields to allow eduCommons to authenticate with a mail server not running locally. Care should be taken not to connect to mail servers over hostile networks (e.g. the internet) as authentication details may be passed in the clear. Currently there is not yet support for encrypted connection to mail servers. This should not be a huge limitation as long as you have access to a local mail server.

If you have additional needs you can consider using sendmail or an equivalent mail server package which could run on the same server as eduCommons, which could be configured to forward mail to a trusted mail server using whatever forms of encryption that are appropriate to your situation. Much information on how to configure advanced setups such as these can easily be found on the Internet. Unfortunately further discussion on email server network topologies is beyond the scope of this documentation.

Feedback

eduCommons now uses a feedback form to collect feedback from users. A name and a corresponding email address can be specified in the Site Setup –> Mail, under the Mail Sender tab. Simply fill in the fields marked Site ‘From’ Name and Site ‘From’ address.

Site Settings

The Site Title and Site Description fields should contain values that were initially set during the installation process. If you want to change these fields, you can do so here. The Site Title field is referred to throughout the site. It is important to remember that eduCommons will only change the portal title on a page when a template is applied. If you change this setting here, it will be necessary to also change it throughout the site, or to reapply templates that refer to it.

JavaScript for web statistics support is an area for enabling web statistics support from external providers (for e.g. Google Analytics). Paste the code snippets provided. It will be included in the rendered HTML as entered near the end of the page.

Setting the Default Language for your Site

Using the Language link you can set a default language for your site. This will have the effect of localizing all menu links, navigation and general eduCommons features into the language of your choice.

What If Only Part of the eduCommons Site Appears to be Localized?

The software that eduCommons is built upon (Plone) supports a large number of localizations out of the box. eduCommons is a customization of this software, and has a much more limited support for additional languages. The net result of this is that if you select a language that is supported by Plone but not eduCommons, you may find that some of the items on a page are translated and some are not. If you require localization in a language we do not yet support we would be happy to work with you to help provide this functionality for your site and also to others who may need it. We are always looking for volunteers to help localize eduCommons into new languages. Please visit: http://educommons.com/documentation/how-to/localizing-educommons for more information.

Search Settings

eduCommons uses live AJAX enabled search functionality to display search results as you type. If you prefer to use non AJAX enabled search behavior, you can disable the live search feature by unchecking the Enable LiveSearch checkbox from Site Setup –> Search. All other settings should be left at their default setting.

Adding Users/Assigning Roles

You must be logged in as a manager or administrator to add users and assign user roles. This can be done from the Users and Groups link within Site Setup.

After clicking Add New User, fill out the registration form and register the user. (If you chose to send an email to the new member, be sure you have set up eduCommons to use an email server as described in the Mail Settings section above.) Once you have set up the desired user accounts, click Show All from the User Overview page to display all users. From this view you can assign roles to each user using the check boxes. You may assign multiple roles to a single user if this meets your needs.

For sites with large numbers of users, you may want to use the search feature to search for the name of a user.

There are also check boxes for resetting user passwords and removing users. (Please note that resetting passwords also requires eduCommons to be set up with an email server.) Once you are finished be sure to click Apply changes.

Another way to add users is to allow self-registration via a “Join” link in the upper right-hand corner of the page. To enable this, login to the site as manager and click Site Setup –> Security. Then check the “Enable self-registration” box and click save.

Customizing Default Pages

A default install of eduCommons provides a number of informational pages, namely a front page, and pages in the help and about sections. These pages are typically only meant to be place holders. You should edit these pages accordingly to fit within your institutional guidelines. The front page is meant to be a showcase for your OpenCourseware collection. You can edit and update it as often as you like. You may choose to stick with the default template, or you may change it to suit whatever need you may have.

The help tab points to a page containing frequently asked questions about eduCommons. This document will need to be edited to reflect your specific institution. Also you may want to add or remove questions according to your circumstances.

The about link is a place where you can add any other information about your eduCommons site. The default page links to two other important pages you will want to customize to your site. These are the Terms of Use and Privacy Policy pages.

The terms of use page contains default template text. You will probably want to either edit this text, or provide completely new text that describes your terms of use policy.

The privacy policy page by default simply states that your site has not yet posted a privacy policy, and to use the feedback link to request privacy policy information. Once you have a privacy policy in place you will most likely want to replace the default text on this page.

The number of pages you can have in each of these locations is not limited to the default pages provided by eduCommons. As an administrator, you can create new pages, and link to them from existing pages as much as you like. Feel free to include other pages that provide additional information to your users (or potential users) in any of these sections.

Other Customizations

If you have a need for further customizations in your eduCommons site, it is possible to change things at a number of levels. This flexibility comes at a cost. The more a site is customized, the harder it is to upgrade when new versions become available. It is important to consider carefully the cost of additional functionality before you make any decisions on customizations.

There are other options that are available if you find yourself needing extra functionality. The development site for eduCommons can be used to check to see if your bug is being or has been fixed, or to see what features have been scheduled for development on the roadmap. There are also forums where you can post issues and get responses from the development team and/or other eduCommons users.

eduCommons depends on community support, and participation in the user community/development process is both appreciated and welcome.

How To

eduCommons Setup Instructions

Information about the customization of eduCommons.

eduCommons: A Guide To Getting Started

eduCommons: A Guide to Getting Started contains nine tutorials to help eduCommons content producers create courses and add content.

Installation Instructions

This section describes how to install an instance of eduCommons from source (linux, OSX), from a Windows installer, from a linux RPM, and from a VMWare image.

Join the eduCommons Localization Team!

Localization is an ongoing process and we always need more help. As new versions of eduCommons are released, translations need to be updated. To join our team, please review the instructions found on the Localizing eduCommons page. To submit translations or related questions, please contact info [at] educommons [dot] com.

Localizing eduCommons

Localization documentation for eduCommons.

Migrate between eduCommons versions

Explains how to migrate to the latest version of eduCommons.

Old Migration Instructions

Explains how to migrate forward a legacy version of eduCommons.

Skinning eduCommons

How to adjust the look and feel of your new eduCommons site.

Try It Yourself

Provides a sample courses for experimentation.

eduCommons Adopters

The following is a partial listing of eduCommons-based OpenCourseWare sites from around the world.

Capilano University OpenCourseWare
China Open Resources for Education (CORE)
Cursos Abiertos de la Universidad Nacional de Educación a Distancia (UNED)
Cursos Abiertos de la Universidad Virtual de Salud Cuba
Ege University (EU) OpenCourseWare
Korea University OpenCourseWare
Kyoto University OpenCourseWare
Kyung Hee University OpenCourseWare
Novell OpenCourseWare
OCW Ankara Üniversitesi
OCW de la Universidad de Zaragoza
OCW de la Universitat de Valencia
OCW Universidad de Cantabria
Open.Michigan – Education OpenCourseWare
Open Universiteit Nederland OpenCourseWare
OpenCourseWare de la Universidad Carlos III de Madrid
OpenCourseWare de la Universidad de Huelva
OpenCourseWare de la Universidad de Murcia
OpenCourseWare de la Universidad de Salamanca
OpenCourseWare de la Universidad de Sevilla
OpenCourseWare de la Universidad del País Vasco/Euskal Herriko Unibertsitatea (UPV/EHU)
OpenCourseWare de la Universidad Icesi
OpenCourseWare de la Universidad Industrial de Santander
OpenCourseWare de la Universidad Nacional de Córdoba (UNC)
OpenCourseWare de la Universidad Nacional de Ingeniería
OpenCourseWare de la Universidad Politécnica de Madrid
OpenCourseWare de la Universitat de les Illes Balears
OpenCourseWare de la Universitat Oberta de Catalunya
Osaka University OpenCourseWare
Proyectos abiertos de la Universidad de Alicante
RoboticsCourseWare
Russian OpenCourseWare
UMass Boston OpenCourseWare
Universidad de Monterrey (UDEM) OpenCourseWare
Teachers Without Borders
University of Notre Dame OpenCourseWare
University of Tsukuba OpenCourseWare
Utah State University OpenCourseWare
United Nations University OpenCourseWare
Weber State University OpenCourseWare
Western Governors University OpenCourseWare

To have your eduCommons OpenCourseWareW site added to the list please email us at info [at] educommons [dot] com.