README_DEVELOPERS.txt
Summary
No overview generated for 'README_DEVELOPERS.txt'
2005-05-31
AreaEdit - Development Info
by: Yermo Lamers of DTLink, LLC
Copyright: 2005 DTLink, LLC
http://www.formvista.com
----------------------------------------------------------
Configure.php
----------------------------------------------------------
To avoid hard coding paths, I've hacked together a small
Configure.php system which will generate various scripts and
set directory permissions based on conf files in ./conf.
Configure.php must be called from the command line using the
full path to command line PHP. This script must be run first
before any other development scripts can be run.
You only need to run Configure.php if you want to run the
examples or intend to use ImageManager, Linker or SpellChecker
or you want to work on the AreaEdit code itself.
----------------------------------------------------------
Dev Environment Scripts
----------------------------------------------------------
These scripts assume the availability command line PHP and
Perl.
These script have not been tested under Windows. If there is
sufficient interest, I can make them portable to Windows.
The devutil scripts are located on ./devutils and they include:
svn_commit.php
preprocessor to "svn commit" command that updates the
popups/about.html file so that it always includes the current
revision info.
Requires command line "svn" command to be in $PATH
buildruntime.php: - not done
generates a "runtime" version of xinha_ub with all comments
and debug trace messages stripped out. It also does in-line
text replacement for some specific tags.
ddtpreproc.php
Javascript does not seem to have a version of PHP's __LINE__
and __FILE__ constants so there is no clean way of including
file and line numbers in ddt trace messages; at least none
that I've been able to find. This script preprocesses the
javascript source files to patch in file and line numbers to
every _ddt() call.
If you are working on the source files and add or delete
lines just rerun the ddtpreproc.php script from the xinha_ub
root directory. It will recurse through all the .js files in
the directory tree.
makedocs.pl
Calls JSDoc with some arguments to generate the class
documentation from the source javascript files. Requires
Perl, JSDoc and PHPDoc to run.
NOTE: Under RedHat 9, JSDoc will cause perl to dump core when
running on htmlarea.js. Upgrading Perl to 5.8.6(from source)
fixed the problem for me).
IMPORTANT:
DO NOT FIELD THE DEVUTILS SCRIPTS ON A LIVE SITE.
I have added "deny from all" .htaccess files and each scripts
checks it's environment in an attempt to avoid being run from a
webserver. The scripts also attempt to detect whether they are
being run from a webserver and if so will fail.
If you are not running Apache or aren't permitted to do
overrides in .htaccess, you may want to move the ./devutils
directory somewhere outside of DOCUMENT_ROOT.
----------------------------------------------------------
NameSpaces
----------------------------------------------------------
We intend to maintain plugin compatibility (at least for a
while) with HTMLArea and Xinha. As a result, the class names
still use the old htmlarea name (instead of AreaEdit).
----------------------------------------------------------
Code Re-Org
----------------------------------------------------------
In an attempt to make the codebase more manageable I've
reorganized htmlarea.js to group related items together.
The file is now broken into five sections:
1. Initial Setup
2. HTMLArea.Config Class
3. HTMLArea class methods
4. HTMLArea Class
5. Misc Support overrides and functions
----------------------------------------------------------
JSDoc and PHPDoc.
----------------------------------------------------------
I found a perl script that implements a JavaDoc style system
for JavaScript. See http://jsdoc.sourceforge.net/.
JSDoc is very sensitive to the order of tags in the headers. If
you try to add doc headers and they are not showing up
correctly compare with the test.js file distributed with JSDoc.
JSDoc seems to lack the ability to link to the actual source
code definition of a given class or method.
I've added JSDoc headers to just about everything I've touched.
For the PHP scripts that I touch, I'm adding PHPDoc headers.
There is a ./utils/makedocs.pl shell script that generates both
PHP and javascript documentation. You will need to make sure
that PHPDoc and JSDoc are in your PATH before running it.
----------------------------------------------------------
Debugging Trace Messages
----------------------------------------------------------
To make my life managing this codebase easier, I've added trace
messages to virtually every method using a contributed version
of my DDT debug-trace-message-to-popup window class.
You will need to turn off any popup blockers in order to see
the debugging trace messages.
These messages can be turned on and off on a per-class basis
using the ddtOn() method. (See examples/simple_example.php)
What's nice is you can quickly get a feel for the order in
which things happen and which methods are invoked for what
events.
The concept is to do development on the trace enabled version
of the code and then generate a stripped "runtime" version
using the provided ./utils/buildruntime.php script.
buildruntime strips all debugging code out of the .js files. It
also removes almost all comments to reduce file size. I am
envisioning having two distributions of AreaEdit .. a
development version with all debugging intact and a runtime
version that has been stripped. (this has served me extremely
well in formVista development)
It's important to note that each domain AreaEdit is run on will
open it's own debugging trace window. (for instance, if you are
working on two copies on different servers they will not be
able to share a single debugging window. This is because a
script in one domain cannot write into a window opened by
another domain).
You should be aware that AreaEdit intecepts some events on
reload or page change which means that there are debugging
messages that are output by the currently loaded script on the
page when you click reload or change pages. (This took me a
while to track down). Often times I would close the trace
window and then do a reload noticing exceptions listed in the
javascript console. Took forever to figure out these exceptions
were not being generated by the new page but instead by the old
page. See DDT.prototype._ddt() in ddt.js for more insights.
----------------------------------------------------------
Coding Style
----------------------------------------------------------
The original coding style guidelines included in Xinha were:
---------------------------------------------------
Developers - Xinha main branch Coding Style by Gogo:
For the sake of not committing needlessly conflicting changes,
- New code to be indented with 2 spaces ("soft tab").
- New code preferably uses BSD-Style Bracing
if(foo)
{
bar();
}
Don't change brace styles unless you're working on the non BSD-Style
area (so we don't get spurious changes in line numbering).
Don't change indentation unless you're working on the badly indented
area (so we don't get spurious changes of large blocks of code).
Jedit is the recommended editor, a comment of this format should be
included in the top 10 lines of the file (see the embedded edit mode)
---------------------------------------------------
Unfortunately, given the endless nested "using dynamic function
definitions as method arguments" the BSD bracing style makes
the code impossible to read, IHMO.
To make my life easier I've gone through and changed the style to:
if (foo)
{
bar();
}
So if you have a function definition as an argument as in:
class.method( "foo",
function()
{
return bar;
});
Which to my eye is alot easier to follow and less error prone.
The editor I use is called CRISP. To work on the source files
set your tabstops to 2 to make everything come out right. I use
tabs extensively to reduce keystrokes.
Documentation generated by
JSDoc on Sat Dec 31 14:56:56 2005