Guide to Common Structure

Modules

Common is broken up into modules that are somewhat optional and can be included or excluded using SAutoload::addModule(). Each module provides a service of some sort, or an API. Some modules are included by default, such as pr2 and helpers. Others, such as sdr and tsd, are not required and should only be included if these services are needed in the project.

Directory Structure

• config - configuration files
• content/ - helper classes for handling content (XML, etc.)
• Doxyfile - configuration file for creating public documentation
• Doxyfile.internal - configuration file for creating internal documentation
• doxygen/ - source code and binaries for doxygen
• helpers/ - miscellaneous helper classes
• jpgraph/ - jpgraph PHP-based graphing add-on
• pdoc/ - special page documentation
• pr2/ - PageRender2 class files
• scripts/ - shell scripts for maintenance (e.g., documentation generation)
• sdr/ - Shodor Data Repository class files (client-side API)
• sdrservice/ - Shodor Data Repository Service class files (server-side API)
• snap2/ - Snap2 Content Management System class files
• SWAT/ - Shodor Web Application Toolkit class files
• tcpdf/ - TCPDF PHP-based PDF generator add-on
• tk2/ - Toolkit class files
• tsd/ - Textbooks, Standards and Dictionary class files
• ui/ - CSS, JavaScript and images for shared user-interface themes
• XForms/ - XForms classes

config

The config/ directory contains three files:

• serverDefaults.php5
• serverLocal.master.php5
• serverStandardIncludes.php5

The serverDefaults.php5 contains default settings and configuration options for all of the modules in common. These can be overridden in serverLocal.php5, which must be manually copied from serverLocal.master.php5 and configured on a per-checkout basis. serverStandardIncludes.php5 performs all of the initialization of the framework and should be included by a project's standardIncludes.php5.

content/

The content directory contains all classes related to processing content.

• CM2, CM3, and AlbumModule are classes that generate StdXML that can be rendered to the screen by PR2 translators. Use CM2 or CM3 to create the XML representing a searchable listing page (i.e. interactivate/activities/).
• DBI2 is a database interface class for connecting to and querying an SQL database
• Mailer allows you to send emails
• SVCalendar and SVEvent generate iCal-compatible VCalendar files
• DBI and ContentModule are deprecated

Doxyfile

This file contains the Doxygen configuration for generating the public documentation. Public documentation is intended for those who are only using common to develop, instead of actually developing in common itself.

See Guide to Documentation for more on configuration of this file.

Doxyfile.internal

This file contains the Doxygen configuration for generating the internal documentation. Internal documentation is intended for those who will be developing features in common itself and so need to know internal APIs and other information that is not relevant for simply using common.

See Guide to Documentation for more on configuration of this file.

doxygen/

In order to use certain versions of Doxygen, the source code and binaries for Doxygen live in here. The binaries are compiled to run on login.shodor.org, so you will have to recompile when using common on other machines. There is no script to do this, but one will likely be added in the near future.

helpers/

Helpers are static classes that provide globally useful helper functions:

• EscapeParser: ??
• imageLibrary.php5: Standard image manipulation functions
• SPath: Dynamically build all the URLs commonly used by projects
• SStringHelper: String-related functions such as diffs
• SURLHelper: URL-related functions like redirects
• SValidation: Validate user input against a global set of input types
• SXMLHelper: Parse and convert XML strings
• XmlFormatter: Format XML files

jpgraph/

The jpgraph add-on stays in this directory. It only seems to be used by the Reflections tool.

pdoc/

This directory contains Doxygen-consumable documentation files for general common stuff. This page, for example, has a file called structure.pdoc located in the pdoc/ directory. All files in pdoc directories should end in .pdoc so that Doxygen knows to use them.

pr2/

The pr2 directory contains PageRender2, the page layout and templating system.

• components/: required add-ons to translators, (i.e., the script to generate the iframe of thumbnails for displaying a photo album)
• config/: the default settings for all PR2 objects (should eventually be moved to SConfig)
• layout/: objects that generate the actual HTML output for a page
• NavXMLModule.php5: generate XML representing page navigation
• PageRender2.php5: the engine used to render a page
• pdoc/: module documentation
• SInput.php5: object describing one "load" of content into a PR2 page
• SPage.php5: output buffer used by PR2; holds values for "slots"
• template/: templates that describe what parts of a layout show up, and in what order
• translate/: translators that take input text/objects and convert them to output HTML

