====================
Installing SilvaPoll
====================


Prerequisites
=============

SilvaPoll 0.4 requires a working Silva 2.0.x installation, with
SilvaExternalSources installed properly. If you want to use the MySQL
service for storing poll data, a recent MySQL database and the
zMySQLDA product should be installed, too.

Basic installation instructions
===============================

- Unpack the SilvaPoll tarball in the Products directory of your Zope
  instance.

- Restart Zope. 

- Go to ``service_extensions`` in your Silva root services (for Silva
  installation instructions, see Silva/INSTALL.txt), make sure that
  the SilvaExternalSource package has been activated properly (if the
  box is still gray, press the 'activate' button)

- Press the 'activate' button in the SilvaPoll box. Or press 'refresh
  all' at the top of the listing if you're updating other packages
  besides SilvaPoll.

- Install a poll service (see next section).

- Probably you'll have to turn on Silva Poll Question in the addables
  (see below).

Installing a service for data
-----------------------------

SilvaPoll comes with two different services that manage poll data:
there's one to add the data to the ZODB and one that uses a MySQL
database. The ZODB based version creates a new transaction on every
vote, thus sites that expect heavy usage may want to store the results
seperately.

To install the ZODB version, go to the Silva root (ZMI) and choose
'Silva Poll Service' from the 'add' select menu. This will take you to
a screen where an id and title can be entered for the service, leave
the id as is, and optionally fill in the title.

Installing the MySQL service requires similar steps, but also requires
a zMySQLDA database adapter to be installed, with the id
'service_polls_mysqldb'.  Once this adapter has been placed, add a
'Silva Poll Service MySQL' and also make sure to not change the id (a
ZODB and MySQL service can not co-exist).

By default the option store cookie is turned on. This option limits voting by
setting a cookie on the users computer. If you don't want voting limits you
should uncheck this option.

Addable configuration
---------------------

Depending on other Silva products installed on your system, you might
need to adjust the 'addables' settings on the Silva root. Go to the
properties tab of the Silva root in the SMI, choose 'addables' and
make sure the checkbox in front of 'Silva Poll Question' is
checked. You can also turn it on in the addables properties of a lower
level publication.

How to stop displaying the Silva Poll Questions in the TOC (Table Of Contents)
==============================================================================

By default Silva Poll Questions are not hidden for the TOC. As navigation
the navigation of Silva relies on TOC they will be shown by default there.

There are 2 ways on how to avoid this:
1) On a question basis:
Go to the properties of a question and set the option "hide from tables of
content" to hide. You'll have to repeat this step for every question you want
to hide.

2) Universal method to hide all Questions:
People who never want to show Silva Poll Questions in the navigation (menus and TOCs) can
do this by changing the code that creates the navigation in the layout.

For instance in get_public_tree.py You can add a condition there to
not show an OBJECT of the metatype "Silva Poll Question":
OBJECT.meta_type == 'Silva Poll Question'

e.g.:
def get_tree_html(node, endobj):
    tree = ''
    endpath = endobj.getPhysicalPath()
    for OBJECT in node.get_ordered_publishables():
        if not OBJECT.is_published():
            continue
        if OBJECT.get_metadata_element(
            'silva-extra', 'hide_from_tocs') == 'hide' or
            OBJECT.meta_type == 'Silva Poll Question':
            continue
            ...

IMPORTANT: It is not recommended to change files in the Silva core as they
won't survive upgrades. Make your own navigation code, or, if you're using the
Silva Layout extension, you can override core views with your own code.

Styling Silva Poll
==================

Using the head_inject
----------------------
When the SilvaPoll extension is installed there are CSS files and other
resources located in the service_resources folder of your Silva root in its
SilvaPoll folder. You can find these in:

/[yourSilvaRoot]/service_resources/SilvaPoll/manage_main

When a Poll Question content type is used like a document, it can automatically
reference the poll.css (but this won't happen when a Question is embedded in a
Silva Document, and in that case you should use one of the other methods).

To enable this place a tal:block with a condition in the head_inject
*within* the tal:block that defines 'model', thus::

  <tal:block define="model request/model|here">
    <!-- your conditions go here -->
  </tal:block>:

This is the condition block for detecting Poll Questions::

  <tal:comment replace="nothing"> _______ SilvaPoll CSS _______ </tal:comment>
  <tal:block condition="python:model.meta_type == 'Silva Poll Question'">
    <link rel="stylesheet" type="text/css" media="all"
      tal:attributes="href python:context.get_root_url()+'/service_resources/SilvaPoll/poll.css'" />
  </tal:block>

Now when a user visits a Poll Question, the poll.css stylesheet should also be
referenced by your layout. Probably it will be the last stylesheet referenced
so it will 'win' in a conflict with other stylesheets.

Note that the files in service_resources are on the file system and should not
be edited because they won't survive upgrades. If you're not satisfied with the
poll.css you can change the path in the head_inject to reference your own
poll.css file somewhere else.

DTML-way
--------
Make a new DTML method or DTML document called e.g. "poll.css" and include all
the content of dtmlpoll.css and reference the newly created css in your layout.
You can also add the selectors to an existing DTML method/document. Customize
background image references and other references as needed. This approach has 
the advantage that you can set caching headers.

Non-DTML-way
------------
Make a new a new css file e.g. "poll.css" and include all content of poll.css and
include the the newly created css in your Silva. You can also add the selectors
to an existing css file. Customize background image references and other
references as wanted.

ZCML-way
--------
Add the content of zcmlpoll.css to your existing layout.css. Customize
background image references and other references as wanted.


Contact information
===================

For questions, bug reports, etc. send email to wim@infrae.com, jasper@infrae.com
