6. Support Classes

6.1. Sending Email Messages

The following classes, along with the EmailTemplate and MailTemplate model classes and EmailTemplateDAO DAO class, provide all email functionality used in the system:

  • classes/mail/Mail.inc.php

  • classes/mail/MailTemplate.inc.php

  • classes/mail/ArticleMailTemplate.inc.php

Mail.inc.php provides the basic functionality for composing, addressing, and sending an email message. It is extended by the class MailTemplate to add support for template-based messages. In turn, ArticleMailTemplate adds features that are useful for messages pertaining to a specific article, such as message logging that can be viewed on a per-article basis.

For a sample of typical usage and invocation code, see the various Action classes, such as SectionEditorAction's notifyReviewer method. Note that since nearly all emails composed by the system must be displayed to the user, who then must be able to modify it over several browser request-response cycles, some complexity is necessary to maintain the system's state between requests.

6.2. Internationalization

System internationalization is a critical feature for OJS 2.x; it has been designed without making assumptions about the language it will be presented in.

There is a primary XML document for each language of display, located in the locale directory in a subdirectory named after the locale; for example, the en_US locale information is located in the locale/en_US/locale.xml file.

This file contains a number of locale strings used by the User Interface (nearly all directly from the Smarty templates, although some strings are coded in the Page classes, for example).

These are invoked by Smarty templates with the {translate key="[keyName]"} directive (see the section titled User Interface for more information). Variable replacement is supported.

The system's locales are configured, installed and managed on the Languages page, available from Site Settings. The available locales list is assembled from the registry file registry/locales.xml.

In addition to the language-dependent locale.xml file, locale-specific data can be found in subdirectories of the dbscripts/xml/data/locale and registry/locale directories, once again named after the locale. For example, the XML file dbscripts/xml/data/locale/en_US/email_templates_data.xml contains all email template text for the en_US (United States English) locale.

All XML data uses UTF-8 encoding and as long as the back-end database is configured to properly handle special characters, they will be stored and displayed as entered.

OJS 2.x has limited support for simultaneous multiple locales for a single journal. For example, articles have a primary locale; however, titles and abstracts can have up to two additional locales.

