Pasting PHP Code into the Manager

Pasting PHP code into the Module Manager or Snippet Editor can be extremely frustrating. Copy/paste your code into a file under /assets/modules/{module-name}/{module-name}.module.php or assets/snippets/{snippet-name}/{snippet-name}.snippet.php.

For modules, delete all PHP source in the Module Manager editor and paste:

<?php
 
require_once($modx->config['base_path'] . "assets/modules/{module-name}/{module-name}.module.php");
 
?>

For snippets, delete all PHP source in the Create/edit Snippet textarea and paste:

<?php
 
require_once($modx->config['base_path'] . "assets/snippets/{snippet-name}/{snippet-name}.snippet.php");
 
?>

• If your snippet fails to display after require-ing the helper file. Try using echo to output the snippet’s response.
• This method allows you to continue using your preferred PHP editor while developing modules and takes two steps out of the testing procedure.

Helper Files

Most of the modules I develop have overlapping functionality. I like to move generic/overlapping functions into an external file and include them in my modules and snippets. This practice helps keep my main module and snippet code tidy. If you prefer an object-oriented approach, you can use classes instead of procedural functions.

As an example, my module ‘user_manager.module.php’ includes a ‘user_manager.inc.php’. This inc.php file is included in the admin area module and front-end snippet.

Database Access

The following code snippet will give you a quick overview of how to access the database from a MODx module:

function getUserTotalPoints($web_user_id)
{
	global $modx;
 
	$web_user_id = $modx->db->escape($web_user_id);
 
	$tp = $modx->db->config['table_prefix'];
 
	$fields = 'SUM(tbl_points.points) AS total';
	$from = $tp . 'web_user_competency_points AS tbl_points';
	$where = 'tbl_points.web_user_id=' . $web_user_id;
 
	$result = $modx->db->getRow($modx->db->select($fields, $from, $where));
 
	return intval($result['total']);
}

• $modx is the document parser.
• $modx->db is the database connection to the primary MODx database.
• $tp is the table prefix for the database (default is ‘modx_’).
• The example above assumes there will only be one row returned. Since the query will never return more than one row, we can use getRow() on a select() in a single line.
• If your result set will return more than one row, use:

  while($row = $modx->db->getRow($result))

Refer to http://wiki.modxcms.com/index.php/API:DBAPI for more information.

Module Sections

A single module may have more than one section or state. I use an ‘opcode’ to keep track of the current module state. For more information visit: http://svn.modxcms.com/docs/display/MODx096/Writing+the+module+code

Installation

1. Close any Macromedia or Adobe applications
2. Download and install the appropriate Extension Manager for your version of Flash and OS from:
   http://www.adobe.com/exchange/em_download/
3. Download and install the ASUnit Extension from:
   http://sourceforge.net/project/showfiles.php?group_id=108947&package_id=208529
4. Open Flash

Verifying the Installation

In Flash, go to the Commands menu and verify the “Create Class” command is available. If the “Create Class” command is not present verify the ASUnit extension is installed and enabled in the Extension Manager. You shouldn’t need to restart your machine.

Getting Started

1. Create a new AS2.0 FLA in an empty directory.
2. Save the FLA to an empty directory. ASUnit will need to create files relative to the FLAs path.
3. Insert the following code on Layer 1, Frame 1

   import AllTests;

   var at:AllTests = new AllTests();

4. Go to the Commands menu, Create Class menu item
   
5. Enter a qualified Class Name
6. Uncheck “Add to Library as MovieClip.”
7. Click OK
8. Go to the Commands menu and select the Build Test Suites command:
   

Potential Problems

• If you don’t enter a namespace when creating a new class ASUnit will output the following error:

  This is easy to fix; just enter “com.Example” in the Class Name text box (highlighted in blue above). All classes must use namespaces.

• If testing the movie does not present you with test case results, go to the Window Menu, Other Panels sub-menu, AsUnit Ui item to show the ASUnit panel.

Recommended Procedures

1. Setup your project so unit testing is performed outside the development area. I usually setup a directory called “unit_testing” and store my tests there. All development is done in the “development.” folder. The testing FLA Publish Settings must include the “development” folder in its search path list; this is usually entered as a relative URL.
   
2. The “Create Class” command creates two files, a className.as and a classNameTest.as. Delete the className.as

I Want To Create Tests For Existing Code

If you’ve decided to add unit testing to your arsenal mid-project try the following:

1. Add a directory in your project to hold the unit tests
2. Create a new AS2.0 FLA in the new directory
3. Go to the File menu, Publish Settings item, Settings… button
4. Add your project’s class path to the Classpath list and close
5. Add the code snippet above

Troubleshooting

