=head1 NAME

YAPCOM - Yet Another Perl COnference Manager

=head1 DESCRIPTION

Software to manage conferences. Especially Perl Conferences.

=head1 UPGRADE

After the "make test" of the INSTALLATION process
see the bin/upgrade.pl file.

1) create file called db/db_closed
2) run the appropriate bin/upgrade_.... file
3) remove the db/db_closed file


=head1 INSTALLATION

    tar xzf Yapcom-x.xx.tar.gz
    cd Yapcom-x.xx/
    perl Build.PL
    ./Build
    ./Build test

    check the path of perl in cgi/yapcom


- perl bin/install.pl

- In the virtual host in the apache configuration file write something like this:


Configuration used on 2006.08.06: Still need to be further simplified

    <VirtualHost 127.0.0.1:80>
        ServerName  yapcom.local
        DirectoryIndex index.html
        DocumentRoot                           /home/gabor/work/yapcom/somewhere_else

        RedirectMatch     ^/(\w[^/]+)$                 http://yapcom.local/$1/
        ScriptAliasMatch  ^/(\w[^/]+)/$                /home/gabor/work/yapcom/cgi/yapcom
        ScriptAliasMatch  ^/(\w[^/]+)/[\w-]*.html$     /home/gabor/work/yapcom/cgi/yapcom
        Alias             /2006/html                   /home/gabor/work/yapcom/html
        Alias             /osdc2007/html               /home/gabor/work/yapcom/html
        Alias             /conference/html             /home/gabor/work/yapcom/html
    </VirtualHost>


Older configurations:

    DocumentRoot                           /home/gabor/work/yapcom/somewhere_else

    RedirectMatch     ^/conference$                 http://yapcom/conference/
    ScriptAliasMatch  ^/conference/$                /home/gabor/work/yapcom/cgi/yapcom
    ScriptAliasMatch  ^/conference/[\w-]*.html$     /home/gabor/work/yapcom/cgi/yapcom
    Alias             /conference/html              /home/gabor/work/yapcom/html


ScriptAlias   /virtual_path_to_application/  /path/to/installation/cgi/
Alias /docs /path/to/installation/docs
Alias /files /path/to/installation/files
Alias /html /path/to/installation/html

<Directory /path/to/installation/cgi>
    Options FollowSymLinks
    AllowOverride None
</Directory>
<Directory /path/to/installation/db>
        Deny from all
</Directory>
<Directory /path/to/installation/lib>
        Deny from all
</Directory>


=head1 TEMPLATES

You can change any of the templates in the templates directory.
The best way to do this is to create a directory next to the templates 
directory.

Copy any templates you want to change from templates into this new
directory and change them. 
Add a 'templates_dirs' entry to the conference configuration 
(via the site_admin interface)

Any templates you do not change will be taken from the default templates 
directory.


=head1 DEVELOPMENT

Check out the 'trunk' from the Subversion repository

    perl Build.PL      (install prerequisites)
    ./Build
    ./Build test

Install Apache (or your favorite web server) and configure it
as described above.

See the L</TODO> list below



=head1 CHANGES

=over 4

=item next  2006.08...

    Add logging via CGI::Application::Plugin::LogDispatch
    Remove the need for external configuration file, fetch configuration from database
    Add set of pages for site_admin that should work out of the box on any system


=item 0.13 2005.12...

	- remove the html_path and other unnecessary entries
	- remove skins_dir
	- enable multiple directories in templates_dirs
	- enable closing the web site
	- add list of speakers 
	- Added keywords table so for each talk people can fill in some coma list of words
	  The list of keywords is free text but we will also supply the users a way to see all
	  the currently used keywords
	Add "admin" and "editor" to person table rename the one in the configuration to be 
	  "root" for now, "root" can do anything, "editor" can approve/reject and edit talks of
	  other people. "admin" will have the same rights as the site_admins in the configuration
	  file but from now on I don't need to change the configuration file in order to
	  add a new admin or remove an old one.
	Add "disabled" to person - administrator should be able to set a person as disabled.
	  I think we need this as some people will subscribe just for their own
	  fun and taint our database.

	Start using the ISEditor and Disabled flags
	Add ADMIN/EDITOR/DISABLED flags to the admin list of users
	Let the administrator set these flags (0/1)
	Make sure disabled user cannot login and is not shown in the list of users

	Make EDITOR accounts be able to accept/reject talks, see info about speakers





