Web Script File Structure

Here are some suggestions for organizing web script files.

Small Apps

For small apps I find it best to put everything in the same folder. However, I like to name "include" files beginning with a "include_" or "inc_" prefix. Typical include files would be:

include_formatting.prg - Formatting utilities such as page headers and footers
include_form_utils.prg - Utilities for forms, such as SQL generators, form cell generators, validation routines, etc.
include_report_utils.prg - Utilities for reports. (Perhaps combine with "formatting" above in smaller apps.)
include_general.prg - Commonly-used routines such as security checks and database handles or wrappers.

(".prg" is a place-holder extension for a program script of some unspecified language.)

Medium Apps

In medium apps it makes sense to start using folders. I've found it a mistake to put things on different levels of folder trees because changing reference paths can be far more work when files are moved. I strongly recommend that almost everything be at the same tree depth if folders are used. Thus, if your folder tree is 3 levels deep, then make sure every file is 3 levels deep. Don't put files on level 2. It will reduce the need to change "include" paths significantly.

Some prefer a "functional" setup and some a domain setup. A functional setup would be folders set up along the lines of the groups described in FuseBox (forammting, query, display, etc.). A domain setup would be along the lines of domain objects or entities. Example domain grouping:

Include_Files // (shared libraries)
- include_formatting.prg
- include_form_utils.prg
- Etc...
Teachers
- teacher_search.prg
- teacher_edit.prg
Students
- student_search.prg
- student_edit.prg
Grades
- etc...

Large Apps

For larg apps, often more levels are wanted due to the shear number of files. One approach is functional divisions on the first level and domain on the second. Or, one could do it the other way around. Here is an example of putting domain divisions on the outer level:

Students
- Search
- Reports
- Edits // (or "Forms")
Teachers
- Search
- Reports
- Edits
Grades
- Search
- Reports
- Edits
Include_Files

Nature of Include Files

Some use include files to simply add the needed code into scripts. For more complex apps this can be problematic because often you need to have options for them. Raw code includes don't handle the concept of parameters very well. Thus, functions or object instantiation makes more sense. If the language does not support named parameters, then consider objects instead. Named parameters are important because there can be lots of variations and adding and counting a new positional parameter for each option can be sticky. Named parameters don't care about order and can have defaults such that you don't have to mention every option.

Objects take up more code, but without named parameters are the next best thing. Subclassing things like page headings into heading sub-types has not worked out well for me because the features can be somewhat orthogonal such that a sub-class hierarchy does not manage the variations well and grows into a sprawling vine. Thus, I tend to use attributes instead of subclasses. If you can get sub-classing to work somehow, that is fine.

 // example file ------

 include("../includes/inc_general.prg");
 include("../includes/inc_formatting.prg"); // functions for formatting

 pageHeader(navigational_bar=false, path_bar=true, quick_links=true);

 ... body ...

 pageFooter();   // no parameters means its the default

 // -- functions --
 function myFunc(...) {
   ...
 }
 // end file -------

Here, the "inc_formatting.prg" file defines the functioins "pageHeader()" and "pageFooter()". An OOP version may look like:

 // example file ------

 include("../includes/inc_general.prg");
 include("../includes/inc_formatting.prg");

 ph = new PageHeader()
 ph.navigation_bar = false;
 ph.path_bar = false;
 ph.quick_links = true;
 ph.render();

 ... body ...
 ... etc ...

An associative array can be used instead of objects.

If one follows the tree depth rule above, then a shortcut "include" function can be made such that one does not have to repeat the include path or extension over and over:

  myInclude("inc_general");

But some languages do not allow this.

Some shops like the FuseBox division of script segments into queries, actions, display, etc. I was never fond of those, but the sugguestions above can still work for those. Example:

Teachers
- Search
  - Actions
    - act_search_teachersByTopic.prg
    - act_search_teachersByName.prg
  - Queries
    - qry_search_teachersByTopic.prg
    - qry_search_teachersByName.prg
  - Display
    - dsp_search_teachersByTopic.prg
    - dsp_search_teachersByName.prg

CategoryWebDesign, CategoryInternet, CategoryInfoPackaging, CategorySourceManagement