DCMMS Development Guide

Plug-ins for the identify tool of the map page should extend the IdentifyPlugin class. See plugin/imageidentifyplugin.php for an example.

Identify plug-ins shall read their configuration from conf/identifyplugin.ini. Each plug-in should have its individual configuration section.

See the Administration Guide for details on the plug-in configuration.

Plug-ins for the find tool at the top of every page should extend SearchPlugin class. See plugin/customersearchplugin.php for an example.

Search plug-ins shall read their configuration from conf/searchplugin.ini. Each plug0in should have its individual configuration section.

See the Administration Guide for details on the plug-in configuration.

In order to display Arabic map labels, a PostGIS database using UNICODE should be used. The labels should be TrueType labels with a UNICODE font that supports Arabic (e.g. Arial).

See the Administration Guide for an example how to load a shape file to such a table.

The Arabic letters have to be shaped, e.g. with the with the PostArabic shape_arabic() function. See Section 13, “PostArabic” for more details on Arabic shaping.

See also Section 8, “Internationalization”.

The DocBook XSL stylesheets are used to convert the documentation from the DocBook format to other formats. DocBook XSL is available from http://www.sagehill.net/docbookxsl/index.html.

The documentation build file (Section 5.3, “Documentation build”) expects a Docbook XSL installation in c:\ms4w\lib\docbook-xsl.

The actual conversion is done by the XSLT processor saxon, which is available from http://saxon.sourceforge.net. Saxon version 6.5.3 has been used.

The documentation build file (Section 5.3, “Documentation build”) expects saxon.jar to be installed in the c:\ms4w\lib folder.

An ANT (Section 7.1, “Ant”) build file (doc/build.xml) is available to automate building the documentation in the following formats:

The build file tweaks the generation of the Arabic user guide. You are encouraged to read the build file source.

It is possible to create HTML Help files (*.chm) from DocBook with the Microsoft HTML Help Workshop.

The HTML help workshop is available under http://www.microsoft.com/office/ork/xp/appndx/appa06.htm .

