= Giftsmas
Giftsmas is a website that is useful for keeping track of gifts people
received. It is designed around a moderate size family keeping track of all
gifts that any member of the family received for Christmas.
== Prerequisites for general use
* ruby
* rubygems
* postgresql
* ruby-pg, ruby-postgres, or postgres-pr
* sinatra (0.3.1)
* sequel (git HEAD)
* sequel_postgresql_triggers (1.0.1, from github)
* scaffolding_extensions (1.3.1)
== Command line setup
After cloning the repository from github, switch to the giftsmas directory:
cd /path/to/giftsmas
Create the db and run the migration:
createdb giftsmas
sequel -m migrate postgres:///giftsmas
Create your user(s):
irb -rmodels
irb(main):001:0> User.create(:name=>'...', :password=>'...')
Modify the configuration for the server, if necessary:
cp config.rb.example config.rb
$EDITOR config.rb
Start the server:
ruby giftsmas.rb
== The web interface
Giftsmas, like Sinatra, runs on port 4567 by default (you can modify this in
config.rb with the :port option to set). So open up your webbrowser:
$BROWSER http://localhost:4567
It will redirect you to the login page. Put in a username and password that
you created earlier and click "Login". It will ask you to create an event.
Choose an event name and click "Create New Event". It will put you on the add
gift page. Put in a gift name, sender name(s), and receiver name(s) and click
"Add Gift". It will add the gift to the database and put you back at the add
gift page, but this time you'll have select boxes for the senders and receivers
you entered. If you want to use a sender or receiver that's not in one of
the select boxes, type the name in (you can separate names with a comma). This
is true even if you want to use a sender that isn't in the sender select box
but is in the receiver select box (you can always type in the names, it doesn't
create duplicates).
== Other pages
=== Event
* Associate Receivers: You can use this to associate other people as possible
receivers in the current event (so they show up in the receivers select box
on the add gift page). Mostly useful if you have multiple events and most
of the people in this event were also in a previous event.
* Associate Senders: Same as Associate Receivers, but for senders.
* Change Event: Change the currently used event, either by picking another
event or adding a new event.
=== Gift Reports
* In Chronological Order: Simple report listing all gifts received in
chronological order.
* By Receiver: Gives separate reports for each receiver. When printing the
reports, uses one page per receiver, good for writing thank you notes.
* By Sender: Similar to By Receiver, but for senders.
* Summary: Shows the total number of gifts, as well as totals by sender
and receiver.
* Summary Crosstab: Shows for each sender/receiver pair, how many gifts the
sender gave the receiver.
=== Other
This are simple scaffold pages for changing data in the database. You can
use them to rename an event, person, or gift, to modify senders/receivers
of gifts after they have been added, or to delete gifts.
== Running the specs
=== Prerequisites to run the specs
* rake
* ruby-style
* hpricot
* mongrel
=== Setup
Create the db and run the migration:
createdb giftsmas_test
sequel -m /path/to/giftsmas/migrate postgres:///giftsmas_test
== Running the specs
The specs are run with rake:
rake # Unit tests
rake integration # Integration tests
The integration specs test the full stack, setting up a web server, having
a net/http web client access the web server, and making sure that it is
displaying information correctly and updating the database correctly.
== Todo
* Secure session support (currently, uses sinatra's default session support,
which is not secure).
* Better visual design? (Any volunteers?)
* More descriptive error messages for when you do something like try to
create a gift or event with a 0 length name.
== License
Giftsmas is released under the MIT License. See the LICENSE file for details.
== Author
Jeremy Evans <code@jeremyevans.net>
) is private.