=item 0.12 2004.

	- replace Makefile.PL by Build.PL
	- start using 3.32 of CGI::Application - don't need to catch warnings any more, we'll be able to test
		for warnings
	- remove the cgi_path and html_path and similar unnecessary variables
	- change templates for YAPC::Israel::2005



=item 0.11  ????.??.??

	- probably there were a number of changes but noone had time to write them down

=item 0.10  2003.12.03

    - show more information about the registered people
    - After anadministrator logs in s/he gets back a regular MyYAPC page without the extra
      link. Only after pressing the 'Personal Inoramtion' link (login.html) do these links
      show up.
    - In I think related issue, if regular user tries to access the proposal.html page
      then she gets  login. One se logs in she gets a Timeline error even though the URL
      in the navigation bar seem to be correct.
    - Improve the interface of the administrators: Show all the proposals

      2003.12.09
    - Added fax, cell and hide to database. Existing databases will need to add these fields
      Updated code and templates to support these fields.

      To update database:

	echo '.dump' | sqlite yapc.db > out
        vi out [ add fields to tables matching db.sql, and to all rows in correct location ]
        my yapc.db yapc.db.bak; sqlite yapc.db < out

      You do not need to stop/restart the web server.


=item 0.09  2003.11.27

    - create XML compilant HTML pages
    - enable logged in users to change their proposals 

=item 0.08_03  2003.11.26

    - Enable the use of a local configuration file.
    - fix minor issues

=item 0.08_01  2003.11.26

    - form (for logged in user) to change the personal information registerd 


=item 0.08  2003.11.25

    - refactoring: using Class::DBI more in the way it should be used
    - refactoring: moving run_mode dispatching, cleaning up the run_modes and authentication 
    - eliminate the 'run' field and base all the actions (run_mode) on the name of the file.

=item 0.07_02 2003.11.24

    - further refactoring the tests
    - add pages to get back lost password and get validation code again
        if e-mail was not yet validated.
    - make list of proposal lengths configurable and add 180 min too
    - make list of languages configurable
    - create admin interface to list all the people with all their properties.
    - interface for the users to change password

=item 0.07_01 2003.11.15

    - send e-mail on every registration to administrator
    - start adding tests for changing user info
    - refactoring the tests a bit

=item 0.07    2003.11.14

    - cookie will expire only after 1d (insted of 1h)


=item 0.06_05 2003.11.14

    - recreating the test file that was lost earlier.

=item 0.06_04 2003.11.14

    - add missing files to the MANIFEST file
    - add lots of tests for the new features
    - logged in users will be able to submit proposals

    - one of the test file were lost due to lack of connetction to the cvs respository
      and a bad 'rm' command on my side.

=item 0.06_03 2003.11.13

    - replaced form submission methods to be POST methods
    - add logout mechanism


=item 0.06_02 2003.11.13

    Partial release, not installed

    - add login mechanism
    - logged in users will be able to access the proposal.html page 

    
=item 0.06_01 2003.11.12

    Partial release, not installed.

    - in 0.06 some of the tests failed on the target system because they
      took the template directory from the YAPC::Config file which was pointing
      to the development directory on the dev machine.
      fix in t/lib/YAPC/Test.pm :
      use Cwd;
      $YAPC::Config::templates_dir = cwd . "/templates";

      fixed in 0.07

    - in 0.06 the bin/setup.pl should also chmod a+w the db directory and the database file
      fixed in 0.07

    - Fix some of the pages as suggested by Offer Kaye

    - improve the installation and upgrade method
    - on the form mark the field which are required
    - make the phone field required
    - search.cpan link did not have the PAUSEID after it.
    - random string generator should give characters from bigger range
    - list only ppl who have validated registration.
    - show statistcs about registrants (how many have registered/authenticated etc.)
    - on the list_people page make sure url without http:// will get it automatically


