update docs
This commit is contained in:
Davide Alberani
parent
b7246d5b7a
commit
2e17b7c3ac
2 changed files with 62 additions and 52 deletions
10
README.md
10
README.md
|
|
@ -8,13 +8,15 @@ EventMan will help you handle your list of attendees at an event, managing the l
|
|||
Main features:
|
||||
- an admin (in the future: anyone) can create and manage new events
|
||||
- events can define a registration form with many custom fields
|
||||
- a person can join (or leave) an event, filling the custom forms
|
||||
- a person can join (or leave) an event, submitting the custom forms
|
||||
- no registration is required to join/leave an event
|
||||
- quickly mark a registered person as an attendee
|
||||
- easy way to add a new person, if it's already known from a previous event or if it's a completely new person
|
||||
- can import Eventbrite CSV export files
|
||||
- RESTful interface that can be called by third-party applications (see the https://github.com/raspibo/event_man/ repository for a simple script that checks people in using a barcode/QR-code reader)
|
||||
- ability to run triggers to respond to an event (e.g. when a person is marked as attending to an event)
|
||||
- can run on HTTPS
|
||||
- multiple workstations are kept in sync (i.e.: marking a person as an attendee is shown in every workstation currently viewing the list of persons registered at an event)
|
||||
|
||||
See the *screenshots* directory for some images.
|
||||
|
||||
|
|
@ -51,7 +53,7 @@ Be sure to have a running MongoDB server, locally. If you want to install the de
|
|||
sudo pip install pycups # only needed if you want to print labels
|
||||
git clone https://github.com/raspibo/eventman
|
||||
cd eventman
|
||||
./eventman_server.py --debug
|
||||
./eventman\_server.py --debug
|
||||
|
||||
|
||||
Open browser and navigate to: http://localhost:5242/
|
||||
|
|
@ -61,7 +63,9 @@ If you store SSL key and certificate in the *ssl* directory (default names: even
|
|||
Authentication
|
||||
==============
|
||||
|
||||
By default, authentication is required; default username and password are *admin* and *eventman*. If you want to completely disable authentication, run the daemon with --authentication=off
|
||||
By default, authentication is not required; unregistered and unprivileged users can see and join events, but are unable to edit or handle them. Administrator users can create ed edit events; more information about how permissions are handled can be found in the *docs/DEVELOPMENT.md* file.
|
||||
|
||||
The default administrator username and password are **admin** and **eventman**. If you want to force authentication, run the daemon with --authentication=on
|
||||
|
||||
Demo database
|
||||
=============
|
||||
|
|
|
|||
|
|
@ -2,8 +2,12 @@ Definitions
|
|||
===========
|
||||
|
||||
- **event**: a faire, convention, congress or any other kind of meeting
|
||||
- **registered person**: someone who said it will attend at the event
|
||||
- **person**: everyone hates them
|
||||
- **registered person**: someone who said will attend at the event
|
||||
- **attendee**: a person who actually *show up* (is checked in) at the event
|
||||
- **ticket**: an entry in the list of persons registered at an event
|
||||
- **user**: a logged in user of th Event Man web interface (not the same as "person")
|
||||
- **trigger**: an action that will run the execution of some scripts
|
||||
|
||||
|
||||
Paths
|
||||
|
|
@ -16,14 +20,17 @@ These are the paths you see in the browser (AngularJS does client-side routing:
|
|||
|
||||
- /#/events - the list of events
|
||||
- /#/event/new - edit form to create a new event
|
||||
- /#/event/:event_id - show information about an existing event (contains the list of registered persons)
|
||||
- /#/event/:event_id/edit - edit form to modify an existing event
|
||||
- /#/event/:event\_id/edit - edit form to modify an existing event
|
||||
- /#/event/:event\_id/view - show read-only information about an existing event
|
||||
- /#/event/:event\_id/tickets - show the list of persons registered at the event
|
||||
- /#/event/:event\_id/ticket/new - add a new ticket to an event
|
||||
- /#/event/:event\_id/ticket/:ticket\_id/edit - edit an existing ticket
|
||||
- /#/persons - the list of persons
|
||||
- /#/person/new - edit form to create a new person
|
||||
- /#/person/:person_id - show information about an existing person (contains the list of events the person registered for)
|
||||
- /#/person/:person_id/edit - edit form to modify an existing person
|
||||
- /#/person/:person\_id - show information about an existing person (contains the list of events the person registered for)
|
||||
- /#/person/:person\_id/edit - edit form to modify an existing person
|
||||
- /#/import/persons - form used to import persons in bulk
|
||||
- /login - login form
|
||||
- /#/login - login form
|
||||
- /logout - when visited, the user is logged out
|
||||
|
||||
|
||||
|
|
@ -34,51 +41,68 @@ The paths used to communicate with the Tornado web server:
|
|||
|
||||
- /events GET - return the list of events
|
||||
- /events POST - store a new event
|
||||
- /events/:event_id GET - return information about an existing event
|
||||
- /events/:event_id PUT - update an existing event
|
||||
- /events/:event_id DELETE - delete an existing event
|
||||
- /events/:event\_id GET - return information about an existing event
|
||||
- /events/:event\_id PUT - update an existing event
|
||||
- /events/:event\_id DELETE - delete an existing event
|
||||
- /events/:event\_id/persons GET - return the complete list of persons registered for the event
|
||||
- /events/:event\_id/persons POST - insert a person in the list of registered persons of an event
|
||||
- /events/:event\_id/persons/:person\_id GET - return information about a person related to a given event (e.g.: name, surname, ticket ID, ...)
|
||||
- /events/:event\_id/persons/:person\_id PUT - update the information about a person related to a given event (e.g.: if the person attended)
|
||||
- /events/:event\_id/persons/:person\_id DELETE - remove the entry from the list of registered persons
|
||||
- /events/:event\_id/tickets GET - return the complete list of tickets registered for the event
|
||||
- /events/:event\_id/tickets POST - insert a person in the list of registered tickets of an event
|
||||
- /events/:event\_id/tickets/:ticket\_id GET - return information about a person related to a given event (e.g.: name, surname, ticket ID, ...)
|
||||
- /events/:event\_id/tickets/:ticket\_id PUT - update the information about a person related to a given event (e.g.: if the person attended)
|
||||
- /persons GET - return the list of persons
|
||||
- /persons POST - store a new person
|
||||
- /persons/:person_id GET - return information about an existing person
|
||||
- /persons/:person_id PUT - update an existing person
|
||||
- /persons/:person_id DELETE - delete an existing person
|
||||
- /events/:event_id/persons GET - return the complete list of persons registered for the event
|
||||
- /events/:event_id/persons/:person_id GET - return information about a person related to a given event (e.g.: name, surname, ticket ID, ...)
|
||||
- /events/:event_id/persons/:person_id PUT - update the information about a person related to a given event (e.g.: if the person attended)
|
||||
- /persons/:person_id/events GET - the list of events the person registered for
|
||||
- /persons/:person\_id GET - return information about an existing person
|
||||
- /persons/:person\_id PUT - update an existing person
|
||||
- /persons/:person\_id DELETE - delete an existing person
|
||||
- /persons/:person\_id/events GET - the list of events the person registered for
|
||||
- /ebcsvpersons POST - csv file upload to import persons
|
||||
- /users GET - list of users
|
||||
- /users/:user\_id PUT - update an existing user
|
||||
- /settings - settings to customize the GUI (logo, extra columns for events and persons lists)
|
||||
- /info - information about the current user
|
||||
- /login - login form
|
||||
- /logout - when visited, the user is logged out
|
||||
|
||||
Notice that the above paths are the ones used by the webapp. If you plan to use them from an external application (like the _event\_man_ barcode/qrcode scanner) you better prepend all the path with /v1.0, where 1.0 is the current value of API\_VERSION.
|
||||
The main advantage of doing so is that, for every call, a useful status code and a JSON value is returned (also for /v1.0/login that usually would show you the login page).
|
||||
The main advantage of doing so is that, for every call, a useful status code and a JSON value is returned.
|
||||
|
||||
Also, remember that most of the paths can take query parameters that will be used as a filter, like GET /events/:event\_id/persons?name=Mario
|
||||
|
||||
You have probably noticed that the /events/:event\_id/persons/\* and /events/:event\_id/tickets/\* paths seems to do the same thing. That's mostly true, and if we're talking about the data structure they are indeed the same (i.e.: a GET to /events/:event\_id/tickets/:ticket\_id will return the same {"person": {"name": "Mario", [...]}} structure as a call to /events/:event\_id/persons/:person\_id). The main difference is that the first works on the \_id property of the entry, the other on person\_id. Plus, the input and output are filtered in a different way, for example to prevent a registered person to autonomously set the attendee status or getting the complete list of registered persons.
|
||||
|
||||
|
||||
Permissions
|
||||
===========
|
||||
|
||||
Also, remember that most of the paths can take query parameters that will be used as a filter, like GET /events/:event_id/persons?name=Mario
|
||||
|
||||
|
||||
Triggers
|
||||
========
|
||||
|
||||
Sometimes we have to execute some script in reaction to an event.
|
||||
Sometimes we have to execute one or more scripts in reaction to an action.
|
||||
|
||||
In the **data/triggers** we have a series of directories; scripts inside of them will be executed when the related action was performed on the GUI or calling the controller.
|
||||
|
||||
Available triggers:
|
||||
- **update_person_in_event**: executed every time a person data in a given event is updated.
|
||||
- **update\_person\_in\_event**: executed every time a person data in a given event is updated.
|
||||
- **attends**: executed only when a person is marked as attending an event.
|
||||
|
||||
update_person_in_event and attends will receive these information:
|
||||
update\_person\_in\_event and attends will receive these information:
|
||||
- via *environment*:
|
||||
- NAME
|
||||
- SURNAME
|
||||
- EMAIL
|
||||
- COMPANY
|
||||
- JOB
|
||||
- PERSON_ID
|
||||
- EVENT_ID
|
||||
- EVENT_TITLE
|
||||
- PERSON\_ID
|
||||
- EVENT\_ID
|
||||
- EVENT\_TITLE
|
||||
- SEQ
|
||||
- SEQ_HEX
|
||||
- SEQ\_HEX
|
||||
- via stdin, a dictionary containing:
|
||||
- dictionary **old** with the old data of the person
|
||||
- dictionary **new** with the new data of the person
|
||||
|
|
@ -87,6 +111,7 @@ update_person_in_event and attends will receive these information:
|
|||
|
||||
In the **data/triggers-available** there is an example of script: **echo.py**.
|
||||
|
||||
|
||||
Database layout
|
||||
===============
|
||||
|
||||
|
|
@ -107,8 +132,9 @@ Main field:
|
|||
- begin-time
|
||||
- end-date
|
||||
- end-time
|
||||
- persons - a list of information about registered persons
|
||||
- persons.$.person_id
|
||||
- persons - a list of information about registered persons (each entry is a ticket)
|
||||
- persons.$.\_id
|
||||
- persons.$.person\_id
|
||||
- persons.$.attended
|
||||
- persons.$.name
|
||||
- persons.$.surname
|
||||
|
|
@ -117,7 +143,7 @@ Main field:
|
|||
- persons.$.job
|
||||
- persons.$.ebqrcode
|
||||
- persons.$.seq
|
||||
- persons.$.seq_hex
|
||||
- persons.$.seq\_hex
|
||||
|
||||
|
||||
persons collection
|
||||
|
|
@ -138,7 +164,7 @@ Contains a list of username and associated values, like the password used for au
|
|||
|
||||
To generate the hash, use:
|
||||
import utils
|
||||
print utils.hash_password('MyVerySecretPassword')
|
||||
print utils.hash\_password('MyVerySecretPassword')
|
||||
|
||||
|
||||
Coding style and conventions
|
||||
|
|
@ -150,23 +176,3 @@ I suggest four spaces instead of tabs for all the code: Python (**mandatory**),
|
|||
|
||||
Python code documented following the [Sphinx](http://sphinx-doc.org/) syntax.
|
||||
|
||||
|
||||
TODO
|
||||
====
|
||||
|
||||
Next to be done
|
||||
---------------
|
||||
|
||||
- handle datetimes (on GUI with a calendar and on the backend deserializing ISO 8601 strings)
|
||||
- modal on event/person removal
|
||||
|
||||
Nice to have
|
||||
------------
|
||||
|
||||
- a test suite
|
||||
- notifications for form editing and other actions
|
||||
- authentication for administrators
|
||||
- i18n
|
||||
- settings page
|
||||
- logging and debugging code
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue