Lace Readme
-----------

Copyright (C) 2005-2006 Brett Stimmerman <brettstimmerman@gmail.com>
Redistribution of this file is permitted under the terms of the GPL

Table of Contents
-----------------
0. Disclaimer
1. General Information
2. How does it work?
3. Requirements
4. Installing Lace
5. Upgrading Lace
6. Support
7. Todo
8. Credits


0. Disclaimer
-------------
Lace is experimental.  It is nothing more than several components
haphazardly smashed together and forced to play nice.

Feel free to modify it in any way; but if you do, please send your
changes to brettstimmerman@gmail.com for consideration for next
official release.


1. General Information
----------------------
Lace is a free, lightweight Ajaxian communications engine written
in PHP, Javascript, XHTML and CSS. Lace takes advantage of
XMLHttpRequest if it is present, and degrades gracefully if it is
not.

The latest version of Lace can be found at:

  http://www.socket7.net/lace/

Lace is released under the terms of the GPL.  See the LICENSE file
for more information.


2. How does it work?
--------------------
Lace has two major components: the client engine and the server
engine.

Lace's client engine is written in Javascript and is
completely optional. If enabled, DOM compliant browsers that
support XMLHttpRequest get a great user experience: speedy updates
on the fly with no browser refreshes necessary. Sweet!

Lace's server engine is written in PHP and provides flat-file data
access and a hook for the XMLHttpRequest object, if present. If
XMLHttpRequest is not present for whatever reason, the server
engine handles submissions like a 'traditional' web application so
that Lace remains usable - from nearly any browser.

The client engine is made up of Javascript files found in the
/scripts/ directory.

The server engine is made of PHP libraries found in /lib/; the main
library is lib_lace.php.  The XMLHttpRequest hook is lace.php in
the root folder.


3. Requirements
---------------
Browsers

So far, Lace seems to work just fine with:

  Firefox
  IE5.5+ (including IE7)
  Opera 8
  Safari

IE/Mac and IE5.0/Win work with several limitations: IE/Mac doesn't
support XMLHttpRequest and IE5.0/Win doesn't support the
encodeURIComponent Javascript method, which means that the client
engine won't work properly in either browser. In addition, they
each mangle the CSS a little differently.

At a minimum, Lace should function to some degree in most browsers
with or without Javascript or CSS support.

Servers

Lace was built on top of Apache 1.3.xx and PHP 4.3.10, and runs
fine on Apache 2.x and PHP 5.  Please email me any configurations
it does (or doesn't) seem to work with.

As of 0.1.3, Lace can optionally utilize mod_rewrite to provide
pretty URLs.

Lace requires PHP be compiled with multibyte character support
(--enable-mbstring) in order to support character sets like
Japanse and Chinese.  You can verify your PHP supports this by
looking for the 'mbstring' section of the output of phpinfo().

If you do not have the mbstring extension, Lace might mangle
multibyte characters.


4. Installing Lace
------------------
1. Copy the contents of the /www directory to your web server.

2. chmod 644 (or whatever works best for you) the following
   files and directories:

  /data
  /data/activity.dat
  /data/lace.dat
  /data/log.dat
  /data/logs/

   If you aren't familiar with chmod, you need to set the proper
   permissions on the above files that allow PHP to read and write
   to them.  This can usually be done from within your FTP program.

   Important
   ---------
   Lace can optionally use .htaccess and mod_rewrite to simulate
   dirified URLs.  If Lace will be hosted by a hosting company,
   there should be no problem.  If you are setting Lace up on your
   own personal server, be sure to allow .htaccess files by making
   the proper changes to httpd.conf, if you haven't done so
   already.

3. Open config.php and make sure to set the following at a
   minimum:

    LACE_URL_ABS
    LACE_URL_REL

   Other settings you may want to change are:

    LACE_SITENAME
    LACE_SITE_DESCRIPTION
    LACE_TIMEOUT
    LACE_MAX_TEXT_LENGTH
    LACE_LOGS_DIRIFIED

   Have a look at the rest of the settings, to see what else you
   may want to change.  All settings have a brief description of
   what they are/do.

   If you ever mess up a setting, or need to remember what it was
   originally set to, you can use the config.dist.php file for
   reference.

4. If you're using LACE_LOGS_DIRIFIED, edit .htaccess and change
   RewriteBase to the setting you used for LACE_URL_REL.  In other
   words, RewriteBase should be the relative URL to your Lace
   installation (e.g. /lace/).

5. Lace ships with a pre-configured version of Cal Henderson's
   lib_filter found in /lib/, and it's pretty strict. It only allows
   a, b, code, i, em and strong tags.  You may want to modify the
   default settings to allow for more tags.

6. The layout is mostly customizable, and much of it can be changed
   by modifying /styles/style.css.


5. Upgrading Lace
-----------------
1. Copy the new files from the Lace distribution to your web
   server, taking care not to overwrite any files you may have
   modified (e.g. config.php), and more importantly, the /data/
   directory.

   During these early stages of development, some files may change
   names or directories, or features may change between versions.
   As Lace matures, such changes will become much less frequent.

2. Look for configuration changes in the new config.dist.php.  If
   there are any changes, use your favorite text editor to copy the
   changes to your old config.php by hand.


6. Support
----------
This release has only been tested on my development and 'production' servers.
I cannot guarantee that it will work with your configuration.

Send any questions, comments or fixes to brettstimmerman@gmail.com.


7. Todo
-------
This release of Lace is experimental.  There are many aspects of
the application that need tending to if it is ever going to fly.

Some of Lace's immediate needs might be:

  - Refactor and streamline entire codebase.  It's currently a
    massive hodge-podge with a blatant disregard for any sensible
    order
  - Streamline XHTML and CSS
  - Improve component abstraction
  - Drop certain hard-coded features in favor of a plug-in
    architecture

Completed items:

    - Consider mod_rewrite in place of ForceType for pretty URLs
      (0.1.3)


8. Credits
----------
Lace is originally based on a small portion of Ryan Grove's
PHPSlice, and includes tiny snips of Ryan's other project,
Poseidon.
PHPSlice Copyright (C) 2001 - 2002 Ryan Grove
Poseidon Copyright (C) 2003 - 2005 Ryan Grove
http://wiki.wonko.com/software

Lace uses Cal Henderson's lib_filter library.
Copyright (C) 2001-2004 Cal Henderson
http://code.iamcal.com