=item 0.06 2003.11.11

     add the web interface to the database functions, 
     add registration form
     add sending e-mail after registration (use Mail::Sendmail)
     check all fields if they really exist,
     check that e-mail is a reasonable address [\w\d_+=@.]   [@]

     add more fields to the registration form
     added more tests to the existing system


=item 0.05 2003.11.10

     add the CGI::Application framework to the existing 'static' site.

=item 0.04 2003.11.09

     add bin/install.pl script that will do the installation process
        later this script will be changed so it will be able to also
        upgrade by skipping local files.

=item 0.03 2003.11.09

     intermediate release - I don't know why did I make this.


=item 0.02 2003.11.07

     add dependency list to make file
     add basic test script
     add -T to the yapc.pl cript
     add download directory and link to it from the navigator page

     add the separate tree of data manegement but no web interface for it yet.
     This version will probably not be released

=item 0.01 2003.11.03

     original release with script to handle the templates of the simple web site. 

=back

=head1 TODO   (not necessarily in order of importance)

=over 4

=item Allow management of several conferences

Up till now yapcom needed a separate installation 
(and thus user registration, etc) for each conference.
I would like to keep the users from OSDC::Israel::2006
and let them login and say they would like to participate
in OSDC::Israel::2007 too.

Currently working on the site_admin tools.

See L</Database Layout>




=item Add more test, check coverage, clean code

make code pass Perl::Critic (see t/99-critic.t)

=item Create levels of administrators

=item Interface for administrators to change configuration

    Started to work on the web interface for this but discontinued for now. 
    See "configuration" run mode and configuration.tmpl 

=item Move all configuration information into database

See L</DESIGN> L</Roles, Administration>

=item Add categories (and streams ?)


=back


=head1 DESIGN

=head2 Configuration

In the current version we just unzip the distribution 
(or during development we work off the checked out version)
This allows us to use a configurqation file relative to the 
executable.

Even when we allow installation as a CPAN module or just anywhere
in the filesystem we would like to have a basic configuration
file relative to the executable or to let people provide the
path to the central config file in the executable.

The basic installation should create the database with a default
account for site administrators. From that point every configuration
can be made via web browser.

Start with one user who is the site_admin with default username/password
When logged in with default values prompt to change them and then logout.

When site_admin logs in, let her add new sites.



=head2 Database Layout

Will be moved to the schema db/db.sql once it seems to be good.

=over 4

=item List of conferences

    ID
    NAME

=item Conference URIs

    Conference ID
    URIs  (a conference will be recognized by the URI it was accessed
          so any page that is under either of these 
          
          www.osdc.org.il/2006   
          osdc.org.il/2006
          
          will be mapped to OSDC2006

          www.osdc.org.il/2007
          osdc.org.il/2007

          will be mapped to OSDC2007
          
=item People

    Probably is_admin should be moved to a separate table as we have more roles now

    Somehow list for each Person what role she has in each one of the conferences
    (And if she is a site admin)
    The all kinds of other issues for each person/conferenc pair (if she participated
    all the accounting stuff)


=back


=head2 Roles, Administration

=over 4

=item Site Admin

    Can add new "confrences" or disable existing ones
    These people are not connected to any specific conference
    Set other user as Conference Administrator
    Set other user as Site Admin

=item Conference Administrator

    Each conference has its own admistrator(s)
    Set other users for all the roles (except site admin)

    Disable registered users
    (There are a few registrations that are obviously bogus.
    I don't want to send them e-mail every time.)

=item Content managers

    (For now I think we can let all the content managers work
    with every proposal, no need for separate managers of Streams)
    
    List all proposals
    Accept / Reject proposals.

=item Accounting

    See and update the accounting information about a person
    (how much and when paid, invoice status, etc.)


=item Who should do these?

    Decide on schedule of a talk
    Allow the display the schedule to the general public
 
    Prepare and send a personalized e-mail to a group of people.
        (include name, title of proposals, etc.)
        Grouping:
            1) Everyone in the system
            2) Everyone in this conference
            3) Those who sumitted a proposal.
            4) Accepted speakers.
            5) Accepted speaker but have not sent paper yet.
            6) People who have already paid
            7) People who have not yet paid
            8) everyone including disabled users (?)

    Open / Close the interface to confirm talk.
        (I am not sure why did I want this)

    Capability to lock a submission - so they cannot be changed
       after they were accepted.

    Paper pre-processor. 
    (Take the submitted paper and try to create the relevant part 
    of the book from it and return error code if the file was not
    well formatted).