The documentation build file (Section 5.3, “Documentation build” expects the installation in c:\Program Files\HTML Help Workshop.

HTML Help Workshop version 4.74.802 has been used.

PDF Documentation can be generated with fop. The Formatting Objects Processor fop is available from http://xmlgraphics.apache.org/fop/.

The documentation build file (Section 5.3, “Documentation build”) expects the fop.jar installation in the c:\ms4w\lib folder.

fop version 0.95 has been used.

See also Section 5.2, “DocBook XSL”.

To build the Arabic documentation, it is currently necessary to shadow the class com.icl.saxon.charcode.ASCIICharacterSet with a new version where the function inCharset() always returns true.

	Tip
	lib\com\icl\ASCIICharacterSet.java should be compiled like this; java -classpath ..\..\..\..\saxon.jar ASCIICharacterSet.java

No PDF is created for the Arabic documentation. Word and PDFCreator can be used to create the PDF from doc/user/ar/index.html.

See also Section 5.2, “DocBook XSL”.

Doxygen is used to document the DCMMS API on the PHP level.

Doxygen is available from http://www.doxygen.org.

The doxygen configuration file can be found under doc/development/doxygen/doxygen.cfg.

In order to generate graphical class representations, you should install Graphviz to c:\program files\att\graphviz. Graphviz is available from http://www.research.att.com/sw/tools/graphviz/.

Please insert the appropriate comments to document the PHP sources (See Section 14.2, “Coding Style”).

The documentation build file (Section 5.3, “Documentation build”) expects doxygen.exe to be installed in c:\program files\doxygen\bin.

doxygen version 1.4.6 has been used.

The DCMMS repository contains the following modules:

See the Sourceforge documentation how to set up SVN access using TortoiseSVN:

http://sourceforge.net/docman/display_doc.php?docid=31165&group_id=1

Apache Ant is a build tool that allows to automate many processes.

Ant is available from http://jakarta.apache.org/ant/.

Ant is well integrated with the jEdit editor - the jEdit plugin is called AntFarm.

ANT is included in Eclipse.

Eclipse proofed to be a good tool for editing the Arabic User Guide.

Eclipse is freely available from http://www.eclipse.org.

The PDT plug-in (http://www.eclipse.org/pdt/) is very useful when developing PHP applications.

Eclipse includes ANT.

Eclipse (http://eclipse.org) can be used to build the documentation.

See Section 7.3, “Eclipse”.

To open the project, select File->Import. Then select General/Existing Projects into Workspace and click Next >. As root folder, select c:\ms4w\apps\dcmms.

To open the Ant view, select Window->Show View->Other.... Then select Ant/Ant.

To build on the documentation, click the Run the selected target button in the Ant view.

The tidy version in the HTML Validator for Firefox is used to validate the generated HTML code.

The HTML Validator for Firefox is available from http://users.skynet.be/mgueury/mozilla/.

Manual testing is done using Firefox and Internet Explorer.

The HTML Validator for Firefox is used to check the HTML validity (Section 7.4, “Tidy”).

The Canoo Webtest suite is used for testing the application.

Canoo Webtest is freely available from http://webtest.canoo.com.

The file containing the tests is script/test/build.xml.

To run the tests, follow the steps below:

The test report will be generated in script/test/webtest-results/results.html.

	Tip
	If you want to generate WebTest.dtd, you can use the "dtd" target of script/test/build.xml. The DTD will allow editors like jEdit to highlight syntax errors in the build file.

The DCMMS version number is split in three parts: Major, minor and revision.

DCMMS versions that don't change the data model in the database only increase the revision number (minor feature enhancements, bug fix releases).

For DCMMS releases changing the data model in the database, the minor number is increased.

The major number will be changed in case of large scale technology changes.

When adding a page to the application, make sure that the following standards are fulfilled:

The Nullsoft Super Installation System, NSIS is used to create the installers used in the DCMMS project.

NSIS is freely available from http://nsis.sourceforge.net.

The files dcmms.nsi and php.nsi in the dcmms module contain the scripts to create the DCMMS and DCMMS Scripting installers.

The fuzzystrmatch module contains the fuzzystrmatch.nsi installer source.

The sample module contains the dcmms_sample.nsi installer source.

The postgis module contains the postgis.ini installer source.

The arabic module contains the postarabic.nsi installer source.

Follow the instructions in bin/README.txt to add the necessary binaries of the GnuWin32 project to the bin folder.

To build the DCMMS Scripting installer, several PEAR packages and the PHP/Mapscript extension are required. See php.nsi for the details. The PEAR tarballs should be saved in c:\windows\pear.

The human interface design tries to follow the GNOME Human Interface Guidelines (http://developer.gnome.org/projects/gup/hig/).

Look at the existing codebase and try to code using the same style.

Update the ChangeLog for every commit.

2003-07-29  Steffen Macke <Steffen_Macke@dorsch.com.jo>

	* doc/development/dcmms_development_guide.xml: more 
	information on coding style

For variable names, use prefixes like flt, str, arr and date to indicate the variable type.

$strName = 'test';

Variable names should be descriptive, with the exception of simple loop variables like i,j,k,l,m

Use a wrap margin of 80 characters. jEdit can provide a guiding line for this purpose: Utilities Global Options Editing Wrap Margin

Internationalize all messages visible to the end user. See Section 8, “Internationalization” for the details.

When echoing texts from PHP, omit the brackets:

echo 'test';

Single quotes should be used wherever possible for performance reasons.

14.2.1. Indentation

	Important
	Use an indent width of 2 characters and a tab width of 8 characters. Do not use "Soft (emulated with spaces) tabs".

Indent classes, functions, loops and if statements properly. This allows to use jEdit folding.

Example 4. Loop indentation

foreach($arrNames as $strName) {
  echo $strName;
}

Example 5. If indentation

if($strValue == $strValue2) {
  echo 'Values are equal.';
} else {
  echo 'Values are not equal.';
}

Classes should be properly indented and commented in a way that is compatible with doxygen:

Example 6. Class indentation

class Test {
  /**
   * A member variable.
   */
  $strTestName;
  
  /**
   * Test function.
   * @param $strName A name to be passed to the constructor.
   * @return The object.
   */
  function Test($strName) {
    $strTestName = strName;
  }	  
}

Example 7. Switch indentation

switch($intValue) {
  case 1:
    $intResult = 2;
  break;
  default:
    $intResult = 1;
  break;
}

Separate arguments in function calls by a comma and a space.

Example 8. Argument separation

$strMessage = sprintf('This is a %s', 'test');

Make sure that you use lower case for geometry field names in