Skip to content
This repository has been archived by the owner on Feb 6, 2022. It is now read-only.

Latest commit

 

History

History
344 lines (236 loc) · 16.2 KB

README.textile

File metadata and controls

344 lines (236 loc) · 16.2 KB

Ba

Ba is a conference and event management system based on Radiant.
Ba aims to be minimalistic and reuse Radiant and other Radiant extensions as much as possible.

Essentially, Ba lets site admins create special “happening” pages which have additional properties
such as a start date and end date. This page (and all subpages) can then use special Ba tags to design
the conference site.

Ba expects you to follow some conventions, such as defining special page parts for the happening
pages. Please refer to the Usage section for details.

We chose the name Ba because it’s Japanese for “a place that supports sharing and relationship building”
and because Japanese is hot. Ba will be used for a 500 people conference, Smidig 2008
and hopefully for lots of other conferences and other happenings in the future.

Features

The features in Ba target 3 main roles: organisers, speakers and regular attendees.

Organizers

The organiser tools consist of extensions to the Radiant admin panel as well as custom tags.

  • Create new happenings (conference or event).
  • Set up a schedule/program
  • Send mass emails to attendees
  • Manage price/discount codes
  • List attendees and billing status
  • Several radius tags for happening related content

Speakers

  • Register talks/presentations
  • Attach slides

Attendees + speakers

  • Maintain a bio

Installation

The first thing to do is to create a clone of Radiant. Actually, you should clone
Aslak Hellesøy’s Radiant clone, because this
clone has Ba and all other required extensions and plugins installed as Git submodules. Here is how
you do that:

git clone git://github.com/aslakhellesoy/radiant.git radiant_ba
cd radiant_ba
git submodule init
git submodule update

When you have a local clone, set up you database configuration. Copy one of the config/database.xxx.yml files to
config/database.yml. If you’re using anything else than SQLite (which works fine) you also need to create
the databases specified in config.yml.

Now, let’s create all the tables:

rake db:bootstrap (Say yes to blow away db and choose the "Empty" database template - the others will cause errors at this stage)
rake radiant:extensions:reorder:migrate db:migrate:extensions radiant:extensions:update_all

Run all tests to validate that you have installed everything correctly:

rake radiant:extensions:ba:features_and_specs

Start Radiant with script/server and go to http://localhost:3000

Creating your first happening with Ba

Once you have Ba installed, you can set up as many happenings as you want. This is ideal for organisations and companies
that want to organise a happening more than once. You don’t have to set up a new website – you just create a new page in
Radiant…

Creating a new happening

  1. Choose “Add Child” somewhere in the Page tree (/admin/pages)
  2. Select “Happening” from the page type dropdown list
  3. Choose “Save and Continue Editing”

In addition to creating the HappeningPage, this will also create several sub pages – each with default contents in the body
part to get you started:


+-LoginPage                 # Global login page
+-AccountPage               # Global account settings
+-HappeningPage             # The main page for a Happening. Gets a "body" and "signup_confirmation_email" part.
  +-SignupPage              # The signup form
  +-AttendancePage          # List attendance info like talk proposals, change promotion code etc.
  +-EditPresentationPage    # Add or edit talk proposals
  +-PresentationsPage       # Hidden page that serves as a "directory" for presentations (PresentationPage)
    +-PresentationPage      # (Added later). People who have signed up can add and edit these via EditPresentationPage

A new HappeningPage will also have a “signup_confirmation_email” part for signup confirmation emails. More details on that below.

As you’ll see, several of the available ba tags are used on these parts, and they are all documented in more detail in Radiant’s
admin interface. You can see this documentation by choosing the “Available Tags” link while editing a page and entering
r:ba in the search box.

Assigning prices

When a new Happening page is created, it is set up with a default price of NOK 250 and unlimited seats. You
can change this in the Admin UI.

It’s common to have different prices for the same happening. Students and sponsors may get a cheaper price than
regular attendees etc. Ba lets you create several prices for a happening and you can choose a code for
each one of them. People who know about these codes can then use them when signing up for a happening, and their
attendance will be associated with the correct price.

If you have early bird prices, the easiest is to change the default price after the early bird time period has
expired. This will not cause previously signed up people to get the new price, as each attendance keeps
the price they were originally signed up with.

Note that Ba does not handle the billing itself (there is no ActiveMerchant or similar integration yet). This means
that you have to get the attendee data out of your database in a separate process and handle them outside Radiant/Ba.