scripts/

This directory contains utility scripts. Right now, only two scripts reside in this directory:

• makedoc.sh: shell script for generating Doxygen documentation
• genmodel.pl: Perl script for generating model files compatible with SModel2

Any additional maintenance or auto-generation scripts should go in this directory.

sdr/

sdr/ contains objects used for querying the SDR Search Service and parsing the XML strings that it returns. These classes are only for querying SDR, not for submitting or updating any new metadata.

sdrservice/

sdrservice/ contains objects used for submitting to, updating, and directly querying the sdr metadata database. These classes do not relate to sending data over the SDR Search Service.

snap2/

The following subdirectories are present in snap2/:

• content/: content modules live here
• core/: the Snap2 kernel, including SnapDBI and the Snap2 class itself
• objects/: filesystem objects, such as SnapResource
• pdoc/: module documentation
• perl/: the Snapple API and command line shell
• perm/: permission management classes
• sql/: SQL scripts for creating and deleting Snap2 databases
• tk2/
  • previews/: preview classes for viewing content
  • editors/: editor classes
• util/: various utility classes, including SnapSearch

When creating new content types in Snap2, you should follow the Guide to Creating and Modifying Content Modules. Those objects go in content/, and the TK components in tk2/previews/ and tk2/editors/. The only other directory which should accept new objects is util/, for any new utility classes providing features above and beyond the original API.

The perl/ directory contains the Snap2 Perl API, which is itself in perl/Snap2/. The command line tool, which uses the API, but presents a user-interface, is called snapple and lives directly in perl/.

As with all modules, the pdoc/ directory contains documentation meant to be consumed by Doxygen and used to build special pages. New guides should be put here and should follow the documentation guidelines as described in the Doxygen Guide.

SWAT/

The SWAT directory contains the Shodor Web Application Toolkit, which handles ORM, sessions, and event handling

• auth/: authentication modules
• event/: objects used during project event handling
• model/: SModel ORM system
• model2/: SModel2 ORM system (newer, more features)
• questionnaire/: classes to create a standard questionnaire system (to be extended in a project)
• session/: session, user, and transaction objects for keeping track of user state
• SWAT.php5: the root class of the SWAT framework
• SWATFunctions.php5: helper functions used by SWAT

tcpdf/

The TCPDF add-on stays in this directory. It generates PDFs via an API. It will be used mostly by InteractivatePlus. The API is not in any way connected to the rest of the common API and is not configured via such.

tk2/

tsd/

ui/

This directory contains all of the CSS, JavaScript and image files needed for skins, themes and Ajax. Each project that wants to have a skin that can be used by other projects will have a directory in here. There is also the default skin, which belongs to no project and lives in the default/ directory. The fledgeling Ajax libraries live in swat/. They are not well-documented and are in flux and are, currently, pretty much only used by TSD, and some in Snap2. The documentation for them, such as it is, is at SWAT JavaScript Libraries.

XForms/

The XForms directory contains XForms, the framework for rendering and processing XML XForms using normal HTML forms.

• .htaccess: the rewrite rules that allow Pictchas to work
• control/: form control objects (input objects such as text boxes, selects)
• DateParser.php5: a helper that parses dates
• Form.php5: a form builder
• FormInput.php5: a form input for the form builder
• FormsMailer.php5: a class that emails XForm output
• group/: objects to hold groups of form control elements
• pdoc/: module documentation
• pictcha/: supporting files for the pictcha system
• Pictcha.php5: Shodor's picture-based user validation (i.e., "captcha") system
• pictcha.xml: The data to power the pictchas
• QueryBuilder.php5: (DEPRECATED)
• StandardValidator.php5: class to validate form input (will eventually be subsumed by helpers/SValidation)
• validationErrors.xml: the error codes for different validation types
• XFormsFunctions.php5: helper functions
• XFormsInputProcessor.php5: used by XFormsRenderModule to process form input
• XFormsInterfaceBuilder.php5: used by XFormsRenderModule to build the form interface
• XFormsRenderModule.php5: the engine for building/processing XForms