BMFO Development Guide

Install the Java Development Kit as described in the BMFO Administration Guide.

Install jEdit. jEdit is available from http://www.jedit.org

The AntFarm plugin was used extensively during the BMFO development. It can be obtained through the jEdit Plugin Manager

	Caution
	Add "-Xmx512m" to your jEdit shortcut in order to increase the available heap memory (in this case 512MB. "C:\j2re\bin\javaw.exe" -Xmx512m -jar "C:\jEdit\jedit.jar" Otherwise you'll run out of memory when compiling the documentation

TortoiseSVN is available from http://tortoisesvn.tigris.org.

TortoiseSVN adds a context menu to the Windows Explorer.

Select SVN Checkout from the Explorer context menu (Figure 1.

Figure 1. TortoiseSVN Context Menu

As shown in Figure 2, use the URL https://svn.sourceforge.net/svnroot/bmfo/trunk/bmfo to check out the BMFO sources.

Figure 2. TortoiseSVN Checkout

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

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

Apache Ant is a Java-based build tool. It can be used to automate tasks.

The BMFO distribution contains 3 ANT build files:

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/.

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 actual conversion is done by the XSLT processor saxon, which is available from http://docbook.sourceforge.net.

An ant build file (build.xml) is available in the doc folder to automate building the documentation in the following formats:

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 .

PDF Documentation can be generated with fop. The fop is available from http://xml.apache.org.

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.

The DocBook XSL template language.attribute in l10.xsl should be changed to assign the value "rtl" to the attribute dir if the language equals "'ar'".

Arabic PDF: Special processing

Doxygen is used to document the BMFO 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.graphviz.org.

Please insert the appropriate comments to document the PHP sources.

Manual testing is done using Firefox and Internet Explorer.

The HTML Validator for Firefox is used to check the HTML validity (Section 2.4).

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.

To edit the dcmms.po files, poEdit is recommended. It is freely available from http://poedit.sourceforge.net.

	Tip
	Install poEdit version 1.3.4 or higher.

4.1.1. Settings

In order to extract the translation messages from the PHP sources, the following settings should be applied.

Start poEdit.

Select Preferences from the File menu.

Select the Parser tab and click on the New button.

Figure 1. poEdit PHP parser settings

Fill in the settings as shown in Figure 1

Close the dialogs.

Open a dcmms.po file.

Choose Options... from the Catalog menu.

In the Paths tab, add the path to the BMFO source as shown in Figure 2

Figure 2. Catalog Path

	Caution
	Make sure that you enter the actual path to the BMFO sources on your system.

Once the settings above have been applied, it is possible to update the catalog by selecting Update from sources from the Catalog menu.

The PDF reports are internationalized using Java ResourceBundles. These ResourceBundles can be generated from the bmfo.po files using the msgfmt command from the gettext distribution.

Gettext for Windows is available from http://gettext.sourceforge.net.

Create the ResourceBundles for the PDF Reports:

msgfmt --java2 -d ..\..\..\servlet\WEB-INF\classes -l ar_AR -r bmfo bmfo.po

Note that javac must be in your PATH.

	Note
	If you are using a gettext version < 0.15.0 on Windows you may encounter an error message like the following: msgfmt: cannot create a temporary directory using template "\/msgK5G9pb": Invalid argument In this case, try to set the environment variable TMPDIR to a temporary directory.

To ease the BMFO deployment under Windows, two NSIS installers have been created.

To compile the installers, you need the Nullsoft Super Installation System, which is available from http://nsis.sourceforge.net.

!define BMFO_URL "http://30.35.35.32:81/bmfo/"

The iReport report writer is available from http://ireport.sourceforge.net.

Use the following font settings for Arabized fields:

	Caution
	Make sure that arial.ttf is copied to your iReport folder for Arabic support.

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 4 for the details.

When echoing texts from PHP, use brackets to indicate that echo() is a function.

echo("test");

Single quotes should be used wherever possible for performance reasons

8.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.");
}

Example 6. Class indentation

class Test {
  // store the name
  $strTestName;
  
  // constructor
  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");

For non-trivial bugs, the following approach is recommended:

9.2.1. Bug Tracker

The Group attribute of the bug tracker shall be used to determine the version in which the problem will be fixed.

	Caution
	Don't use the group item to mark the version(s) that are affected by the problem.