Location: PHPKode > scripts > Calendar Solution > convissor-calendar_solution-ff69243/include/CalendarSolution/doc/INSTALL.TXT
REQUIREMENTS
------------
* Apache's httpd or Redmine's lighttpd web server.  (You can get it to run
  on other servers by porting the .htaccess and .htpasswd files.  If
  you do, please send them to me so they can be included in
  a future version.)
* Access to one of the following database systems:
  + MySQL
  + PostgreSQL
  + SQLite, version 2 or 3
* PHP 5.2 or later with the extension for the database system being used:
  + mysql
  + mysqli
  + pgsql
  + sqlite
  + sqlite3
* Caching is optional.  If using caching, our default is to use Memcached.
  It is possible to use other cache engines by writing a simple cache
  wrapper class.  Anyway, if using our Memcached based mechanism:
  + Memcached server
  + PHP's memcache PECL extension


NOTE
----
When this document places something between "<" and ">", that
indicates a place holder that you need to replace with the actual
value relevant to your situation.  The "<" and ">" need to be
replaced as well.  For example, you would turn
"<database_admin_user_name>" into "root".


OBTAINING THE PACKAGE
---------------------
There are two options for obtaining this package:
a) Find and download the tar tar ball at
http://www.analysisandsolutions.com/software/download/

b) Or, use Git to obtain the source code directly.  The current
stable branch is 3.  Development happens in master.  The nice
thing about this route is it permits easy integration of any
enhancements we make with the changes you need to make to the
settings and CSS files.
  + git clone git://github.com/convissor/calendar_solution.git
  + cd calendar_solution
  + git checkout --track -b 3 origin/3
  + Edit the configuration files, as discussed below.
  + git commit -a -m 'Local configuration changes.'
  + Any time in the future you want to obtain our latest code, you
    can call "git pull" and our changes will be merged with yours.


INSTALLATION STEPS
------------------
* Create a database if necessary.  Calendar Solution's tables can
be added to an existing database (the table names are prefixed with
"cs_") or put into a new database.  If you do want to create a new
database, here are some rough examples of how to do so.
  + MySQL
    mysql -u <database_admin_user_name> -p

    CREATE DATABASE <database_name> CHARSET utf8 COLLATE utf8_bin;
    GRANT INSERT, SELECT, UPDATE, DELETE
      ON <database_name>.* TO <database_user_name>@localhost
      IDENTIFIED BY '<password>';
    FLUSH PRIVILEGES;
    exit

  + PostgreSQL
    sudo -u postgres psql

    CREATE USER <database_name> PASSWORD '<password>';
    CREATE DATABASE <database_name> WITH ENCODING 'UTF8';
    GRANT CONNECT ON DATABASE <database_name> TO <database_user_name>;
    \q

  + SQLite
    Calendar Solution comes with a pre-created SQLite database that
    is ready to use.  Skip to the "Personalize the system tables"
    step.

* Load the installation SQL script into your database system.
  + MySQL:
    mysql -u <database_admin_user_name> -p <database_name> \
      < include/CalendarSolution/sql/install-3.0-mysql.sql

  + PostgreSQL
    sudo -u postgres psql <database_name> \
      < include/CalendarSolution/sql/install-3.0-postgresql.sql

    sudo -u postgres psql <database_name>

    GRANT INSERT, SELECT, UPDATE, DELETE ON
      cs_status,
      cs_list_link_goes_to,
      cs_power_of_two,
      cs_feature_on_page,
      cs_frequent_event,
      cs_category,
      cs_calendar
      TO <database_user_name>;
    GRANT SELECT, UPDATE ON
      cs_frequent_event_frequent_event_id_seq,
      cs_category_category_id_seq,
      cs_calendar_calendar_id_seq
      TO <database_user_name>;
    \q

