Module File Structure 2.0 Guide

Created: 2007-09-24    Modified: 2007-09-24    Author: Greg Hemphill

This is a basic overview of Webstop's web application (module) file structure. The document covers the basic file structure of Webstop's web applications. Specifics of the purpose, function, and conventions of files is beyond the scope of this document. That being said, I go into a small amount of detail in areas that are new or diverge from our previous approach.

At the time of writing this document we have yet to implement all of these conventions on a module, but plan to use this method for new projects and major module upgrades.

A few conventions: When naming files or folders the word "module" is used to represent the application's name (example: WeeklyAd, Recipes, or etc.). Some files and folders will have "{site}" to represent the 3 or 4 letter site abbr. (example: WeeklyAd_PCN).

Overview of Changes:

• All "slamable" module files have been moved from the Includes_Module folder into various folders within the primary module folder.
• Primary module folder no longer contains files, but rather folders. Most of the files traditionally found in the module folder are now located in the Pages folder.
• We have done away with the "Includes_Module" folder. All slamable module files are moved into respective folders within the primary module folder. All retailer specific files are moved into the "Module_{site}" folder.
• Added AJAX and JavaScript folders and the Module_J.js file type for Web 2.0 functionality.
• All retailer specific files now end with the site value (example: Header_WeeklyAd_PCN.inc).
• Switch files and folders added for URL Design and One File processing.

Module Folder

Naming of files within this section take the form of {module}_{page}_{type}.{extension} (example: WeeklyAd_Search_B.inc).

Version File

The Version file contains consise notes for the purpose of understanding what must be done to upgrade a module to this version. The file is named with the version number, so it also serves the purpose of allowing us to know what version of the module we are looking at.

When making an entry into a version file "less is more". The "why" description should be summed up in one or two lines. The rest of the file is purely ment to indicate what changes need to be made to bring a module of the previous version to this release.

Version Notes Folder

When the author sees a need to list more information than the bare minium needed to upgrade to this module version, a version notes file can be created to provied detailed notes. This file is optional and generally only created for complex or large upgrades.

AJAX Folder

This is a new folder who's purpose is to house the files used in AJAX returns. Think of these as mini pages within a page. The Protoype.js file is required for AJAX to function under our standard approach (we may switch to jQuery at some point).

Basic AJAX files:

• XHR File: A light version of the traditional Stub file. They differ from Stub files in the Pages folder in that they don't contain templates or other includes normally used in a web page.
• Stub (S) File: A traditional Stub file used when JavaScript is disabled or otherwise not functioning in the browser. This allows the function of the AJAX return to be available via a new page.
• Proc (P) File: (optional) A traditional Proc file which contains a majority of the Lasso code used in the page. Note: I forgot to include this file in the screenshot below.
• JavaScript (J) File: (optional) Contains JavaScript used in the AJAX return.
• Body (B) File: Traditional Body file containing mostly HTML.

CSS Folder

Contains slamable CSS files.

JavaScript Folder

Contains application level JavaScript files. There are also Site and Page level JavaScript files, but they are placed in other folders.

Pages Folder

The Pages folder contains the main Stub, Proc, JavaScript, and Body files of web pages in the module.

Naming of files within the folder take the form of {module}_{page}_{type}.{extension} (example: WeeklyAd_Search_B.inc).

The primary landing page (home, default, index, or etc.) of each module is named {module}_Index_{type}.{extension.} (example: WeeklyAd_Index_B.inc). Notice the {page} portion of the file name is "Index", this serves to better sort the files within the Pages folder.

Switch Folder

Provides the files used for URL Design and One File functionality of the module.

Module_{site} Folder

The Module_{site} folder replaces the primary function of the Includes_Module folder - to house retailer specific files. The folder name change serves to group the folder near the primary module folder for easy development and upgrades.

Naming of files within this section are a little differnt than in the Module folder. Naming takes the form of {type}_{module}_{section}_{site}.{extension} (example: Config_WeeklyAd_Search_PCN.inc or Config_WeeklyAd_PCN.inc).

The name of the folder and all files within it end in "_{site}". This is to prevent accidental slaming of the files and folders, and quickly identify the retailer it was created for.