 |
Doc/AcmeBase_files.pod |
 |
AcmeBase Files
Introduction
This is a description of the AcmeBase files and directories, and how they are organized in their directory tree.
Conventions for writing programs and program dependicies are also listed.
File System
The AcmeBase files are organized into a directory structure that fits into a FHS-compliant file system (http://www.pathname.com/fhs/) and can reside in the default directories that Red Hat Linux 7.2 sets up for the Apache web server .
AcmeBase can be set up with only one instance per computer like Apache, where there is only one web site per computer, or it can be set up with several independent systems each in their own directory tree. I tend to set up my systems to handle multiple systems even though it is best to only execute one system on a computer. It is resource intensive.
Several file locations can be set in the site configuration file
etc/site.conf. Symbolic links can also be used to reference files
located outside the AcmeBase directory tree. For example, www/var/users
can be mapped to /home. That allows users to easily access their AcmeBase
files. I almost always map www/log to a directory located in /var/log so
that all system logs are in a common location. The www/lib/Acme directory
can be mapped to /opt/AcmeBase/lib and can be shared among all sites.
There are the standard CGI programs in www/cgi-bin and configuration files
in www/etc, but the heart of the system are the library modules located
in www/lib/Acme. The modules that actually process the schema files and
builds the AcmeBase database structure are located in www/lib/Acme/Base. The
library modules in www/lib/Local/Acme are those that are most likely to
be customized from site to site.
The AcmeBase system is usually located where the web site directory is located.
The following is a schematic of the directory layout and main files for AcmeBase. Most of the directories are listed but only the files that I think are of interest are listed.
www ---+
|
+--- cgi-bin + (cgi programs for site)
| |
| +--- admin.cgi (system administrators screen)
| |
| +--- console.cgi (main user console screen)
| |
| +--- form.cgi (form processor)
| |
| +--- search.cgi (lookup windows to search the database)
| |
| +--- query.cgi (construct a search from a form)
| |
| +--- pick.cgi (select a record to edit or view)
| |
| +--- list.cgi (process lists of database records)
| |
| +--- report.cgi (list saved reports)
| |
| +--- import.cgi (import data from a spreadsheet)
| |
| +--- calendar.cgi (calendar program)
| |
| +--- customers + (custom routines for customers)
| | |
| | + --- ...
| |
| +--- orders + (custom routines for orders)
| | |
| | + --- ...
| |
| +--- ... (other custom programs)
|
|
+--- bin + (system administration/command line programs)
| |
| + --- clonedb (clone database and make a tarball)
| |
| + --- sendmaillist (send email to list of addresses in var/email_lists)
| |
| + --- perl_startup.pl (startup file for mod_perl)
| |
| + --- ...
|
|
+--- clone + (working directory and custom scripts for cloning the database)
| |
| + --- setupdb (setup file system)
| |
| + --- mkdb (make database tables from schema)
| |
| + --- loaddb (load data into database)
| |
| + --- unloaddb (unload some database tables for loaddb)
|
|
+--- perl + (programs available to mod_perl)
| |
| + --- form.cgi
| |
| + --- ...
|
|
+--- etc + (system configuration files)
| |
| +--- site.conf (system configuration file)
| |
| +--- access.conf (security access file)
| |
| +--- httpd.conf (web site configuration file)
| |
| +--- passwd (site password file)
|
|
+--- lib +
| |
| +--- Acme + (main library of Acme functions)
| | |
| | +--- Base +
| | | |
| | | + --- Schema.pm (primary meta-database structure)
| | | |
| | | + --- Object.pm (object nodes for schema)
| | |
| | |
| | +--- Cache.pm (cache info read from files)
| | |
| | +--- Calendar +
| | | |
| | | + --- DayMenu.pm (build day menus)
| | |
| | |
| | +--- Date.pm (date functions)
| | |
| | +--- Db.pm (database access routines)
| | +--- Db +
| | | |
| | | + --- Record.pm (add record transaction)
| | | |
| | | + --- RecordSet.pm (form's data structure)
| | | |
| | | + --- Interface + (site specific interface)
| | | |
| | | + -- MySQL.pm
| | | |
| | | + -- Postgres.pm
| | |
| | +--- Form.pm
| | +--- Form +
| | | |
| | | + --- Builder.pm
| | | |
| | | + --- Filler.pm
| | | |
| | | + --- Saver.pm
| | |
| | |
| | + --- HTML.pm (for user info/error messages)
| | + --- HTML +
| | | |
| | | + --- SearchControl.pm (controls for searching tables)
| | | |
| | | + --- SectionControl.pm (sections of view screens)
| | | |
| | | + --- HideShow.pm (hide or show window sections)
| | | |
| | | + --- InputArray.pm (input fields for text arrays)
| | | |
| | | + --- Parameters.pm (get parameters from user)
| | | |
| | | + --- NavButtons.pm (window navigation buttons)
| | | |
| | | + --- Tag.pm (parse HTML tags)
| | |
| | |
| | + --- HTTP.pm (HTTP protocols encoding/decoding)
| | |
| | + --- Lister.pm
| | + --- Lister +
| | | |
| | | + --- Filter.pm (filter original list)
| | | |
| | | + --- Selector.pm (selector filter)
| | |
| | + --- Options.pm (save and access user option settings)
| | |
| | + --- Searcher.pm (combine search scripts with SQL)
| | |
| | + --- Security.pm (check user's security settings)
| | + --- Security +
| | | |
| | | + --- Access.pm (parse etc/access.conf)
| | | |
| | | + --- Alert.pm (send alerts to administrator)
| | | |
| | | + --- SQL.pm (clean SQL statements)
| | | |
| | | + --- User.pm (check user's privileges)
| | |
| | |
| | + --- SQL.pm (parse SQL statements)
| | |
| | + --- TextArray.pm (utilities for text arrays)
| |
| |
| +--- Local + (site specific interface/extensions to AcmeBase)
| |
| +--- Common.pm (local site page banners)
| |
| +--- Config.pm (site config using etc/site.conf)
| |
| +--- Format.pm (list format functions)
| |
| +--- ListMenu.pm (local dropdown menus)
| |
| +--- User.pm (user information routines)
| |
| +--- Form +
| |
| + Common.pm (page banners for forms)
| |
| + Extensions.pm (form filler commands)
|
|
+--- html + (document root directory for web site)
| |
| + --- doc + (documentation files)
| | |
| | + --- AcmeBase.pod (schema file instrctions)
| | |
| | + --- AcmeBase_files.pod (file/directory organization)
| | |
| | + --- AcmeBase_forms.pod (form instrctions)
| |
| + --- help + (help files)
| | |
| | + --- search_instructions.htm (how to construct searches)
| | |
| | + --- ...
| |
| + --- images + (pictures)
| | |
| | + local + (site specific pictures for banners)
| | | |
| | | + --- company_banner.gif
| | | |
| | | + --- company_icon.gif
| | | |
| | | + --- company_logo.gif
| | |
| | |
| | + pic_of_day + (pictures for option button on banners)
| | |
| | + --- ... (arbitrary pictures for banners)
| |
| + --- new_forms + (default location where new constructed forms are saved)
| | |
| | + --- ...
| |
| + --- scripts + (common and custom JavaScript files)
| | |
| | + lib + (AcmeBase JavaScript library)
| | |
| | + --- form_events.js (capture keypresses and clicks)
| | |
| | + --- form_save.js (routines to save a form)
| | |
| | + --- form_entry.js (utility functions for form)
| | |
| | + --- list.js (utility functions for lists)
| | |
| | + --- calendar.js (render calendars)
| | |
| | + --- colorwheel.js (choose a color)
| | |
| | + --- control.js (used for HTML/SearchControl.pm)
| | |
| | + --- address.js (parse addresses)
| | |
| | + --- button-bar.js (button bar control functions)
| |
| |
| + --- styles + (CSS style sheets)
| | |
| | + --- admin.css (administration screen styles)
| | |
| | + --- calendar.css (calendar styles)
| | |
| | + --- calendar_full.css (full-screen-calendar styles)
| | |
| | + --- calendar_list.css (calendar-as-list styles)
| | |
| | + --- common.css (styles common to all pages)
| | |
| | + --- console.css (styles for console screen)
| | |
| | + --- form.css (form stylesheet)
| | |
| | + --- form_print.css (added form styles for printing)
| | |
| | + --- list.css (list stylesheet)
| | |
| | + --- list_print.css (added list styles for printing)
| | |
| | + --- message.css (message screen styles)
| | |
| | + --- view.css (view stylesheet)
| | |
| | + --- view_print.css (added view styles for printing)
| |
| |
| + --- sounds + (sound files)
| |
| + --- ...
|
|
+--- log + (log files whose names are specified in configuration files)
| |
| + --- Db.log (database error/transaction log)
| |
| + --- access_log (web site access log
| |
| + --- error_log (database error/transaction log)
| |
| + --- referrer_log (database error/transaction log)
| |
| + --- security_log (copies of security alerts sent to administrator)
| |
| + --- backup_log (log of Postgres dump snapshots for backups)
| |
| + --- vacuumb_log (log of Postgres vacuumb database maintenance)
|
|
+--- schema + (AcmeBase schema source files)
| |
| +--- acme + (pattern/example specification files)
| | |
| | + --- ...
| |
| +--- *Company* + (site specific directory of AcmeBase schema files)
| |
| + --- ... (company schema files)
|
|
+--- templates + (Custom HTML form templates)
| |
| + ...
|
|
+--- var +
|
+--- backup + (database snapshots for Postgres backup)
| |
| + --- ...
|
+--- lists + (database lists saved in list.cgi)
| |
| + --- ...
|
+--- email_lists + (email addresses saved in list.cgi for sending email)
| |
| + --- ...
|
+--- reports + (report specification files)
| |
| + --- customers (customer report files)
| |
| + --- ...
|
+--- users + (user's private files)
|
+ --- *User-Name* + (directory name is user's login name)
| |
| + --- database + (name is set in etc/site.conf)
| |
| + --- .AcmeOptions (user settings)
| |
| + --- lists + (private lists)
| | |
| | + ...
| |
| + --- reports + (private reports)
| |
| + ...
|
+ --- ...
Note: the path to .AcmeOptions must be searchable and the file readable by administrative accounts in order for user options to be used during automated nightly chores (such as callbacks processing).
Programs
CGI programs are located in the cgi-bin directory or in a subdirectory.
The programs located in the bin directory are primarily used for site
administration. The programs are intended to be executed from the
command line are they not CGI programs.
Libraries
Acme libraries are located in the lib/Acme and lib/Local/Acme
directories. The libraries which usually change from site to site are
located in lib/Local/Acme directory.
Using a different database than PostgreSQL will require changes to the
lib/Acme/Db/Site.pm module. Plus there will probably be changes to the
SQL code fragments assembled by the programs as there is so many differences
between the database engines.