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

Meta::

Valid for:  SilvaPoll-generic-0.4
Authors:    Guido Wesdorp, Wim Boucquaert, Jasper Op De Coul
Email:      guido@infrae.com, wim@infrae.com, jasper@infrae.com

Copyright (c) 2006-2007 Infrae. All rights reserved.
See also LICENSE.txt

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
Service Polls' 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 Service Polls 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
