This page describes the basic structure of the Gallery 2 application and some high level design concepts. It will help you learn your way around the codebase before developing new modules or themes, or modifying existing code. It helps if readers have some knowledge of object oriented programming and web based applications.
Gallery 2 is a PHP application that uses a single entry point to handle all HTTP requests: main.php. This script reads your configuration file (config.php) and then checks some basic parameters so it can handoff processing of the request to the right code. Gallery uses the Model-View-Controller design pattern (though with loosely defined models). In short, views are for display and controllers perform actions. So main.php determines which view or controller will process the request and hands over control. Views are then wrapped in a theme system to give site builders the ability to control much of the layout and appearance of the site with minimal PHP code involved.
__MAGIC_REMOVE__146290__
Modules define views (classes extending GalleryView) in *.inc files in the module's directory (alongside module.inc). There are two flavors of views:
Standard Views: These views create an HTML page in the application. To separate the code from the user interface, all data needed for creating the page is loaded first. The container for this data is the GalleryTemplate. The view loads whatever data it will need and then the theme (which may also load some data) takes over to render the page.
Immediate Views: These are special purpose views which bypass the theme system and send their output directly. This can be to send non-HTML output such as binary or XML data. Immediate views are also used for AJAX requests, where javascript code interacts with the Gallery server behind-the-scenes and updates the page dynamically as results come back. Some AJAX views may save changes to the database (arguably these should be controllers).
Themes have total control of Gallery's page layout and appearance. The Gallery framework determines the type of page being accessed and calls one of six functions in the active theme's theme.inc file (a class extending GalleryTheme).
Each of these functions loads any additional required data into the template and then specifies a tpl file for the page display. In most cases this is theme.tpl. Calling theme.tpl first creates a wrapper for other page types and maintains a basic look and feel (headers, banners, etc) across all Gallery pages. The theme.tpl then rechecks the page type and includes the associated tpl for the Gallery content requested. More about themes and the template system
Controllers perform actions that will save changes on the server. Adding new photos or comments, changing settings or even logging in are actions handled by controllers. Controllers extend the GalleryController class and their code resides in the *.inc files in a module's directory along with the views.
Generally the first task done by controllers is to verify proper permissions for the requested action. Always remember that even if your view omits a button or link based on permissions, the controller still must check permissions as HTTP requests can be manually constructed.
The second task is to validate the input data. If any user entered data is missing or invalid, the controller adds a token to the $error array that will be returned. Only if the inputs are valid does the controller proceed with the operation and set a key in the $success array. Controllers then instruct main.php what to do next. Upon success a controller will send a redirect, usually back to the same view. The $success data is stored in the session and made available to the view in the next request so it can show a status message. If $error is nonempty usually a controller will delegate back to the same view. This means the view is rendered in the same HTTP request, so the given $form data is still available. The view can then fill in the user entered data (so they don't have to enter it again) and check the $error tokens to show the appropriate error message next to the invalid data. These checks and messages are in the tpl file for the view.
Some views make it possible for other modules to add components, bringing different features together in a common user interface. All three of the admin type views (core.SiteAdmin, core.ItemAdmin and core.UserAdmin) use "subviews" to group those functions together. A subview is defined in a *.inc file and is written like a normal view. The difference is the module.inc file will list the view in its getSiteAdminViews, getItemAdminViews or getUserAdminViews function so a link for the view will appear in the sidebar of the appropriate admin area. Note that subviews use their own controllers (there is no "subcontroller").
Two subviews have additional levels of depth for adding user interface components. core.ItemAdd and core.ItemEdit are both ItemAdmin subviews, but each includes too many options to show on a single page. So each offers a plugin interface (not to be confused with the usual meaning of a Gallery plugin, which is a module or theme) to add components, which are shown as tabs. Modules can register implementations of the ItemAddPlugin or ItemEditPlugin interface in the performFactoryRegistrations function to make these components available when the module is activated. While registered in a different manner, these are still similar to subviews in that they control the main content of the page. The final level of depth is ItemAddOption and ItemEditOption. These are also factory registrations, but instead of defining an entire form they add just a section to a form and some processing upon form submission. ItemAddOptions may add some form controls (such as the checkbox for whether to build thumbnails), or they may add no UI component and just perform post-processing (such as EXIF autorotate). ItemEditOptions usually have both UI and post-processing, and also are registered to appear with a particular ItemEditPlugin. For example, the thumbnail module adds its custom thumbnail controls to the General tab, as any item type can use a custom thumbnail. The size limit module adds controls to the Album tab, as its settings are defined for an entire album.
The *Option classes discussed above are two examples of factory interfaces. Gallery uses this mechanism for all communication between modules. A module defines an interface class that describes the functions of the interface. This can be used in two ways: other modules can define implementations of the interface, allowing those implementations to be found and used. This is how the *Option classes are discovered. It is also how the search module allows other modules to make their data searchable. Alternatively, the module itself can implement the interface which allows other modules to use it. This is how the EXIF module allows other modules to read EXIF data from image files. Implementations are always registered in the performFactoryRegistrations function of module.inc. The interfaces themselves don't need to be registered.
Gallery includes an event system so that modules may take action when certain events take place. For example, the ratings module listens for GalleryEntity::delete events and remove all ratings for an item when the item is deleted. No registration is needed for event types; other modules just need to listen for the right event name. Read more about events.
Security is a shared responsibility of modules and the Gallery framework. The framework provides tools such as GalleryUtilities::getRequestVariables and GalleryCoreApi::assertHasItemPermission, but modules must also use these properly. Other aspects of security are transparent to modules, and handled automatically by the framework, such as preventing session hijacking or cross site request forgery. Read more about Gallery 2 Security.
Gallery manages user sessions automatically. When a user logs in or a guest does something that requires saving state between requests (such as adding items to a cart), a persistent session is created. Modules can store short-lived information in the session too. This information is discarded if the user logs out or the session expires. Gallery takes care of creating a cookie to track the session, or adding the session ID to all URLs in the page if the browser does not accept cookies. Read more about session management.
Gallery is an internationalized application. This means all user-visible text in the application can be translated for display in any language. Modules make text available for translation by using the $module->translate() or $gallery->i18n() functions in PHP code, and the {g->text} tag in tpl files. Note that these translations are for text included with the application. User entered text (such as image titles and captions) are not translated by this system. The multilanguage module does make it possible to enter a few basic fields in more than one language. Read more about internationalization and translations.
Check the available documents in the Gallery 2 Development category to find additional detail on these and other topics. Particularly look for the Module development tutorial and information about the Gallery 2 APIs. Also, once you understand the basics, looking at existing code is a great way to learn how to accomplish various tasks in Gallery code. You can also visit the #gallery channel on irc://chat.freenode.net to ask development questions. Good luck!