=head2 Categories and Streams

    Administrator(?) should be able to create list of categories
    A person submitting a proposal will be able to select 1 or more 
    categories for his/her talk. Categories are Perl, MySQL, etc...


    Streams: The person who organizes the schedule should be able to
    create streams and put each talk in one (?) stream.
    Business, C/C++, Databases, Education, Java, Linux/Unix,
    PHP, Perl, Python, Security, Web - XML/HTML/Javascript

    There is some overlap betwen the categorization and the stream so
    I am not sure we need two separate systems.

=back





=head1 OLD TODO 

(things will be moved up to the real TODO step by step.





When sending e-mail escape the characters in the e-mail address (e.g. the 
otherwise valid + character)


	Add table for payments
		date
		type (check, credit card, cash, wire transfer)
		amount
		who - user from the database or maybe not registered yet?

	Form to send e-mail to (all/acked/not acked) participants
	form to send e-mail to all confirmed speakers




	Define the time of the days of the conference
	TABLE days: YYYY MM DD StartHH StartMM EndHH EndMM
	
	Define Rooms: TABLE Rooms: name, size, comment

	Users can select a day for the visit (the "daypass" is enaled)

	Show schedule should be a flag if we want to show them to the general public
	or only the editors.

	Schedule: 
	   Each talk has a starting date YYYY MM DD HH MM (and a length)
           Each talk has a room



	Remove hard coded strings from the code.
- remove most(?) of the default values from Config.pm and where they show up
- remove any Perl specific entries (e.g. PAUSE id)
- levels? for now we can have separate categories for the different levels
  "beginner-perl" or "intro-perl", "perl"


- When the administrator accepts a talk let him press another key and by that
  send an e-mail to the speaker that the talk was accepted.


- handle error gracefully when there is no database created yet 
  (or if it was accidentally created corrupted) and give nice error message on HTML

- enable central templates directory and several (probably language specific) 
  customized templets directory.
 


	- Upgrade underlying modules (CGI::Application and stuff has made some 
		progress so we should also use the new stuff)


Urgent
    - Add some "privacy guidlines" statement, i.e. which of the entered info (if
      any) will be shared with the world. (this is text only)

    - improve error messages on the web site
    - give error message on validation form if something went wrong
    - Shall we use Error.pm for exception handling ?
    - Shall we use some Form Validator module ?
         WWW::Form, CGI::Formmagick , else ?


    - Improve the installation process.
    - in the installation process change the content of the configuration file.
      including the installation directory. (or should it be a PREFIX ?)


Intermediate
    - allow registrant to be anonymous (not to show in the public interface, but
      only if they don't give presentations)
    - ask for mobile phone number as well.


Later
    - on the list_people page show stat of how many people have paid already.

    - enable logged in user to delete their proposal(s)

    - separate the code (with simple templates) and the templates needed for
      YAPC::Israel::2004. Put the former in  the distribution, move the
      latter to manual change and upload.
      This will also bear the advantage that we don't have to deal with the
      question, where to put the image files and the css files as the simple
      template version will not have any.
     
    - user should be able to delete his account ?? I am not sure

    - user should be able to change e-mail address but the new 
      e-mail address should be unique and should be validate before it takes effect.
      

    - indicate on the navigation bar who is logged in

    - change the directory tree after the installation so the data files, cgi scripts 
      and library files will not be in the reachable path.


    - Improve the use of a local configuration file based on Timesink of Richard
      http://unixbeard.net/svn/richardc/timesink/lib/Timesink/Config.pm

    - Implement the timeout of the logins

    - Make the code platform independent
        (replacing Mail::Sendmail with MIME::Lite maybe ?)

    - Make sure the code works with mod_perl


????
    - testing the various e-mail sending routines

    - write tests that test the real forms with a real web server infront of them.


In the far future 
    - Add way to update the news without uploading new files
    - Add discussion board
    - Add Wiki

=head1 BUGS

=over 4

=item *

  use YAPC::Organizer crashes if used if there is no database
  it can be seen when running the cgi/yapc.pl script
  actually I think non of the pages will respond

=item *

  When running the tests sometimes I stop them in the middle by Ctrl-C.
  In such cases the database usually becomes corrupted.
 
  I get an error message like this when I try to run the tests again:
 
  Ima::DBI connect('t/test.db','',...) failed: database disk image is
  malformed
 
 
  How can we make sure that this will not happen in the real system ?
  How can we write a test that will cause the above problem (even if that
  test has to run 10 times to have good chances to one corruption)
  so we can see when our script is good enough ?

=item *

  there are more bugs listed in the TODO list.

=back


=head1 MORE DESIGN

The primary objective of this software is to manage *our* conference(s)
but I'd be glad if it was used in other conferences too.
So the order of importance when deciding on design and implementation
is the following:

It should be used in....
- YAPC::Israel::2004
- YAPC::Israel
- YAPC
- Any Perl conference.
- Any conference.


=head2 User Interface

   Double opt-in registration (confirm e-mail address)
   Manage information about oneself.
    (but make sure s/he cannot delete himself or part of
      the important information after registration. E.g. at least
      we need to have the valid e-mail address)

   Details:
    (Actually this should be configurable so other conferences
       could also use it)
     Username
     First name
     Last name
     Title (Mr/Ms/...)
     E-mail address
     Personal URL
     City
     (State)
     Country (list)
     A full address for billing purposes.


     Bio
     Upload picture

     Perl specific
        PAUSE/CPAN id
        Monger Group (list)
        PerlMonks id
        use Perl.org name

   Tool to submit proposals on the web interface.
   Tool to submit papers on the web interface
   Tool to Modify te proposal/paper? Till when ?
   Confirm presentation (after it was accepted).

   A GANT like tool for milestones and progress.

   Accounting?


=head2 Public Interface
    
    List all registered users
      (Group them according to country, pm group, whatever else)
    List of accepted speakers
    List of accepted talks, including their

    List of proposals before accepting them (?)


=head2 Implementation Requirements

    Using templates to make it customizable.
    Hebrew and other language enabled.
    Simple intsallation as CGI
    Compatible with mod_perl
    Database independent backend.


=head2 Features

    Lightweight database using SQLite
    Other, heavier SQL servers are supposed to work but were not tested (yet)

    Language support ? Unicode ?


=head1 Payment and Credit Card Processing

=head2 Automatic way

Interface to an automatic payment gateway.
We should provide easy intergration with CC processing companies like:

http://www.2checkout.com/
or
http://www.clickbank.net/

We should implement integration with the CC processor of The Perl Foundation.

As it is very inconvenient for people in other countries to pay in USD or EURO we have to find a CC processing company 
that will let us display prices in any currency and will be able to send the collected money in that currency without
charging for 2 conversions.


=head2 Manual way 

Some people will not want to pay by CC over the Internet.
They might pay in cash or by check.
We should prepare an interface so the admin will be able to
mark who and when paid manually.

Some companies have a separate person for paying such fees
and it is not done by the registrant. We should create some facility to handle this case as well.

Manual way (for the admin to update payment information)
 Reason: Some companies will have another person,
          not the registrant who arranges the payment,
          we should create some facility for this as well.
          Some people will want to pay cash. We should prepare
          an interface for this.


=head1 THANKS

Many thanks to the Siesta project. 
While not related a large part of the code outline was copied from there.

Thanks for the help of 
Richard Clamp and
Shlomi Fish
Yuval Yaari



=head1 COPYRIGHT

(c) 2003-2006 Gabor Szabo <gabor@pti.co.il>
http://www.pti.co.il/

Licensed under the same terms as Perl itself.
No warranty whatsoever.


=cut