vdz.plone.projectreview 1.0.0.dev2

Project reviews for Plone

vdz.plone.projectreview

This Plone add-on has been developed by visaplan GmbH, Bochum, Germany for VDZ Technology gGmbH, Düsseldorf, Germany, to evaluate projects.

Examples

This add-on is currently under development and not yet used on public internet sites.

Documentation

Sorry, we don’t have real user documentation yet.

Installation

These instructions assume you have shell access to the server which will run the your Plone instance and moderate shell using skills.

Install Plone

The vdz.plone.projectreview package is an add-on for the open-source content management system Plone, which in turn is based on the web application server Zope.

Currently, vdz.plone.projectreview still needs Plone 4.3; see Issue 1, “Plone 5 support”.

If you don’t have a suitable Plone installation yet, you can use the Unified Installer. Install a recent 4.3 version.

At the time of this writing, the latest release provided via UnifiedInstaller is 4.3.19, but 4.3.20 is soft released and ready for production use.

We need to apply a few little changes to your buildout script, typically named buildout.cfg; thus, don’t run buildout immediately (unless you want to do it twice).

Please note:

A vanilla Plone 4.3.19 most likely won’t work because of the broken main_template.pt it contains. So, if you get an ugly little error text about a compilation error when trying to access the web interface (or just to have the most recent version), please update to Plone 4.3.20 (which is expected to be the last 4.3 release), by replacing e.g.:

[buildout]
...
extends =
    ...
    versions.cfg

by:

[buildout]
...
extends =
    ...
    https://dist.plone.org/release/4.3.20/versions.cfg

If you already have a running Plone 4.3.19, you probably use an alternative main_template.pt already (as we’ll do as well, using plonetheme.bootstrap), and may continue to do so.

You are encouraged to update, of course, but there is not technical requirement to do so for vdz.plone.projectreview.

Use an existing Plone 4 installation

If you have an existing Plone 4 installation, you might be able to use it. There are a few things to consider:

• Since we use plonetheme.bootstrap, the global main_template is overridden. If you rely on another main_template, this probably won’t work.

• We use Bootstrap 3 styles.

• We use jQuery 1.11 (or higher). If you have incompatible custom Javascript which needs an older version (e.g. using the old .live and .die API which was removed in jQuery 1.9+), you’ll need to install a compatibility layer or update your scripts.

The rule is:

• If you are fine with the product activations needed for vdz.plone.projectreview and with the package versions, you can use your existing Plone instance.

• If our product activations don’t match your needs, but the package versions do (e.g. you can live with plone.app.jquery being v1.11.2 and a 4.3.* Products.CMFPlone version), you should be able to use your existing Zope installation and create a new Plone site in it, with an id of your choice.

Please test the coexistence of your current site with vdz.plone.projectreview in a dedicated test environment!

Add vdz.plone.projectreview

First, the vdz.plone.projectreview package must be added to the eggs value; the Unified Installer puts this in the [buildout] section:

[buildout]

...

eggs =
    Plone
    vdz.plone.projectreview

Since we use a relational database, you’ll need a database driver as well. Our package pulls in SQLAlchemy (via zope.sqlalchemy) itself, but you’ll need a specific driver for your database. For PostgreSQL, this might be psycopg2:

eggs =
    ...
    vdz.plone.projectreview
    psycopg2

Version pinnings

Since we use Bootstrap 3, we need jQuery 1.11+. Plone 4.3 by default still uses jQuery 1.7, for historical reasons.

Your buildout.cfg script extends other scripts, containing version pinnings. Find or create the [versions] section in buildout.cfg and override the 1.7.* value:

[versions]
...
plone.app.jquery_ = 1.11.2

Product configuration

There are two configuration settings which are done in the buildout:

1. the data source name, specifying the relational database;

2. a directory path for file attachments.

For these, we’ll create additional text for the zope.conf file(s) of your Zope instance part(s).

You might want to put these settings in a dedicated settings.cfg file and add this to the extends list. The Unified Installer uses the [buildout] section:

[buildout]
zope-conf-additional =
    <product-config projectreview>
    data-dir ${buildout:directory}/var/myattachmentsdir
    </product-config>
    <product-config reldb>
    dsn      postgresql+psycopg2://localhost/mydb
    </product-config>

In this case, you’ll need to make sure this value is used for your instance parts, e.g. in base.cfg:

[instance_base]
...
zope-conf-additional = ${buildout:zope-conf-additional}

Build and start

With everything in place, run bin/buildout.

If you didn’t specify an own administration password, be sure you have it in the buildout, or to write it down; you’ll need it to login to your fresh Zope instance and create the “real” users.

Start up the instance (depending on the type of your installation), e.g.:

bin/instance fg

Database initialization

(TODO; script needed)

Product installations

In the prefs_install_products_form view of your instance, we’ll activate the following extensions (if not already done):

• vdz.plone.projectreview

• Bootstrap Theme

• jQuery DataTables

• jQuery UI

We’ll deactivate:

• Classic Plone design

Update to Plone 5

Finally, a few remarks considering Plone 5.

Most of the parts are Plone-5- and Python-3-ready already, so there might be an update soon.

However, all projects data is held in a relational database anyway, so it should be possible to use this in a fresh installation without any necessary data migration, just using the same data source name.

The only thing which would need to be migrated (in the standard case) is the user and groups information; this is beyond the scope of this documentation. In most cases, this involves so few user accounts and groups that it can be done by hand easily.

Dependencies

• Products.CMFPlone:

  This is “the Plone” we use.

  • Currently we require a 4.3 version.

  • Version 4.3.19 is broken regarding the contained main_template.pt skin layer template; thus, a vanilla Plone 4.3.19 (e.g. for fresh installations) most likely won’t work. Since this template is frequently overridden, this is not a hard requirement; in case of problems, please follow the instructions above to upgrade to release 4.3.20.

• Python 2.7:

  Because Plone 4.3 requires Python 2.7, so do we (for the moment). Our Python code should support Python 3 already, using the six library.

Used software

General purpose

• Plone

• Zope

• Python

• SQLAlchemy, via zope.sqlalchemy

• Bootstrap 3.3.7, via collective.js.bootstrap and plonetheme.bootstrap

• jQuery 1.11.2+, via plone.app.jquery

More specific, or developed for this project

• visaplan.zope.reldb, to configure the data source name and provide some SQL generating functions

• visaplan.zope.inputmacros (TAL templates for generation of form and output fields)

• visaplan.plone.infohubs (a mini language to access sevaral Plone features)

• visaplan.plone.tools

• visaplan.tools (non-Plone-specific Python utilites)

Included Software

This package includes the following Javascript libraries we didn’t find a ready Plone integration to use:

• Chosen 1.8.7

• jQuery Keypad

Contribute

• Issue Tracker: https://github.com/visaplan/vdz.plone.projectreview/issues

• Source Code: https://github.com/visaplan/vdz.plone.projectreview

Support

If you are having issues, please let us know; please use the issue tracker mentioned above.

License

• The project is licensed under the GPLv2.

• The following components are licensed under the MIT license:

  • Chosen

  • jQuery Keypad

Contributors

• Tobias Herp, [e-mail]

Changelog

1.0.0 (unreleased)

• Initial release. [tobiasherp]