Documentation

Contents

• Introduction
• Installation
• Getting Started
• Methods
• Uninstall UserQ
• Contributing

Introduction

What is UserQ

UserQ is a user-queue engine. Tell it how many items (i.e. tickets to sell) you've got and we'll magically create a queue - allowing people to reserve a place and then complete their transaction in a certain time limit (but only much quicker).

An example of a website using a UserQ-like plugin is Ticketmaster.

Why we built UserQ

We think a utility like UserQ massively helps with engagement rates and user experience. We use it so you don't see a ticket form if you aren't guaranteed a ticket. Nothing good enough to serve that purpose exists so we built UserQ.

UserQ is lightweight and very reliable. In fact, it is already used on production through the StudentHack website with over 50% of ticket reservations powered by UserQ converting into a paid ticket sale. We love it and we think you will too.

---

Installation

There are three ways you can get UserQ on your application. The first two (stable versions) are recommended as they are production ready.

Install as a gem (Stable)

$ gem install userq
$ rails generate userq:install

Install using Bundler (Stable)

In your Gemfile, add

gem "userq"

Then run the following

$ bundle install
$ rails generate userq:install

Install from source (Development)

You want bleeding-edge. Go wild.

$ git clone https://github.com/studenthack/userq.git

---

Getting Started

Nothing better than a few code examples to get you started.

Queues

A single Queue consists of many entries. Most only need to use a single UserQ queue.

Creating a single queue

single_queue = UserQ::Queue.new(capacity: 10)

Or - Creating multiple queues

premium_queue = UserQ::Queue.new(context: 'premium', capacity: 10)
standard_queue = UserQ::Queue.new(context: 'standard', capacity: 50)

Check queue status

single_queue = UserQ::Queue.new(capacity: 10)

if single_queue.enter_into_queue?
	entry_id = single_queue.enter.code
	# now we can deal with entries
else
	# refresh this page every n seconds
	# the code below tells them how long their waiting time is
	# puts single_queue.avg_wait_time => "Less than a minute remaining"
end

Entries

This acts for people who are successfully given a place in the queue (i.e. shown the ticket purchase form in the ticket queue).

Get an entry

entry = UserQ::Entry.new(entry_id)

Get an entry (from a particular context)

entry = UserQ::Entry.new(entry_id)

if entry.valid_context?("premium")
	throw "You are not from the premium queue" 
end

Extend when an entry expires

entry = UserQ::Entry.new(entry_id)
entry.expires # => 180
entry.extend(10) # => 190
# entry.shorten(30) # => 160
# entry.expired? # => false
# entry.alive? # => true

Other cool stuff

Store custom data in entry

single_queue = UserQ::Queue.new(capacity: 10)

custom_data = { "first_name" => "Bob", "last_name" => "Smith" }
entry = single_queue.enter(custom_data)

# Get first name
first_name = entry.data["first_name"]

Disable queue auto-clean

single_queue = UserQ::Queue.new(capacity: 10, auto_clean: false)

Reset Queue

single_queue = UserQ::Queue.new(capacity: 10)
single_queue.reset

---

Methods

Queues

UserQ::Queue

	# Create new Queue
	new(constraints)
	
	# Update constraints
	constraints(constraints)  # => { constraints }
	constraint(constraints)   # => { constraints }
	
	# Queue status
	enter_into_queue?  # => true/false
	empty?             # => true/false
	
	# Waiting time
	nearest_entry()  # => 180
	avg_wait_time()  # => "approximately 2 minutes"
	
	# Create entry in queue
	enter()
	enter(custom_data)
	
	# Manage queue
	empty_queue()  # => true
	reset()        # => true

UserQ::Entry

	# New entry
	new(entry_id)
	
	# Verify the context
	valid_context?(context)
	
	# Entry status 
	expired?  # => true/false
	alive?    # => true/false
	expires   # => integer of seconds left
	alive     # => integer of seconds entry has been alive
	
	# Immediately expire entry (but not delete)
	expire  # => true
	
	# Alter entry
	extend(seconds)   # => integer of seconds left
	shorten(seconds)  # => integer of seconds left
	
	# Expire and delete entry
	remove    # => true
	removed?  # => true/false
	
	# Get custom data (if applicable)
	data  # => object of custom data

---

Uninstall UserQ

Revoke the UserQ migration:
$ rake db:rollback

Remove everything UserQ:
$ rails destroy userq:install

---

Contributing

Directly clone the repository (or fork it and clone your fork):

$ git clone https://github.com/studenthack/userq.git

Do some awesome stuff. To test simply run

$ rake test

We love pull requests! Make sure you write a test for your contribution.