BSAdv Project on SourceForge Get Boy Scout Advancement at Fast, secure and Free Open Source software downloads

Users: | BSAdv Home Page | Release Notes | Using BSAdv | Youth Protection | Installation
Developers: | To Do List | Database Tables | Extending BSAdv | Database Consistency

Extending BSAdv

Extending the code refers to adding compatible MVC elements, without changing the existing code, and without changing the flow of code in existing MVC elements. This is distinctly different than bug fixes or enhancements of existing code. To begin, study the organization of data in the database tables. Decide if you need to create a report or a form. Reports read data from the MySQL database and create representations in HTML or other formats. Forms interact with the user and can modify the data in the database. Forms are generally more difficult to write than reports. Determine what data you need from the MySQL database, and how you want to represent it to the user.


BSAdv follows reasonably standard Joomla coding standards. To add an element foo, the following files need to be created:

Additionally, I like to create the following:

Development Process

To extend the functionality of BSAdv, you need skills in PHP, HTML, probably MySQL, and possibly JavaScript. If you have a preferred method to develop Joomla code, have fun! If you want some hints, this is the way I would go about it.

  1. Create the model. Create files:

    Iterate, making changes to site/models/foo.php until you like the variables displayed by site/views/foo/tmpl/debug.php.

  2. Create the template. Create file: site/views/foo/tmpl/default.php - Change the controller to execute this instead of debug.php:
    JRequest::setVar( 'layout', $task );
    If this is all that you want your extension to do, you are done.
  3. If you want your extension to return data to the MySQL database, you need to implement the following:
  4. Do lots and lots of testing.

JSON and JavaScript

Some of the more complex forms used in BSAdv interact with the user via JavaScript and DHTML. This concept needs a little more explaination here. This is the flow of data:

  1. The model reads selected data from several MySQL tables and creates one or more PHP objects. The organization of the objects depends on how the data ultimately needs to be accessed in the browser.
  2. The view passes the PHP objects directly to the template.
  3. The template executes the PHP function, json_encode(), converting each PHP object into a JSON-encoded string. This allows a complex object to be transferred to JavaScript as one Javascript variable. It may be more compatible with Joomla to convert the PHP object to JSON in the view, then have the template just pass it to the browser, but I chose to do it this way.
  4. JavaScript, executing in the browser, writes the JSON string to a JavaScript string. It then executes eval() to turn the JSON string into a JavaScript object.
  5. Javascript, executing in the browser, creates one or more DOM objects, each of which appear as a separate web page to the user. The general process is for the HTML to define one or more sections of the page with
    constructs, where name is a named section of the page, of your choosing. JavaScript then constructs one or more HTML representations for that section of the page and uses the construct
    element.innerHTML = string
    to write new HTML to that part of the page. These page changes are normally done as a response to the user clicking a button on the screen, which executes one or more JavaScript functions, which creates a new page. This appears to create a completely new page, but in reality, just updates the HTML on a part of the page. This it the DYNAMIC part of DHTML and is a powerful way to decrease response time to the user. For this to function, the designer must transmit all necessary database informatin to the browser, and the JavaScript must use it to create multiple HTML representations of that data, in response to user actions.
  6. Interacting with the user, JavaScript creates one or more variables, or modifies one or more variables from the server. When the user completes the edits, he or she submits the data back to the server with an HTML
    form action=
    usually as a result of selecting a Submit button. For convenience, we often encode the return data as a JSON string. To simplify determining what changes have been made to the variable(s), we keep an unmodified version of the data and transmit it back to the server along with the edited version. This reduces problems that occur when multiple edits are occuring simultaneously in the database.
  7. The server receives both the modified and original JSON strings, decodes them both into PHP objects, compares the modified PHP object to the original object, then creates database update commands to make the required database changes, if required. The data has now completed the cycle from MySQL database, to Joomla server PHP, to browser JavaScript, back to the Joomla server PHP and back to the MySQL database. It is quite a path, but JSON helps keep complex data in an object form throughout the process from server to browser and back to server.

Not all BSAdv elements use DHTML. Reports create HTML output only and do not perform database updates. Some forms have simple HTML update variables and do not use DHTML or JavaScript. DHTML and JavaScript are valuable when the application requires multiple display pages that change as a result of user interaction. The event controller is a complex example of this.

Helper Controllers

Several controllers are useful only to help other controlers.


Look at the following BSAdv code for examples of the previous explanations. The code can be found in the distribution tar file. The files are distributed throughout directories under the site directory, including site/controllers/, site/models/ and site/views/. See the examples for foo (above) for their locations.

Output only (reports)

Takes data from the MySQL database and creates HTML

Output and Update (forms)

Takes data from the MySQL database and creates HTML forms, which the user can modify. Submitting the form returns data to the server, which is used to potentially update data in the database.

Use in units other than Boy Scout Troops in the USA

Plans exist for converting BSAdv for use by Cub Scouts and other types of groups. The first step is to separate the advancement and merit badge databases from the BSAdv software. This will allow them to be updated separately. Next, the Cub Scout (or other group) advancement data needs to be mapped to the Boy Scout tables, and parallel update paths defined for the Cub Scout advancement updates. The different terminology used in the web pages for Cub Scouts will be implemented with translation files. Stay tuned. This will be interesting.

If the existing table structure cannot adequately represent the advancement requirements of your unit, then the tables would need to be modified. In addition to adding or deleting fields and tables, it may be necessary to modify the software.

Get Boy Scout Advancement at Fast, secure and Free Open Source software downloads Thanks to for hosting our project.