If you run into class conflicts check to see if Flash’s global class paths are conflicting with the local Flash paths. To do this in CS3, go to the Edit menu, Preferences item, ActionScript category, ActionScript 2.0 Settings button. In reference to the example above, if your global class paths contain “./classes/” and your testing FLA class paths contain “../flash/classes/” Flash will happily notify you of a conflict.

Resources

• Official ASUnit Homepage: http://www.asserttrue.com/articles/tag/asunit
• Tutorial Part 1: http://www.flashcodersny.org/wordpress/?p=103
• Tutorial Part 1 (in PDF): http://timbeynart.com/docs/ASUnit_Part1.pdf
  
• Tutorial Part 2: http://timbeynart.com/docs/ASUnit_Part2.pdf

10 Ways to Improve Website Credibility

The following list is available here. The external guidelines page also contains descriptions for each method and a link to research in PDF format.

1. Make it easy to verify the accuracy of the information on your site.
2. Show that there’s a real organization behind your site.
3. Highlight the expertise in your organization and in the content and services you provide.
4. Show that honest and trustworthy people stand behind your site.
5. Make it easy to contact you.
6. Design your site so it looks professional (or is appropriate for your purpose).
7. Make your site easy to use — and useful.
8. Update your site’s content often (at least show it’s been reviewed recently).
9. Use restraint with any promotional content (e.g., ads, offers).
10. Avoid errors of all types, no matter how small they seem.

This research is also available in PDF format here.

Usability and Credibility

Many of the methods for improving website Credibility overlap with Usability. I recommend reviewing Jakob Nielson’s article on usability testing at.

User Interfaces and Usability

Site usability can be improved through:

• Attention to detail when designing the user interface:
  http://www.uie.com/articles/subtle_interaction_design/
• Performing usability testing – “The 5-Second Test”:
  http://www.uie.com/articles/five_second_test/

References

• Fogg, B.J. “The Web Credibility Project: Guidelines – Stanford University.” Stanford Guidelines for Web Credibility. Jun 2002. Stanford University. 10 Jul 2008 <link>.
• Nielson, Jakob. “Usability Testing With 5 Users.” useit.com. 19 Mar 2000. 10 Jul 2008 <link>.
• Spool, Jared. “Interaction Design: It’s All About the Subtleties.” User Interface Engineering. 24 Jun 2008. 10 Jul 2008 <link>
• Perfetti, Christine. “5-Second Tests: Measuring Your Site’s Content Pages.” User Interface Engineering. 9 Jun 2005. 10 Jul 2008 <link>.

Irony

At the time of this writing http://www.webcredibility.org/ has no index page. Site visitors are presented with a directory structure. Tisk tisk.

Getting Started with UML

• If you are new to UML diagramming practice with paper or a whiteboard. Starting off with these mediums ensures you are learning one thing at a time. Tools like MS Visio are built to be user friendly but you will learn UML from the way Microsoft interprets UML. Even a fully UML compliant editor (such as Enterprise Architect) will increase your learning curve because every application interprets how you should draw UML differently. Learn UML first, then cool design software.
• Using design tools (like Visio or Enterprise Architect) to brainstorm wastes time; if the problem is not well understood or the solution changes – you must redraw the diagram. Use design tools to communicate “solutions to problems” or “problems”.
• Ask someone that is not a stakeholder in your project to interpret the diagram. Project stakeholders might make assumptions based on pre-existing project knowledge.
• Avoid spending extra time making diagrams UML compliant if they are tacit. I’ve spent hours arguing over a Use Case diagram arrangement – this time can be spent elsewhere. Compliance will improve over time, don’t try to make things perfect the first time.
• Use separate diagrams to describe different areas of a system. Mixing multiple diagram types into one diagram will confuse your audience.

Recommended Reading

• UML 2.0 In a Nutshell (O’Reilly) http://oreilly.com/catalog/9780596007959/
• Learning UML 2.0 (O’Reilly) http://oreilly.com/catalog/9780596009823

UML Style Guidelines

• Avoid curved lines
• Avoid overlapping lines. If lines must intersect use a “line jump” to indicate overlaps
• Elements should have consistent shapes and sizes. This includes decorations like rounded rectangle radius and line thickness
• Diagram elements should have consistent whitespace
• Maintain consistent fonts, colors, and font styles
• Use sans-serif fonts

Style Guideline References

http://www.ibm.com/developerworks/webservices/library/ws-tip-uml/

Refining UML Diagrams Over Time

• Create templates in your favorite design tool to reduce startup time
• Modify your diagrams based on feedback from clients and project managers. This may include items such as:
  • Color coded elements accompanied by a color key
  • Comments next to diagram elements
• Use layers to provide details for different audiences (this is a handy feature of Visio). Details may include:
  • Comments or notes not intended for the client
  • Developer details not relevant to designers
  • User interface notes that don’t pertain to developers

Recommended Software

Microsoft Visio

http://office.microsoft.com/en-us/visio/default.aspx

Enterprise Architect

http://www.sparxsystems.com.au/

UML Software List

http://en.wikipedia.org/wiki/List_of_UML_tools

• Where to find the NaturalDocs executables
• Where to find commenting guidelines
• Setup a sample project workspace
• Automate NaturalDocs with a simple Windows Batch File

Getting Started

1. Download and unpack the latest version of NaturalDocs available at:
   http://www.naturaldocs.org/.
2. Document your code according the NaturalDocs coding guidelines found at:
   
   http://www.naturaldocs.org/documenting.html.
3. Download this Windows Batch File if you wish to automate the process.
4. Create a folder in your project for documentation. Refer to the Project Folder Structure below.
5. Run NaturalDocs.bat directly or customize and run the automation batch file.

Setting Your Project’s Folder Structure

The following is an example project structure with separate development and documentation areas:

Customizing the Windows Batch File for Automation

Save the automation batch file in the /documentation/ directory. The batch file contains the following variables:

• NATURAL_DOCS_PATH: Location of the NaturalDocs executable
• INPUT_PATH: Relative path from the automation batch file to the source files
• OUTPUT_PATH: Relative path from the automation batch file to the desired output directory*
• PROJECT_PATH: Relative path from the automation batch file to the desired project directory*

*Set the output path and the project path to the same directory and leave the project data alone to save time on customizations. I usually have two batch files in the documentation directory. Each batch file generates documentation for a different portion of my code (procedural ActionScript and ActionScript classes).

Using NaturalDocs in a Subversion Workspace

NaturalDocs deletes documentation files if the class source file has been renamed or removed. Committing the documentation directories immediately after running NaturalDocs will eliminate errors in your working copy.

NaturalDocs Command Line Options

Refer to http://naturaldocs.org/running.html for more information. The automation batch file uses HTML output instead of HTML-frames output. Modify the last line of the automation batch file to change the output format.

NaturalDocs uses a ‘Project Root’ command-line parameter for storing project data. The project data contains custom menu arrangements, custom keywords, and custom topics. Project data is generated automatically but may be modified after NaturalDocs has generated documentation.

Potential Problems

Browser detection is not bulletproof since users can change their browser name string, firewalls may prevent browser data from passing through, and software builders change their browser ID formats. Since these are the exceptions and not the rule-it’s worth attempting to customize the page presentation to your visitors’ browser.

Approach

1. Create individual stylesheets for different browsers and browser versions
2. Use PHP to detect the current browser and browser version
3. Load base stylesheets first
4. Load browser-specific styles after the base styles

The order of steps 3 and 4 are critical. We’re trying to overwrite the base styles so they must be included first in the HTML header.

Detecting the Browser Version

At the very least you’ll need to retrieve the browser name. If compatibility requirements are strict you’ll want the version and revision numbers too. Once you’ve chosen a detection script you’re ready to move on.

Instead of retyping source, I will now point you to this site which uses PHP’s get_browser() function. This page has a dedicated author and a history of updates dating back to 1998.

I recommend using get_browser() but if you don’t want to modify your PHP setup you are in luck. There are enough open-source detection scripts on the web to save you the trouble of writing your own. When you find a script be sure to check its release date.

An open-source script will have the same approach as the browser capability approach linked above.

Suggestions

• If you’re aiming for IE and Firefox it’s probably simpler to keep all your files in one ./css/ directory
• Use a folder structure like the one below if you have many browser-specific CSS files.
  

• If you’re switching approaches mid-project be sure to add relative paths to your CSS files!

References

http://www.hudzilla.org/phpbook/read.php/16_5_0

What is a Browser Testing Suite?

A browser testing suite captures screenshots of web pages as they appear in different browsers and different operating systems. Visit this site to see a list of available browser testing suites. I use browsershots because of its price point (free).

Testing Procedures

1. Start with an HTML-based page
2. Create two standards compliant CSS files:
   • css/screen/layout.css
   • css/screen/site.css
3. Include the default layout and site CSS files in the HTML header
4. Test your work with a browser testing suite
5. If there are display differences between browser versions following the steps outlined below

Fixing CSS for a Specific Browser

IE6 is the culprit in the following example:

1. Duplicate the compliant layout CSS file and rename it layout_IE6.css
2. Modify the layout_IE6.css files for IE6 compatibility
3. Use a scripting language to inject the IE6 links after the standards compliant links. Refer to this post for details
4. Test your changes with a browser testing suite. You’ll only need to run tests for IE6
5. Don’t delete unchanged styles from the IE6 CSS file

References

• http://www.smashingmagazine.com/2007/10/02/
  browser-tests-services-and-compatibility-test-suites/
• http://www.melbournechapter.net/wordpress/web-accessibility/
  cman/2006/05/12/css-ie-hacks-recommendations/