=head1 Name

YOTE

=head1 Summary

Yote is a platform for creating web based applications by bridging
client side javascript with server side, automatically persistent perl
objects. Yote provides javascript objects with methods that map to
their server side counterparts.

See http://fenowyn.com/yote for more information.

=head1 Quickstart for OSX / Linux

In the following directions, $SITE_ROOT is the document root of your
web site and $YOTE_ROOT is the directory where the Yote Build.PL file
resides.

It's as easy as...

=over 4

=item 1. Ensure you have a web server that will serve CGIs

=item 2. Install stuff and start the server

    $ ./install '/path/to/your/web/root' '/path/to/cgi-bin'

=item 3. Write your own code (e.g. "hello world" app, website code, etc)

=back

(Note that the yote_server is automatically started in the background
in step 2.  Be sure to kill this when you're done with it, or they
will tend to pile up.)

=head1 Requirements

=over 4 

=item * perl version 5.10

=item * A webserver that can run perl cgi files

=item * jquery (provided with this distribution, or from http://docs.jquery.com/Downloading_jQuery)

=item * Some sort of server-side storage (MySQL or a writable file)

=back

=head1 Install Yote

    $ perl Build.PL
    $ ./Build
    $ ./Build test
    $ ./Build install

=head1 Verify / install the requirements

Following is how to verify that you have each of the requirements and,
if not, to get it.

=over 4

=item * perl version 5.10

To verify if you have this:

       $ perl -v

If your version is too low, look at using perlbrew to upgrade:

       http://search.cpan.org/~gugod/App-perlbrew-0.39/bin/perlbrew

(From the perlbrew docs:)

       $ curl -kL http://install.perlbrew.pl | bash
       $ ~/perl5/perlbrew/bin/perlbrew install 5.14.2  # Current version as of 2012-01-20
       $ ~/perl5/perlbrew/bin/perlbrew use 5.14.2
       $ perl -v  # Should now tell you 5.14.2

This installs the perlbrew executable, the perl-5.14.2 executable, and
all core Perl modules into ~/perl5/perlbrew/.  It then sets the
current shell to use the new version.

You may also want to use cpanm (or another CPAN shell) to install
additional modules for the new perl version.

=item * Storage

Yote needs to store data server side.  This can be in a MySQL
database or a file (which will become a SQLite database).  Other
options, including MongoDB, are in the works -- patches welcome!

If you want MySQL storage, verify / install as follows:


OSX has MySQL installed by default.  Verify that it's running by
doing: 

       $ mysql -u root

(NOTE: For simplicity, the directions in this README connect to MySQL
as 'root'.  This will work and it makes these directions easier, but
in general practice you should connect via a user with lower
permissions.)


Many Linux distributions come with MySQL.  If it is not installed and
running by default, install it as per
http://dev.mysql.com/doc/refman/5.5/en/installing.html  (v5.5.x is
latest as of 2012-01-20).


Once MySQL is running, create a database for Yote to use and
initialize it as follows:

       $ echo 'create database yote;' | mysql -u root
       $ script/init_datastore.pl 

!!!
@@DKSNOTE:  init_datastore.pl is not included in the current version
of Yote
!!!

=item * A webserver that can run perl cgi files

OSX has Apache installed by default.  To verify it is running and
allow it to run CGIs, do the following:

       System Preferences > Sharing > Web Sharing 
     
Ensure that the checkbox is checked; if so, the web server is up.


By default, CGIs are served from /Library/WebServer/CGI-Executables/
(hereinafter '$CGI_BIN')

By default, content is served from ~/Sites/ (hereinafter '$SITE_ROOT')


On Linux, @@TODO

=item * yote.cgi

    $ cp cgi/yote.cgi $CGI_BIN/
    $ chmod 755 $CGI_BIN/yote.cgi

=item * jquery

On OSX or Linux:

    $ mkdir -p $SITE_ROOT/js
    $ cp $YOTE_ROOT/javascript/* $SITE_ROOT/js

=item * put the Yote::WebAppServer module in your path

On OSX / Linux:

    $ export PERL5LIB=$YOTE_ROOT/lib:$PERL5LIB

=item * modify the start_server.pl file

!!!
@@DKSNOTE:  Can't find anything matching this name -- missing
dependency?
!!!

=back

=head1 Using Yote

=head2 Start the Web App Server

Starting the Web App Server from the command line:

       $ script/yote_server

This starts the server on the default port (8008), using SQLiteIO, and
writing to file ~/.yote/SQLite.yote.db.

   
Starting the Web App Server from a package:

       use Yote::WebAppServer;

       my $server = new Yote::WebAppServer();

       $server->start_server( port => 8008,
                  datastore  => 'Yote::SQLiteIO',
                  sqlitefile => 'yote.database' );



=head2 Coding with Yote

=head3 Client Side

       <script src="./js/jquery-latest.js"></script>
       <script src="./js/jquery.dumper.js"></script>
       <script src="./js/jquery.base64.min.js"></script>
       <script src="./js/json2.js"></script>
       <script src="./js/yote.js"></script>
       <script>
           var hello_app = $.gServ.get_app( 'Yote::Hello' );
           var result = hello_app.hello({ name:"fred" } );
           var counter = hello_app.get_counter();
       </script>

=head3 Server Side

    package Yote::Hello;

    use strict;
    use Yote::Obj;
    use base 'Yote::AppRoot';

    sub init {
        my $self = shift;
        my $counter = $self->get_counter( new Yote::Obj() );
    }

    sub hello {
        my( $self, $data, $acct ) = @_;
        my $name = $data->{name};
        my $counter = $self->get_counter();
        $counter->set_count( $counter->get_count() + 1 );
        return "hello there '$name'. I have said hello ". $counter->get_count() . " times.";
    }

    1;

=cut
