About switchboard-tg2

switchboard-tg2 provides an easy way to plug Switchboard, a feature flipper library, into TurboGears2 applications.

Installing

switchboard-tg2 can be installed both from pypi:

easy_install switchboard-tg2

should just work for most of the users.

Using switchboard-tg2

In your application config/app_cfg.py import plug:

from tgext.pluggable import plug

Then at the end of the file call plug with switchboard-tg2:

plug(base_config, 'switchboard_tg2')

You will be able to access Switchboard’s admin UI at http://localhost:8080/switchboard.

You will also need to configure Switchboard’s access to memcached and MongoDB. By default Switchboard attempts to connect to both of these services on localhost and on the default ports. If it fails to connect it will fall back to in-memory equivalents and display warning messages in the admin UI.

While running with the in-memory mode enabled is fine for getting started quickly, please do not run in production in this mode!

Getting Started - An Example

The switchboard-tg2 code contains an example TurboGears 2 application, modified to use Switchboard. The application is a quickstart application and the only changes made to it where to setup Switchboard. You’ll find the application in the ‘example’ directory. Here’s how Switchboard was added to the app:

1. Add the plug call to app_cfg.py:

   from tgext.pluggable import plug
   ...
   plug(base_config, 'switchboard_tg2')

2. Import Switchboard’s operator and use it to optionally display a flash message from the root.py controller, as an example of using Switchboard in Python code:

   from switchboard import operator
   ...
   if operator.is_active('hello_world'):
       flash('Hello World')

3. Next, we want to pass the operator off to the template so that we can also use it there. Again, in the root.py controller:

   return(page='index', operator=operator)

4. Finally we can use the operator in the index.html template to make various parts of the page turn on or off:

   <py:if test="operator.is_active('getting_started')">
   ...
   </py:if>

One thing to note: the template demonstrates the use of parent/child switches. The getting_started switch is the parent switch. Any switch prefixed with getting_started: will be a child. Children inherit conditions from their parents and can add conditions of their own.

To see all of these switches in action: run paster serve development.ini in the example directory and point your browser to http://localhost:8080/. Once you load the index page, all of the switches encountered will be automagically created within Switchboard. When you pull up the admin UI at http://localhost:8080/switchboard/, you’ll see the hello_world and getting_started switches.

Set the getting_started switch to “Active for everyone” and reload the index page. Now reload the Switchboard admin and you should see several more of the child switches for the Getting Started section. These switches weren’t created because they weren’t even checked until their parent switch was turned on.

Play around with turning various switches on and off to see what impact it has on the index page. You can also try adding conditions to a switch to see what happens when a switch is only active under certain conditions.

Here’s a diff of all the changes made to the example app to change it from the stock quickstart app to a Switchboard-enabled app:

http://pastie.org/6634144

More information

You can find more information about Switchboard and how to use it in your code in the Switchboard docs.