Creating a program

The program is created from presentation proposals which can be created underneath [happening url]/attendance. When
a potential speaker creates a presentation proposal, a regular radiant page is created underneath the happening. By
default those pages will be unpblished (draft), so only Radiant admins can see them.

Creating a program skeleton

The first step to creating a program is to create the program skeleton. This is simply a “Program” page underneath your “Happening” page. You can use special tags to create slots for presentations in your program, and you have complete freedom over the layout. The following example (Using Textile) is what we’re using for a conference with lots of lightning talks:


<r:ba:program empty_text="To be announced">
table(prettytable).
|_. Tidspunkt    |_. Hall A                       |_. Hall B                       |_. Auditorium                   |
|/4. 09:00-09.50 | <r:presentation slot="1000" /> | <r:presentation slot="1001" /> | <r:presentation slot="1002" /> |
                 | <r:presentation slot="1003" /> | <r:presentation slot="1004" /> | <r:presentation slot="1005" /> |
                 | <r:presentation slot="1006" /> | <r:presentation slot="1007" /> | <r:presentation slot="1008" /> |
                 | <r:presentation slot="1009" /> | <r:presentation slot="1010" /> | <r:presentation slot="1011" /> |
|/4. 10:00-10.50 | <r:presentation slot="1012" /> | <r:presentation slot="1013" /> | <r:presentation slot="1014" /> |
                 | <r:presentation slot="1015" /> | <r:presentation slot="1016" /> | <r:presentation slot="1017" /> |
                 | <r:presentation slot="1018" /> | <r:presentation slot="1019" /> | <r:presentation slot="1020" /> |
                 | <r:presentation slot="1021" /> | <r:presentation slot="1022" /> | <r:presentation slot="1023" /> |
</r:ba:program>

(If you’re reading this at GitHub you may not see the markup properly – see the source instead)

The ba:program:presentation tag will contain a link to the presentation you choose to put there. This is done in the admin
interface. All you need to do is to assign a unique id to each ba:program:presentation tag.

You can create several program pages underneath a happening. This allows you to have separate programs for each day. You still
have to make sure each id is unique across the program pages. If you have several program pages for an event, it can be wise to use a different series of integers for the slots, e.g. 1000..1020 for Day 1, 2000..2020 for day 2 etc.

Adding presentations to the program

When you have created a program page with a skeleton structure, you can go to the Programs tab in the admin interface
and drag presentations onto the slots in the program.

A presentation will be instantly published when dragged onto a slot, and put in the draft state when placed at the draft
section at the bottom of the page.

Importing users

If you’re setting up Ba for the first time, you can import a list of users (potential attendees) into Ba.
This is especially useful if you use the mass email feature (see below).

Ba manages attendees separately from Radiant’s admin/developer users. (Ba stores them in the
site_users table).

Ba comes with a script that can import users into the site_users table. You first have to create a CSV
file that looks something like the following:


name,email,phone,company_name,billing_address,billing_city,billing_postal_code,created_at
Frank Zappa,[email protected],,,Downtown rd 34,Champagne,12345,IL

The first line must contain column names of the site_users table, and the remaining rows the values.

Once you have created this file, you can import them into Ba by standing in the RADIANT_ROOT and running:


script/runner vendor/extensions/ba/script/import_site_users.rb path_to_your_csv_file

All imported users will be put in a “pending” state and a secret actication code will be created for
each of the new users. Each user will need their activation code to log in the first time.

This is when you send email invitations (details below). Each of your imported user will receive an email,
they click a link in their email, and they come straight to a page where they can sign up to your event.
The form fields will be pre-filled with the info you imported the user with. Then the user can change
some of the fields (password/confirmation mandatory) and register. It doesn’t get much simpler.

Email

Email is a central part of organizing conferences and events. Ba supports the most common scenarios that can be cumbersome to do with a regular email client.

Configuring Email

Ba will send confirmation emails to people who sign up. In order for this to work, you must configure ActionMailer
in your environment/production.rb file. See environment/development.rb for an example.

You also have to set up the template email that people will receive. This is done in the signup_confirmation_email
part on the happening page (a default part will be created when you create a happening).

You can use both Textile and “none” filters for this part (which will send HTML or plain text email, respectibely).
The formatting is special – the first two lines must have From: and Subject: headers followed by a new line.
The remaining lines must contain the body of the email.