* Personalize the system tables, if so desired.
NOTE: the INSERT statements here are ONLY EXAMPLES.

  + Log into the database, if you have not already:
    - MySQL:
      mysql -u <database_admin_user_name> -p <database_name>
    - PostgreSQL:
      sudo -u postgres psql <database_name>
    - SQLite 2
      sqlite include/CalendarSolution/sqlite/calendar_solution.sqlite2
    - SQLite 3
      sqlite3 include/CalendarSolution/sqlite/calendar_solution.sqlite3

  + Exit the database:
    - MySQL:
      exit
    - PostgreSQL:
      \q
    - SQLite:
      .quit

* Adjust permissions on the files.  Rework the examples to suit
the environment you are running in.
  + cd into the "calendar_solution-2-1-1" directory, which is the root
  directory created by extracting our .tar.bz2 file.
  + chown -R root:www-data .
  + find . -type d -exec chmod 750 {} \;
  + find . -type f -exec chmod 640 {} \;
  + chmod 755 include/CalendarSolution/doc/*.sh
  + chmod 760 include/CalendarSolution/sqlite/calendar_solution*

* Edit the "CALENDAR_SOLUTION_DBMS", "CALENDAR_SOLUTION_HTTP_HOST",
and "CALENDAR_SOLUTION_LINK_PATH" settings in
"include/calendar_solution_settings.php".

* This package depends on PHP's autoload functionality and ships with
such a function in "include/calendar_solution_settings.php".  If your
system already has an autoloader, feel free to integrate the concepts
in our autoload function into yours and then comment out our call to
"spl_autoload_register()".

* (If using the default SQLite database that comes with the Calendar
Solution, skip this step.)  Put the database authentication information
into the SQL Solution user class file matching your database system.
The files are in the include/SQLSolution directory:
  + MySQLUser.php  (for PHP's mysql extension)
  + MySQLiUser.php  (for PHP's mysqli extension)
  + PostgreSQLUser.php  (for PostgreSQL)
  + SQLiteUser.php  (for PHP's sqlite extension)
  + SQLite3User.php  (for PHP's sqlite3 extension)

* If you are using SQLite as your database AND you obtained
the source code using Git, the following step is needed to
prevent future updates from corrupting your database:
  + echo "calendar_solution* merge=ours" >> \
    include/CalendarSolution/sqlite/.gitattributes

* Configure the web server to block public access to the Admin directory.
There are many ways to do this; the following is one.

  + In a command line terminal, cd into our "calendar/Admin" directory.

  + Generate a user/password:  htpasswd -m .htpasswd <user_name>

    If you get a "command not found" error, or similar, you will need
    to use the full path to the executable.  On Unix/Linux/BSD systems,
    one can find the path via "locate htpasswd".  On Windows boxes,
    the program is in the "bin" sub-directory where Apache is
    installed, e.g. "C:\Program Files\Apache Group\Apache\bin\htpasswd"

    If you are using Lighttpd, make sure there are no comments in the
    .htpasswd file, otherwise you may not be able to log in
    (http://redmine.lighttpd.net/issues/2223).

  + If using an APACHE HTTPD web server: edit the ".htaccess" file so the
    AuthUserFile setting contains the full path to the .htpasswd file.
    For example: "/var/www/calendar/Admin/.htpasswd".

  + If using a LIGHTTPD web server: edit "/etc/lighttpd/lighttpd.conf"
    (adjust paths as appropriate for your environment):

      server.modules += ( "mod_auth" )
      url.access-deny += ( ".htaccess", ".htpasswd", "/include/" )
      auth.debug = 2
      auth.backend = "htpasswd"
      auth.backend.htpasswd.userfile = "/var/www/calendar/Admin/.htpasswd"
      $HTTP["host"] == "localhost" {
        auth.require = (
          "/calendar/Admin/" => (
            "method" => "basic",
            "realm" => "Calendar Solution Admin",
            "require" => "valid-user"
          )
        )
      }

* Everyone who obtained the source code using Git needs to commit
their changes now:
  + git commit -a -m 'Local configuration changes.'

* Put the "calendar" and "include" directories in a location accessible
by the web server.  This package assumes both of these directories will
be put in the same location.  If they are not, the path used in the
require calendar_solution_settings.php calls in each of the *.php files
in the "calendar" directory and the require List.php in
"calendar/calendar.php" must be adjusted.


CACHING (OPTIONAL)
------------------
* If you want to enable caching, populate the "$GLOBALS['cache_servers']"
array in "include/calendar_solution_settings.php".

If you wish to utilize a different caching engine:
* Write a class that implements the interface found in
  "include/CalendarSolution/Cache.php". See
  "include/CalendarSolution/Cache/Memcache.php" for an example.
* Change the value of the "CALENDAR_SOLUTION_CACHE_CLASS" constant in
  "include/calendar_solution_settings.php".

The following tests are run against databases populated with the data
found in "include/CalendarSolution/sql/benchmark-insert.sql".

------------------------------------------------------------------
Benchmarking Database Extensions (w/o caching) (requests / second)
------------------------------------------------------------------
mysql  mysqli  pgsql  sqlite  sqlite3   file in calendar/benchmark
-----  ------  -----  ------  -------   --------------------------
   24      24     14      24       21   calendar.php
   72      72     24      69       58   title-limit10.php
   71      71     23      68       55   title-limit10-offset20.php
------------------------------------------------------------------

---------------------------------------------------------------
Benchmarking Cache (using mysqli extension) (requests / second)
---------------------------------------------------------------
none  memcache   file in calendar/benchmark
----  --------   --------------------------
1663       n/a   blank.php
  24       105   calendar.php
  72       115   title-limit10.php
  71       114   title-limit10-offset20.php
---------------------------------------------------------------


ADDING EVENTS
-------------
* Point your web browser at your web server and navigate to the
"calendar/Admin" directory.  The web server will produce a prompt
asking for the user name and password you generated in the prior
step.

* You should see a calendar with no events in it.

* Click the "Add Event" link, enter the data for an event
then click the "Add" button at the bottom.

* Click the "Events" link at the top and your event
should show up in the calendar, though the calendar shows only
three months by default, so you may need to navigate ahead
via the "See Later Events" link to get to the right time frame
in the display.

* If at any point you receive the "A Database Problem Occurred"
message, the full error message can be obtained by editing the
"include/SQLSolution/General.php" file.  At the end of the file is a
"debug tool ->" comment.  Move the "echo"... command down one
line so it becomes uncommented, save the file and retry the
request in your web browser.  Once you get the message, make
sure to undo your change to avoid revealing server information
to the public.


DISPLAYING EVENTS
-----------------
This package comes with pre-configured web pages for listing events in
calendar and list formats ("calendar/calendar.php") and displaying full
information about individual events ("calendar/calendar-detail.php").

While it is possible to use those web pages as is, it is also possible
to either put your own layout into those scripts or to copy the relevant
parts of the PHP code into your own web pages.

In addition, the "calendar/" directory includes examples of how to use
the other output formats:
+ example-detailtable.php
+ example-monthtitle.php
+ example-quicktable.php
+ example-title.php
+ example-ul.php

All of the Cascading Style Sheets provided are for demonstration purposes.
Creating and using your own, independent style sheets is encouraged.


WORDPRESS SHORTCODE API (OPTIONAL)
----------------------------------
WordPress sites can easily use the Calendar Solution via our
Shortcode API.  To do so:

* Have one of your wp-content files make a PHP include call to our
"include/wordpress_shortcodes.php" file.

* Use WordPress' "Edit Page" user interface to place the desired
Shortcode into your page's content.  Here is a sample short code:
    [calendar_solution_quicktable limit="3"]

A complete list of Shortcodes and attributes is available in the
"include/wordpress_shortcodes.php" file.
Return current item: Calendar Solution