Internationalization functions are provided by classes/i18n/Locale.inc.php. See also classes/template/TemplateManager.inc.php (part of the User Interface's support classes) for the implementation of template-based locale translation functions.

6.3. Forms

The Forms class (classes/form/Form.inc.php) and its various subclasses, such as classes/manager/form/SectionForm.inc.php, which is used by a Journal Manager to modify a Section, centralize the implementation of common tasks related to form processing such as validation and error handling.

Subclasses of the Form class override the constructor, initData, display, readInputData, and execute methods to define the specific form being implemented. The role of each function is described below:

  • Class constructor: Initialize any variables specific to this form. This is useful, for example, if a form is related to a specific Article; an Article object or article ID can be required as a parameter to the constructor and kept as a member variable.

  • initData: Before the form is displayed, current or default values (if any) must be loaded into the _data array (a member variable) so the form class can display them.

  • display: Just before a form is displayed, it may be useful to assign additional parameters to the form's Smarty template in order to display additional information. This method is overridden in order to perform such assignments.

  • readInputData: This method is overridden to instruct the parent class which form parameters must be used by this form. Additionally, tasks like validation can be performed here.

  • execute: This method is called when a form's data is to be “committed." This method is responsible, for example, for updating an existing database record or inserting a new one(via the appropriate Model and DAO classes).

The best way to gain understanding of the various Form classes is to view a typical example such as the SectionForm class from the example above (implemented in classes/manager/form/SectionForm.inc.php). For a more complex set of examples, see the various Journal Manager's Setup forms (in the classes/manager/form/setup directory).

It is not convenient or logical for all form interaction between the browser and the system to be performed using the Form class and its subclasses; generally speaking, this approach is only useful when a page closely corresponds to a database record. For example, the page defined by the SectionForm class closely corresponds to the layout of the sections database table.

6.4. Configuration

Most of OJS 2.x's settings are stored in the database, particularly journal settings in the journal_settings table, and are accessed via the appropriate DAOs and Model classes. However, certain system-wide settings are stored in a flat file called config.inc.php (which is not actually a PHP script, but is so named to ensure that it is not exposed to remote browsers).

This configuration file is parsed by the ConfigParser class (classes/config/ConfigParser.inc.php) and stored in an instance of the Config class (classes/config/Config.inc.php).

6.5. Core Classes

The Core classes (in the classes/core directory) provide fundamentally important functions and several of the classes upon which much of the functionality of OJS 2.x is based. They are simple in and of themselves, with flexibility being provided through their extension.

  • Core.inc.php: Provides miscellaneous system-wide functions

  • DataObject.inc.php: All Model classes extend this class

  • Handler.inc.php: All Page classes extend this class

  • Registry.inc.php: Provides a system-wide facility for global values, such as system startup time, to be stored and retrieved

  • Request.inc.php: Provides a wrapper around HTTP requests, and provides related commonly-used functions

  • String.inc.php: Provides locale-independent string-manipulation functions and related commonly-used functions

In particular, the Request class (defined in classes/core/Request.inc.php) contains a number of functions to obtain information about the remote user and build responses. All URLs generated by OJS to link into itself are built using the Request::url function; likewise, all redirects into OJS are built using the Request::redirect function.

6.6. Database Support

The basic database functionality is provided by the ADODB library (http://adodb.sourceforge.net); atop the ADODB library is an additional layer of abstraction provided by the Data Access Objects (DAOs). These make use of a few base classes in the classes/db directory that are extended to provide specific functionality.

  • DAORegistry.inc.php: This implements a central registry of Data Access Objects; when a DAO is desired, it is fetched through the DAO registry.

  • DBConnection.inc.php: All database connections are established via this class.

  • DAO.inc.php: This provides a base class for all DAOs to extend. It provides functions for accessing the database via the DBConnection class.

In addition, there are several classes that assist with XML parsing and loading into the database:

  • XMLDAO.inc.php: Provides operations for retrieving and modifying objects from an XML data source

  • DBDataXMLParser.inc.php: Parses an XML schema into SQL statements

6.7. File Management

As files (e.g. galleys and journal logos) are stored on the server filesystem, rather than in the database, several classes are needed to manage this filesystem and interactions between the filesystem and the rest of the OJS. These classes can be found in the classes/file directory.

  • FileManager.inc.php: The three subsequent file management classes extend this class. It provides the necessary basic functionality for interactions between the web server and the file system.

  • FileWrapper.inc.php: This implements a wrapper around file access functions that is more broadly compatible than the built-in access methods.

  • ArticleFileManager.inc.php: This extends FileManager by adding features required to manage files associated with a particular article. For example, it is responsible for managing the directory structure associated with article files. See also ArticleFile and ArticleFileDAO.

  • PublicFileManager.inc.php: Many files, such as journal logos, are “public" in that they can be accessed by anyone without need for authentication. These files are managed by this class, which extends the FileManager class.

  • TemporaryFileManager.inc.php: This class allows the system to store temporary files associated with a particular user so that they can be maintained across requests. For example, if a user is composing an email with an attachment, the attachment must be stored on the server until the user is finished composing; this may involve multiple requests. TemporaryFileManager also extends FileManager. See also TemporaryFile and TemporaryFileDAO.

6.8. Scheduled Tasks

OJS 2.x is capable of performing regularly-scheduled automated tasks with the help of the operating system, which is responsible for launching the tools/runScheduledTasks.php script via a mechanism like UNIX's cron. Scheduled tasks must be enabled in the config.inc.php configuration file and the journal's settings.

Automated tasks are configured in registry/scheduledTasks.xml and information like the date of a task's last execution is stored in the scheduled_tasks database table.

The ScheduledTask model class and the associated ScheduledTaskDAO are responsible for managing these database entries. In addition, the scheduled tasks themselves are implemented in the classes/tasks directory. Currently, only the ReviewReminder task is implemented, which is responsible for reminding reviewers that they have an outstanding review to complete or indicate acceptance of.

These tasks, which extend the ScheduledTask model class and are launched by the runScheduledTasks tool, must implement the execute() method with the task to be performed.

6.9. Security

The OJS 2.x security model is based on the concept of roles. The system's roles are predefined (e.g. author, reader, section editor, proofreader, etc) and users are assigned to roles on a per-journal basis. A user can have multiple roles within the same journal.

Roles are managed via the Role model class and associated RoleDAO, which manage the roles database table and provide security checking.

The Validation class (classes/security/Validation.inc.php) is responsible for ensuring security in interactions between the client browser and the web server. It handles login and logout requests, generates password hashes, and provides many useful shortcut functions for security- and validation-related issues. The Validation class is the preferred means of access for these features.

6.10. Session Management

Session management is provided by the Session model class, SessionDAO, and the SessionManager class (classes/session/SessionManager.inc.php).

While Session and SessionDAO manage database-persistent sessions for individual users, SessionManager is concerned with the technical specifics of sessions as implemented for PHP and Apache.

6.11. Template Support

Smarty templates (http://smarty.net) are accessed and managed via the TemplateManager class (classes/template/TemplateManager.inc.php), which performs numerous common tasks such as registering additional Smarty functions such as {translate ...}, which is used for localization, and setting up commonly-used template variables such as URLs and date formats.

6.12. Paging Classes

Several classes facilitate the paged display of lists of items, such as submissions:

  • ItemIterator

  • ArrayItemIterator

  • DAOResultFactory

  • DBRowIterator

  • VirtualArrayIterator

The ItemIterator class is an abstract iterator, for which specific implementations are provided by the other classes. All DAO classes returning subclasses of ItemIterator should be treated as though they were returning ItemIterators.

Each iterator represents a single “page" of results. For example, when fetching a list of submissions from SectionEditorSubmissionDAO, a range of desired row numbers can be supplied; the ItemIterator returned (specifically an ArrayIterator) contains information about that range.

ArrayItemIterator and VirtualArrayIterator provide support for iterating through PHP arrays; in the case of VirtualArrayIterator, only the desired page's entries need be supplied, while ArrayItemIterator will take the entire set of results as a parameter and iterate through only those entries on the current page.

DAOResultFactory, the most commonly used and preferred ItemIterator subclass, takes care of instantiating Model objects corresponding to the results using a supplied DAO and instantiation method.

DBRowIterator is an ItemIterator wrapper around the ADODB result structure.

6.13. Plugins

There are several classes included with the OJS 2.x distribution to help support a plugin registry. For information on the plugin registry, see the Plugins section.