If you do not wish to send confirmation emails for a happening, just delete the signup_confirmation_email part.

In the body you can use any r:ba:email tag to add personalised content.

Sending mass emails and invitations

If you have configured ActionMailer as described above, you can also send mass emails to combinations of attendees
and speakers of a happening. This is done from the admin interface. The “Email” tab will list all site users, and
you can filter who you want to send emails to.

If you choose to invite people this way, make sure the email you’re sending contains a link to your
happening’s signup page – with the user’s activation code. For example:

"Beerfest 2008" <[email protected]>
Invitation til Beerfest 2008

Hi, <r:ba:email:site_user:name />

We hope you liked Beerfest 2007, and we have the pleasure of inviting you to Beerfest 2008
at the North pole on December 24th.

Sign up here: http://beerfest.no/beerfest2008/signup?activation_code=<r:ba:email:site_user:activation_code />

See you!

Login and account setting

In order for your users to be able to manage their own account, Ba creates a Login and Account page in the database
migrations. You can change the contents in the admin interface. Make sure you keep the same form and input fields.

You may also want to create a “login_logout” snippet that you can use in your layout. Something like this:


<r:ba:if_logged_in>
"My account":/account |
"Log out":/logout
</r:ba:if_logged_in>

<r:ba:unless_logged_in>
"Log in":/login
</r:ba:unless_logged_in>

Contributing

Want to help out with development of Ba? Start by reading 8 steps for fixing other people’s code if you’re new to
open source development. Then, follow the installation instructions above. You can’t check out the Ba repository alone –
it has to be within a Radiant clone.

Run tests

When you have the code installed, install the libraries needed by the tests:

gem install hpricot
gem install treetop
gem install term-ansicolor
gem install diff-lcs
cd vendor/plugins/cucumber
rake install_gem

make sure you can run the awesome test suite based on RSpec and Cucumber.

rake radiant:extensions:ba:features_and_specs

This should produce all green, passing features and specs.

Important: You may have to comment out the routes in RADIANT_ROOT/test/fixtures/extensions/01_basic/basic_extension.rb
in order to make the features pass.

During development it can be very useful to run individual features and scenarios. This can be done
with commands like these:

cucumber vendor/extensions/ba/features/create_conference.feature
cucumber vendor/extensions/ba/features/sign_up.feature --line 7
cucumber --help

BDD

If you have found a bug or want to add a feature, start by writing a new feature or scenario that describes the
feature you want. Snoop around in the existing features (in the features folder) to get started. Alternatively,
if you want to fix something more low level, write a spec instead (see the specs folder).

Now run the features or specs again. The one you wrote should fail. (If it doesn’t you’re doing something wrong,
or the feature is already implemented).

This is when you start writing code. You might as well get used to doing it this way, because we won’t accept
any patches unless you also have features or specs for your code. This is because we don’t want to end up with a
brittle, unmaintainable, undocumented pile of code that nobody understands. (Yes, stores and specs are documentation too).

If you think this sounds annoying, try it out anyway. You’ll end up writing better (and less) code this way. Trust me.
Work outside-in (the outside being the feature, the inside being the low level code). Do it the BDD way.

Tips

These tips apply to Rails development in general…

  • Talk to models directly in Given steps
  • Use Webrat in When steps
  • Use Webrat and/or models in Then steps
  • Organise steps in files named accordingly to resources used
  • Avoid keeping state in @variables in steps. It will couple your steps and make them harder to reuse.

Deployment

We recommend deploying Radiant+Ba to a POSIX server (Linux/Solaris), because that’s what we’re familiar with.
Use Capistrano for this.

Remember to manually set

Radiant::Config['tags.results_page_url'] = 'results'

(or something similar) in a production console. It’s needed in order for page tagging to work.

You may try to package the whole thing into a war file with Warbler
and deploy it to a Java servlet container, but noone has tried this yet (to our knowledge).

Getting in touch

There is no mailing list or forum yet, so please use the radiant forum for now. If it gets too busy there we’ll
set up a separate mailing list.

Credits

  • Marty Haught for his Page Event extension. Ba is inspired from this.
  • Tobin Richard for the “Shopping Trike” extension. It gave me insight into how to organise different dynamic pages in parts.
  • Johannes Brodwall for help on early versions of Ba

TODO

  • “presentation_questions” part on HappeningPage where admins can enter extra questions, like “Complexity” [Beginner, Intermediate, Advanced] etc.
  • Similar for “signup_questions”