AreaEdit

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.



AreaEdit

Documentation generated by JSDoc on Sat Dec 31 14:56:56 2005