NAME
Symphero::Web - web rendering part of Symphero E-Commerce suite
SYNOPSIS
None, see the description below and individual manpages.
DESCRIPTION
Symphero::Web is a part of Symphero open source e-commerce
suite. It can also be used as a general purpose web templating
system that allows you to create arbitrary complex web pages and
process them in rather optimal way.
Most interesting features of Symphero::Web are:
* Perl code is not mixed with templates. Templates can be normal
HTML files if no processing is required.
* Site can replace or modify standard Symphero::Web objects if
required by overriding or extending their methods. You do
not need to re-implement entire object to make a site
specific change.
* Site can create any extension objects or embed third-party
extensions as well.
* One server can serve arbitrary number of Symphero::Web sites
each with however extended functionality without creating
any conflicts.
* There are standard objects that support e-commerce functionality
that is enough to implement amazon-style e-commerce sites
relatively easy. That includes credit card authorization,
strong cryptography, users database, products database,
orders database, shipping tracking and so on.
* Works with CGI or mod_perl (mod_perl is recommended for
production grade sites).
* If used in mod_perl mode improves performance by using caching
of configuration, parsed templates, database handlers and so
on.
INSTALLATION
Install it in a usual way, just say:
perl Makefile.PL
make
make test
make install
Saying "install Symphero::Web" from CPAN shell is a good way
too.
When you run "perl Makefile.PL" you will be asked for
Symphero::Web home directory. Feel free to point it somewhere
inside your home directory if you do not feel like modifying
/usr/local/symphero (suggested default). This is a directory
where symphero.pl CGI and mod_perl handler would be placed along
with default site and default templates. That means that entire
path to that directory should be world-readable (or at least
web-server readable).
*NOTE:* On FreeBSD 4.x (or probably with just some older version
of MakeMaker) there is a problem with installing to
/usr/local/symphero - somehow MakeMaker translates it to
$(PREFIX)/symphero and PREFIX is /usr. I do not yet have a
solution for that other then installing it somewhere outside
/usr/local.
FIRST-TIME RUNNING AND TESTING
After you installed Symphero::Web you can try it in web
environment. Configure your Apache server so that it would
execute (from now on I assume that Symphero::Web was installed
into /usr/local/symphero) /usr/local/symphero/cgi-
bin/symphero.pl when someone types URL like
http://company.com/cgi-bin/symphero.pl. Here is an example of
virtual host configuration for that (or you can simply move or
sym-link symphero.pl to your existing cgi-bin directory if you
have one):
ServerName test.company.com
ServerAlias test.company.com
ScriptAlias /cgi-bin/ /usr/local/symphero/cgi-bin/
After you configure and re-start your web-server point your
browser at http://test.company.com/cgi-bin/symphero.pl/docsite/
-- you should be able to see "docsite" content. To see simplest
possible site that does not even have its own templates go to
http://test.company.com/cgi-bin/symphero.pl/emptysite/
You do not have to use that "/cgi-bin/sitename/" garbage, it was
only here to demonstrate the idea. In normal circumstances you
would want to use Apache "rewrite" module to map everything or
almost everything to be processed by symphero.pl. Here is an
example:
ServerName test.company.com
ServerAlias test.company.com
ScriptAlias /cgi-bin/ /usr/local/symphero/cgi-bin/
RewriteEngine on
RewriteRule ^/images/(.*)$ \
/usr/local/symphero/projects/docsite/images/$1 \
[L]
RewriteRule ^/(.*)$ \
/usr/local/symphero/cgi-bin/symphero.pl/docsite/$1 \
[L]
That leaves everything in /images/ to be processed by web server
in a usual way and maps everything else to symphero.pl. Try
going to just http://test.company.com/ now and see the
difference.
And finally, here is an example of mod_perl configuration.
Please replace ScriptAlias with the following:
Options +ExecCGI
SetHandler perl-script
PerlHandler Apache::Registry
PerlSendHeader Off
I'm currently working on pure Apache mod_perl handler that will be
faster then using Apache::Registry and would not require mod_rewrite to
rewrite paths. Keep tuned.
SITE DEVELOPMENT
Here is a couple of steps to start development of a new site:
1 Choose a name for your site. It have to start with a lowercase
letter and may contain letters, digits and underscore sign.
Let's assume you've chosen "mysite" as a name.
2 Create sub-directory in /usr/local/symphero/projects with the
name of your site (/usr/local/symphero/projects/mysite in
our case). This directory is home directory of your site.
Everything else below is relative to that directory.
3 Create subdirectory named 'modules'. Place configuration file
called 'Config.pm' inside of it. There are two requirements
for that file:
* It have to be in the specific namespace --
Symphero::Objects::mysite::Config, where mysite is your
site name.
* It have to be based on "Symphero::SiteConfig" object.
* It have to define "init" method that will initialize site
configuration. In mod_perl environment that method will
be called only once when the site is initialized first
time. That means that init() is a good place to open
connection to a database and it is recommended to do
that as most of Symphero modules require database
connection to work properly.
Here is an example of configuration module Config.pm for
"mysite" site:
# Configuration for mysite
package Symphero::Objects::mysite::Config;
use strict;
use vars qw(@ISA);
use Symphero::SiteConfig;
use DBI;
use DBD::mysql;
##
# Inheritance
#
use vars qw(@ISA);
@ISA=qw(Symphero::SiteConfig);
##
# Site configuration values. A lot of stuff can be stored
# here for different modules.
#
my %data=
( base_url => "http://test.company.com"
, base_url_secure => "http://test.company.com"
);
##
# Initializing configuration object for our site.
#
sub init
{ my $self=shift;
##
# Putting initialization data into configuration.
#
$self->fill(\%data);
##
# Initializing database
#
$self->dbconnect(db_dsn => 'DBI:mysql:mysite'
,db_user => 'mysite'
,db_pass => 'SuperPassword'
);
}
##
# That's it
#
1;
4 At that time you should already be able to see your new site in
your browser. Just point it to http://test.company.com/cgi-
bin/symphero.pl/mysite/
But in order to do something useful you need to create two
more directories: "objects" and "templates".
"Objects" will contain your site-specific extensions for
system objects and your new objects.
"Templates" will contain your site templates.
Nothing else is used by symphero.pl and usually you would
also create directories like "images" or "static"; put your
site to CVS version control or make some kind of
installation tools for it. It is all up to you.
This is it. You should probably start from playing with "foocom"
example e-commerce site before creating your new site.
CORE CODE DEVELOPMENT
If you plan to make changes to the Symphero::Web code (which is
not recommended unless you participate in official development)
please read devsite/README for instructions.
AUTHOR
Brave New Worlds, Andrew Maltsev . Creating of
Symphero::Web would not be possible without valuable comments
and ideas from everybody on our team and especially from Bil
Drury, Marcos Alves, Brian Despain and Jason Shupe. Thank you
guys!
SEE ALSO
Recommended reading: the symphero.pl manpage, the
Symphero::Categories manpage, the Symphero::Objects manpage, the
Symphero::OrdersDB manpage, the Symphero::ProductsDB manpage,
the Symphero::SiteConfig manpage, the Symphero::Templates
manpage, the Symphero::UsersDB manpage, the Symphero::Data
manpage.