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.