Common errors in rich applications

Let's review some common errors in rich applications:

1. Missing files / resources
2. Missing updates
   
3. CSS Class conflict
4. Data related problems
   
1. Incorrect data
2. Server errors make the data dirty
3. UTF with BOM files
5. Cache results don't let you see the results
   
6. Incorrect JS
   

1. Missing files / resources

One of the most common issues we find in applications is that developers forget to download or deploy some files, CSS files, support images, etc..

Images

This mistakes are subtle and sometimes hard to notice as some browsers simply don't show anything, unfortunately other browser will show a massive X in place of the missing image.

CSS

You will normally notice you are missing a CSS file because the screen looks weird (layout), or the font colors, backgrounds have changed

JS

Javascript errors are caused many times by not loaded JS files.

Debugging

You can easily find which files are missing using firebug,

1. Open firebug
2. Go to Net tab
3. Select All, or the specific type you suspect
4. All missing files are written in red
   
1. You can mouse over them to see the complete path of the file and then verify if the resource exist on server or not
2. You can click the + symbol, to check the requesting Headers, the Response header and the HTML

Paths are correct, resources still missing

In some environments, resources will keep failing to download, this is specially true when you load a lot of files. Tequila offers some strategies to prevent this problem. To enable them: file minimization, joining and monitored downloading, you simply:

1. Open includes/config.php (server side)
2. Find the js_includes configuration section (package it's included in core)
3. Modify these lines to enable:

$js_safeloading = true;
$js_blocktillcomplete = true;
$js_retry = 3;
$js_cachedir = 'temp';

This will minimize, join all JS files, cache results for faster execution, monitor downloading, retry up to $js_retry times and optionally ($js_blocktillcomplete) Block the screen use until the files are loaded successfully.

* Notice. Minimization require all your JS files to be very well done (at least all closing brackets and ending semicolons). Tequila uses a standard minimization library and there are many tools online to check your library is valid, try this very strict validator JSLINT

2. Missing updates

Another common reason of involuntary bug induction is incorrect application updating, as files and resources are split across the application it's quite common that partial updates are made. i.e. Template files are not updated, or JS or CSS or...

Solution

Use a file comparison tool, or use mercurial to upgrade your application.

3. CSS Class conflict

CSS is awesome, it allow many levels of definition that allow precise change of look and layout, unfortunately some times CSS definitions can crash. i.e. A YUI component / JS component define the look of

and so your application does. The final result is a mix of both definitions.

Debugging

1. Find out the source of the conflict
1. Right click on the conflicting element
2. Inspect element
3. Verify on the left panel you are on the right HTML tag
4. Check the list of styles on the right panel, to see which one is defining the tag
1. Each entry also mentions the file and line number
   

Solution

Once you have identified the conflicting resources you can:

1. Decide to remove one of them (this removal can be specific to one page, i.e. a complex one-screen)
   
2. Modify one of the CSS to be more specific
1. You can use CSS syntaxis to affect just the children of one node, i.e. #mainlayer div
   
2. You can modify the HTML to apply an specific class to the affected element
   
3. You can add a class to parent to differentiate, (i.e. HTML:
   CSS: .special_case div )

4. Data related problems

Modern applications transmit a lot of data using ajax, this data is hard to debug as it's normally not visible, so the 1st step is to make data visible.

Viewing exchanged data

1. Open firebug using the icon on the right bottom corner
   
2. Click on console
1. You will see a list of all AJAX calls
2. Open them by clicking on the + icon
3. Params tab: You will be able to see the information sent by JS
   
4. Headers tab: You can see the headers sent by server
5. Response tab: You can view here the reply from server

Common problems

Based on this data you can start moving towards a solution, some common problems you can find are

1. Server errors make the data dirty
2. Incorrect data
3. UTF with BOM files

1. Server errors

This is the easiest error to debug, simply inspect the "response tab" like a normal web page and work over the PHP in server to clean up all the errors.

* If you are sending all parameters using GET (querystring). You can also right click on the Console entry and select Open in New Tab

This will allow you to inspect data in detail, you can switch server modes from XML to cd, to get rid of the headers and be able to read the complete errors. (Simply replace rrt=xml -> rrt=nh or cd; read RRT section on Tequila manuals for more info on Requested Response Types)

2. Incorrect data

Incorrect data might point to a logic problem in the server code, use your normal debugging techniques to solve this issue.

Another possible problem is that server and client versions are out of sync. Verify which data is correct before starting modifications. Then work on the server or JS files as necessary.

3. UTF with BOM files

Sometimes you will discover everything is correct, data is perfect, JS is in place and still you keep getting errors from your ajax callback function (this happens specially with XML data).

There's a subtle bug with files saved as UTF with BOM, the problem is that when they are included, PHP immediately start the output making impossible to set the correct XML headers.

Solution

Open every file included in the task with Notepad++ or another editor that support this setting and re save them WITHOUT BOM (optionally you can enable output cache but this is only recommended for testing, cache code is commented in index.php file)

5. Cache results don't let you see the results

This is a common issue, sometimes you own browser cache keeps showing images, css or data from previous calls. You can clear the cache or install the "web developer" plug in mentioned above, simply:

Click on Disable button > Disable Cache.

This will allow you to have a clean environment all the time.

Server cache

We have found on some online servers that PHP pages are cached and the changes made on the PHP are not reflected, try adding some extra info, an extra echo or some visual element that let you know your code is being executed. You might even be connected to the wrong server :)

If required, duplicate the file you are testing, and use this copy for debugging / developing. Update the real file after results are satisfactory, normally the server will start using the updated version after some hours.

6. Incorrect JS

Once you have determined that the server is sending the right responses and all resources are loaded, it's time to move debugging to the client side, You can work on this debugging in many ways.

Echo, echo echo.

Using the exact same technique as in PHP, you can use alert() at some places to inspect execution values.

debug.js

Tequila includes a very basic library to inspect values at running time, you must include it at server side to be able to use it on client, a couple of useful functions are:

function showobj(myObj, title, complete)

function showScript (content, safehtml, title)

Firebug!

And your best friend again: line by line debugging. Before you get crazy following each line, you should inspect your code in an external editor and determine the function you think might be the problem, i.e. the callback function, in ajax

To start debugging in firebug

1. Open firebug (icon on bottom right side of the screen)
2. Click on script tab
3. Under script you will find 2 selectors, the 2d one indicates the name of the library being displayed
4. Open this selector and select the library you want to debug
5. Move the left pane to the line of code you want to inspect
6. Add a breakpoint by clicking on the left hand side of the numbers, a red spot will appear
7. Keep the window open
8. Trigger in the normal window the action you want to inspect
9. Execution will stop in the breakpoint you added, you can then
1. Control execution advance using the icons on top of the code, right side
2. Watch the value of all variables including objects on the right pane
3. You can also add custom watches on the right pane

Useful links on debugging:

* http://www.ibm.com/developerworks/library/os-debug/
* http://www.phpfreaks.com/tutorial/debugging-a-beginners-guide
* http://www.php-debugger.com/dbg/installation.php
* http://xdebug.org/




Good luck and happy debugging!
Find php framework and more useful information about RAD workflow open source.