source: branches/unified_backend/README_DEVELOPERS.txt

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

Fixed exceptions on closed trace window.
each domain now opens it's own trace window.
updated README files and index.html

File size: 7.4 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
140It's important to note that each domain Xinha is run on will open it's own
141debugging trace window. (for instance, if you are working on two copies on different
142servers they will not be able to share a single debugging window. This is because
143a script in one domain cannot write into a window opened by another domain).
144
145You should be aware that Xinha intecepts some events on reload or page change
146which means that there are debugging messages that are output by the currently
147loaded script on the page when you click reload or change pages. (This took me
148a while to track down). Often times I would close the trace window and then
149do a reload noticing exceptions listed in the javascript console. Took forever
150to figure out these exceptions were not being generated by the new page but
151instead by the old page. See DDT.prototype._ddt() in ddt.js for more insights.
152
153----------------------------------------------------------
154                      Coding Style
155----------------------------------------------------------
156
157The original coding style guidelines included in the code were:
158
159---------------------------------------------------
160 Developers - Xinha main branch Coding Style by Gogo:
161
162    For the sake of not committing needlessly conflicting changes,
163
164   - New code to be indented with 2 spaces ("soft tab").
165   - New code preferably uses BSD-Style Bracing
166     if(foo)
167     {
168        bar();
169     }
170
171   Don't change brace styles unless you're working on the non BSD-Style
172    area (so we don't get spurious changes in line numbering).
173
174   Don't change indentation unless you're working on the badly indented
175    area (so we don't get spurious changes of large blocks of code).
176
177   Jedit is the recommended editor, a comment of this format should be
178   included in the top 10 lines of the file (see the embedded edit mode)
179---------------------------------------------------
180
181Unfortunately, given the endless nested "using dynamic function
182definitions as method arguments" the BSD bracing style makes the code
183impossible to read, IHMO.
184
185To make my life easier I've gone through and changed the style to:
186
187if (foo)
188  {
189  bar();
190  }
191
192So if you have a function definition as an argument as in:
193
194class.method( "foo",
195  function()
196    {
197    return bar;
198    });
199
200Which to my eye is alot easier to follow and less error prone.
201
202I tried Jedit. I can't stand Java apps and the editor is simply too
203slow. I use CRISP which unfortunately has some serious issues with
204tab to space conversions.
Note: See TracBrowser for help on using the repository browser.