.-----------------.
| Getting Started |
'-----------------'
You can get started with SeeSaw with just the following files. They
are sufficient to enable the creation of links or buttons for
manipulating sections.

  o SeeSaw.py
  o seesaw.js
  o jquery-1.4.4.min.js


Installation
============
SeeSaw.py
---------
Install SeeSaw.py in the place where you normally install third-party macros.
This will probably be in data/plugin/macro within the wiki, or since 1.8,
could be in a place listed in the wiki configuration variable plugin_dirs.

seesaw.js
---------
The simplest place to install seesaw.js initially in order to get SeeSaw
working is within MoinMoin's htdocs/common/js directory.

jquery-1.4.4.min.js
-------------------
Install jquery-1.4.4.min.js in the same place as seesaw.js

I've provided the version of jQuery current at the time of release. I keep
a lookout for new releases of jQuery and test them at http://seesaw.ncl.ac.uk.
The home page there will indicate which version it uses.


Configuration
=============
Configure html_head in your wiki's wikiconfig.py configuration file as
follows:

    html_head = '''
<script type="text/javascript" src="<url_prefix_static>/common/js/jquery-1.4.4.min.js"></script>
<script type="text/javascript" src="<url_prefix_static>/common/js/seesaw.js"></script>
'''

replacing <url_prefix_static> with the value of url_prefix_static used by the
configuration file.

NB You may need to restart your Web server for the changes to take effect.


Testing
=======
If you've got everything right, the following markup should work

<<SeeSaw()>>{{{  }}}<<SeeSaw(type=button)>>
{{{#!wiki seesaw section
This is the section
}}}

It should present a 'Show' link and a 'Show' button, both of which turn to
'Hide' when either is clicked, and reveal the section containing the text
'This is the section'. Clicking either 'Hide' should cause a return to the
initial state.


Alternative Installation
========================
You can install the .js files anywhere you like. I prefer not to
install them within the MoinMoin installation tree in order to avoid
having to re-install them at upgrades. If you put them somewhere else
then you have to configure your server to be able to access them,
e.g.through the use an Alias directive for Apache and suitably
adjusted entries in html_head..


.-----------------------------.
| Images in Links and Buttons |
'-----------------------------'

The images in the img subdirectory need to be installed in order to be able to
use the image= option with them. The simplest place would be in htdocs/common
within MoinMoin's installation tree.

You also have to configure img_prefix in SeeSaw.py. For the case above, the
value would be

   img_prefix = '<url_prefix_static>/common'

if you put the individual files directly into common, or

   img_prefix = '<url_prefix_static>/common/img'

if you copy the directory there. As above, you replace <url_prefix_static>
with the value of the variable url_prefix_static in your wiki's configuration
file.

NB You may need to restart your Web server for the changes to take effect.


Testing
=======
If you've got everything right, the following markup should work

<<SeeSaw(image=arrow)>>{{{  }}}<<SeeSaw(image=plumin)>>{{{  }}}
<<SeeSaw(image=arrow, type=button)>>{{{  }}}
<<SeeSaw(image=plumin, type=button)>>
{{{#!wiki seesaw section
This is the section
}}}

You can install the images anywhere you like, but of course you then need to
configure your Web server to be able to access them through the img_prefix you
choose.


That's everything that's needed for all of SeeSaw's features to work.

------------------------------------------------------------------------------

The following is optional.

.--------------------.
| Anti-jump Solution |
'--------------------'
If you experience page jump as a page is rendered, i.e. sections of
the page that are to be hidden initially are seen briefly before being
withdrawn, you could try the following solution:

 1. Install seesawnojump.js alongside the other .js files

 1. Install seesawnojump.css where your server can access it; beside the .js
    files would be as good as any to start with

 3. Edit seesawnojump.js so that the line referring to seesawnojump.css
    contains an href such that your server can access it, e.g.

    style.href = "<url_prefix_static>/common/js/seesawnojump.css"

 4. Add a further entry to html_head to load seesawnojump.js, e.g.

    <script type="text/javascript" src="<url_prefix_static>/common/js/seesawnojump.js"></script>

NB You may need to restart your Web server for the changes to take effect.


Jim Wight
January 2011
