update documentation

README.md

@@ -3,7 +3,7 @@ EventMan(ager)
 
 Your friendly manager of attendees at an event.
 
-EventMan(ager) will help you handle your list of attendees at an event, managing the list of registered persons and marking persons as present.
+EventMan(ager) will help you handle your list of attendees at an event, managing the list of tickets and marking persons as present.
 
 Main features:
 - an admin (in the future: anyone) can create and manage new events
@@ -11,12 +11,12 @@ Main features:
 - 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
+- easy way to add a new ticket, if it's already known from a previous event or if it's a completely new ticket
 - 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)
+- multiple workstations are kept in sync (i.e.: marking a person as an attendee is shown in every workstation currently viewing the list of tickets of an event)
 
 See the *screenshots* directory for some images.
 
@@ -60,17 +60,42 @@ Open browser and navigate to: http://localhost:5242/
 
 If you store SSL key and certificate in the *ssl* directory (default names: eventman\_key.pem and eventman\_cert.pem), HTTPS will be used: https://localhost:5242/
 
-Authentication
+
+Basic workflow
 ==============
 
-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.
+So, you've just installed it and you have the server running.  Let's create an event:
+- login with the **admin** user (default password: **eventman**)
+- click "Add an event"
+- edit basic information about the event and save it
+- in the second panel ("Registration form"), edit the form that will be presented to the persons that want to join your event:
+  - first, define how many rows the form will have
+  - then define how many columns will be in each rows
+  - now edit every form field
+  - give a name to the form (not really meaningful) and save it
+
+Now persons can start joining your event:
+- click on "Join this event" in the list of events
+- compile the form and submit it
+- the user will have to keep the provided link, if they want to edit their information later
+- from this, a person can also mark a ticket as "cancelled" (not counted in the list of tickets), or they can enable it again
+- if the person was a registered user, it's possible to see the list of own tickets in the personal page
+
+As an administrator, you can now go to the list of tickets of the event:
+- from there, once the event has started, you can mark persons as attendees
+- it's also possible to quickly add a new ticket or delete an existing one (the ticket is effectively deleted, it's not the same as the cancelled action)
 
-The default administrator username and password are **admin** and **eventman**. If you want to force authentication, run the daemon with --authentication=on
+Some notes about the event registration form:
+- fields name are important (case is not considered). You can use whatever you want, but "name", "surname" and "email" are internally used to show the tickets list, so please add at least one of them
+- please notice that the "Email" field type has a very silly regular expression and will create a lot of problems: please use "Text input" and names the field "Email"
 
-Demo database
-=============
 
