source: branches/unified_backend/README_DEVELOPERS.txt @ 84

Last change on this file since 84 was 84, checked in by yermol, 15 years ago

_ddt() trace system now writes to a popup window resulting in much faster execution.
_ddt() messages now identifiy file, line and source of trace message.
_ddt() popup window has "add hr" link
ddtpreprop.php script added to patch in file and line numbers.
full_example-body.html and simple_example.html bugfix to not double-call xinha-init.
simple_example.html now only loads a single Xinha instance.

File size: 6.6 KB
Line 
12005-04-15
2                   
3              Xinha Unified Backend Branch
4                    Development Info
5
6by: Yermo Lamers of DTLink Software
7http://www.formvista.com
8
9----------------------------------------------------------
10             Configure.php
11----------------------------------------------------------
12
13To avoid hard coding paths, I've hacked together a small
14Configure.php system which will generate various scripts
15and set directory permissions based on conf files in ./conf.
16
17Configure.php must be called from the command line using the
18full path to command line PHP. This script must be run first
19before any other development scripts can be run.
20
21----------------------------------------------------------
22             Dev Environment Scripts
23----------------------------------------------------------
24
25These scripts assume the availability command line PHP and Perl.
26
27These script have not been tested under Windows. If there is sufficient
28interest, I can make them portable to Windows.
29
30The devutil scripts are located on ./devutils and they include:
31
32svn_commit.php
33
34  preprocessor to "svn commit" command that updates the
35  popups/about.html file so that it always includes the current
36  revision info.
37
38  Requires command line "svn" command to be in $PATH
39
40buildruntime.php: - not done
41
42  generates a "runtime" version of xinha_ub with all comments
43  and debug trace messages stripped out. It also does
44  in-line text replacement for some specific tags.
45
46ddtpreproc.php
47
48  Javascript does not seem to have a version of PHP's
49  __LINE__ and __FILE__ constants so there is no clean way of
50  including file and line numbers in ddt trace messages; at least
51  none that I've been able to find. This script preprocesses the
52  javascript source files to patch in file and line numbers to
53  every _ddt() call.
54
55  If you are working on the source files and add or delete lines just
56  rerun the ddtpreproc.php script from the xinha_ub root directory. It
57  will recurse through all the .js files in the directory tree.
58
59makedocs.pl
60
61  Calls JSDoc with some arguments to generate the class documentation
62  from the source javascript files. Requires Perl, JSDoc and PHPDoc
63  to run.
64 
65  NOTE: Under RedHat 9, JSDoc will cause perl to dump core when running
66  on htmlarea.js. Upgrading Perl to 5.8.6(from source) fixed the
67  problem for me).
68
69IMPORTANT:
70
71      DO NOT FIELD THESE SCRIPTS ON A LIVE SITE.
72
73I have added "deny from all" .htaccess files and each scripts
74checks it's environment in an attempt to avoid being run from
75a webserver.
76
77If you are not running Apache or aren't permitted to do overrides
78in .htaccess, you may want to move the ./devutils directory
79somewhere outside of DOCUMENT_ROOT.
80
81----------------------------------------------------------
82             Code Re-Org
83----------------------------------------------------------
84
85In an attempt to make the codebase more manageable I've
86reorganized htmlarea.js to group related items together.
87
88The file is now broken into five sections:
89
901. Initial Setup
912. HTMLArea.Config Class
923. HTMLArea class methods
934. HTMLArea Class
945. Misc Support overrides and functions
95
96----------------------------------------------------------
97               JSDoc and PHPDoc.
98----------------------------------------------------------
99
100I found a perl script that implements a JavaDoc style system
101for JavaScript. See http://jsdoc.sourceforge.net/.
102
103JSDoc is very sensitive to the order of tags in the headers.
104If you try to add doc headers and they are not showing up
105correctly compare with the test.js file distributed with JSDoc.
106
107JSDoc seems to lack the ability to link to the actual source
108code definition of a given class or method.
109
110I've added JSDoc headers to just about everything I've touched.
111
112For the PHP scripts that I touch, I'm adding PHPDoc headers.
113
114There is a ./utils/makedocs.pl shell script.
115
116----------------------------------------------------------
117             Debugging Trace Messages
118----------------------------------------------------------
119
120To further make my life easier and come up to speed, I've added
121trace messages to virtually every method using a contributed version
122of my DDT debug-trace-message-to-popup window class.
123
124You will need to turn off any popup blockers in order to see the debugging
125trace messages.
126
127These messages can be turned on and off on a per-class basis using the ddtOn() method.
128(See examples/simple_example.html)
129
130What's nice is you can quickly get a feel for the order in which things happen
131and which methods are invoked for what events.
132
133The concept is to do development on the trace enabled version of the code and then
134generate a stripped "runtime" version using the provided ./utils/make_runtime.sh
135script. make_runtime strips all debugging code out of the .js files. It also removes
136almost all comments to reduce file size. I am envisioning having two distributions
137of Xinha .. a development version with all debugging intact and a runtime version
138that has been stripped. (this has served me extremely well in formVista development)
139
140----------------------------------------------------------
141                      Coding Style
142----------------------------------------------------------
143
144The original coding style guidelines included in the code were:
145
146---------------------------------------------------
147 Developers - Xinha main branch Coding Style by Gogo:
148
149    For the sake of not committing needlessly conflicting changes,
150
151   - New code to be indented with 2 spaces ("soft tab").
152   - New code preferably uses BSD-Style Bracing
153     if(foo)
154     {
155        bar();
156     }
157
158   Don't change brace styles unless you're working on the non BSD-Style
159    area (so we don't get spurious changes in line numbering).
160
161   Don't change indentation unless you're working on the badly indented
162    area (so we don't get spurious changes of large blocks of code).
163
164   Jedit is the recommended editor, a comment of this format should be
165   included in the top 10 lines of the file (see the embedded edit mode)
166---------------------------------------------------
167
168Unfortunately, given the endless nested "using dynamic function
169definitions as method arguments" the BSD bracing style makes the code
170impossible to read, IHMO.
171
172To make my life easier I've gone through and changed the style to:
173
174if (foo)
175  {
176  bar();
177  }
178
179So if you have a function definition as an argument as in:
180
181class.method( "foo",
182  function()
183    {
184    return bar;
185    });
186
187Which to my eye is alot easier to follow and less error prone.
188
189I tried Jedit. I can't stand Java apps and the editor is simply too
190slow. I use CRISP which unfortunately has some serious issues with
191tab to space conversions.
Note: See TracBrowser for help on using the repository browser.