-In the *data/dumps/eventman\_test\_db.tar.gz* you can find a sample db with over 1000 fake persons and a couple of events to play with. Decompress it and use *mongorestore* to import it.
+Authentication
+==============
+
+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 (you usually don't), run the daemon with --authentication=on
 
 
 License and copyright

angular_app/js/app.js

@@ -172,7 +172,7 @@ eventManApp.config(['$stateProvider', '$urlRouterProvider',
                 templateUrl: 'user-main.html'
             })
             .state('user.edit', {
-                url: '/edit/:id',
+                url: ':id/edit',
                 templateUrl: 'user-edit.html',
                 controller: 'UsersCtrl'
             })

docs/DEVELOPMENT.md

@@ -1,7 +1,7 @@
 Development
 ===========
 
-As of June 2016, EventMan(ager) is under heavy refactoring. For a list of main changes that will be introduced, see https://github.com/raspibo/eventman/issues
+As of July 2016, EventMan(ager) is under heavy refactoring. For a list of main changes that will be introduced, see https://github.com/raspibo/eventman/issues
 
 Every contribution, in form of code or ideas, is welcome.
 
@@ -13,9 +13,9 @@ Definitions
 - **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
+- **ticket**: an entry in the list of persons registered at an event (one ticket, one registered person)
 - **user**: a logged in user of the EventMan(ager) web interface (not the same as "person")
-- **trigger**: an action that will run the execution of some scripts
+- **trigger**: an action that will cause the execution of some scripts
 
 
 Paths
@@ -33,12 +33,10 @@ These are the paths you see in the browser (AngularJS does client-side routing:
 - /#/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
+- /#/users - the list of users
+- /#/user/:user\_id/edit - edit an existing user (contains the list of events the user registered for)
 - /#/import/persons - form used to import persons in bulk
-- /#/login - login form
+- /#/login - login and new user forms
 - /logout - when visited, the user is logged out
 
 
@@ -52,37 +50,24 @@ The paths used to communicate with the Tornado web server:
 - /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
-- /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
+- /events/:event\_id/tickets GET  - return the complete list of tickets of the event
+- /events/:event\_id/tickets POST - add a new ticket to this event
+- /events/:event\_id/tickets/:ticket\_id GET    - return a ticket (e.g.: name, surname, ticket ID, ...)
+- /events/:event\_id/tickets/:ticket\_id PUT    - update a ticket (e.g.: if the ticket attended)
+- /events/:event\_id/tickets/:ticket\_id DELETE - remove the entry from the list of registered tickets
+- /users GET  - list of users
+- /users POST - create a new user
 - /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
+- /settings GET - settings to customize the GUI (logo, extra columns for events and tickets lists)
+- /info GET - information about the current user
+- /ebcsvpersons POST - csv file upload to import persons
+- /login POST - log a user in
+- /logout GET - 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, 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.
-
-Beware that most probably the /persons and /events/:event\_id/persons paths will be removed from a future version of EventMan(mager) in an attempt to rationalize how we handle data.
+Also, remember that most of the paths can take query parameters that will be used as a filter, like GET /events/:event\_id/tickets?name=Mario
 
 
 Permissions
@@ -106,24 +91,24 @@ 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\_ticket\_in\_event**: executed every time a ticket 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\_ticket\_in\_event and attends will receive these information:
 - via *environment*:
   - NAME
   - SURNAME
   - EMAIL
   - COMPANY
   - JOB
-  - PERSON\_ID
+  - TICKET\_ID
   - EVENT\_ID
   - EVENT\_TITLE
   - SEQ
   - 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
+  - dictionary **old** with the old data of the ticket
+  - dictionary **new** with the new data of the ticket
   - dictionary **event** with the event information
   - boolean **merged**, true if the data was updated
 
@@ -133,14 +118,12 @@ In the **data/triggers-available** there is an example of script: **echo.py**.
 Database layout
 ===============
 
-Information are stored in MongoDB.  Whenever possible, object are converted into integer, native ObjectId and datetime.
+Information are stored in MongoDB.  Whenever possible, object are converted into native ObjectId.
 
 events collection
 -----------------
 
-Stores information about events and persons registered for a given event.
-
-Please notice that information about a person registered for a given event is solely taken from the event.persons entry, and not to the relative entry in the persons collection. This may change in the future (to integrate missing information), but in general it is correct that, editing (or deleting) a person, older information about the partecipation to an event is not changed.
+Stores information about events and tickets.
 
 Main field:
 
@@ -149,29 +132,24 @@ Main field:
 - begin-time
 - end-date
 - end-time
-- persons - a list of information about registered persons (each entry is a ticket)
-  - persons.$.\_id
-  - persons.$.person\_id
-  - persons.$.attended
-  - persons.$.name
-  - persons.$.surname
-  - persons.$.email
-  - persons.$.company
-  - persons.$.job
-  - persons.$.ebqrcode
-  - persons.$.seq
-  - persons.$.seq\_hex
-
-
-persons collection
-------------------
-
-Basic information about a person:
-- persons.name
-- persons.surname
-- persons.email
-- persons.company
-- persons.job
+- summary
+- description
+- where
+- group\_id
+- tickets - a list of information about tickets (each entry is a ticket)
+  - tickets.$.\_id
+  - tickets.$.ticket\_id
+  - tickets.$.attended
+  - tickets.$.name
+  - tickets.$.surname
+  - tickets.$.email
+  - tickets.$.company
+  - tickets.$.job
+  - tickets.$.ebqrcode
+  - tickets.$.seq
+  - tickets.$.seq\_hex
+
+Notice that all the fields used to identiy a person (name, surname, email) depends on how you've edited the event's form.
 
 
 users collection