Structure of Files and Directories

In this document we will walk through a typical tree of files and directories in a Cotonti setup and explain their purpose and standard conventions.

We start with the site root and describe its contents and then go deeper into each of its subfolders. Each significant branch of the tree is expanded consequentially, paths are contained in section titles.

Parts of the paths given in italics are not literal, you may substitute them with appropriate values.

#1. / - site root

There are several standard folders in the site root, they are described below each in its own section. As for the files in the root folder, typical of them are described in this list:

 /.htaccess special configuration file for Apache webserver, often used to finetune server settings and set URL rewriting rules.
/Install.txt a short memo how to install the CMS after unpacking.
/License.txt Cotonti license (3-clause New BSD License).
/admin.php Administration backend entry point.
/apple-touch-icon.png icon used by Apple touch devices in shortcuts to your site.
/favicon.ico icon used by browsers in navigation panes.
/index.php site homepage loader and main root-level script.
/message.php a script used to display service messages and errors.
/plug.php standalone plugin loader.
/rc.php compressed static resource (JavaScript/CSS) output tool.
/robots.txt settings for search engine spiders.
/module_name.php root-level loader for a module “module_name”.

#2. /datas – site configuration and user files

This directory contains “data files” specific to the site and its users. Most of its contents is static files, except for a few configuration scripts.

/datas/avatars contains user uploaded avatars.
/datas/cache contains cache files. Each subfolder represents a “cache realm” and contains cache entries (files) for that realm.
/datas/defaultav put default avatar pack here.
/datas/exflds contains uploaded files for file extrafields.
/datas/html contains static HTML files which can be displayed by “view” module.
/datas/photos user uploaded photos.
/datas/thumbs image thumbnails are stored here.
/datas/tmp general purpose temporary files (e.g. temporary file uploads) can be stored here.
/datas/users Personal File Space and Site File Space uploads live here.
/datas/config-sample.php sample configuration template, used by “install” module.
/datas/extensions.php configures file extensions allowed for upload on the site.
/datas/index.php directory listing blocker (present in many directories).
/datas/mimetype.php MIME type signatures used to verify files upon upload.
/datas/urltrans.dat URL transformation rules used by “urleditor” plugin.

#3. /images – static images used globally on site

Those are images uploaded by site administrator and used by various site extensions, themes and other parts.

/images/filetypes icons associated with file types.
/images/filetypes/default default file type icon pack.
/images/flags country flags.
/images/icons icon packs used by various extensions and themes.
/images/icons/default default icon pack.
/images/smilies contains current smiley pack.
/images/smilies/set.js smiley pack configuration file in JSON format.

#4. /js – JavaScript libraries

This folder is occupied by standard and third-party JavaScript libraries.

/js/base.js Cotonti basic JavaScript functions.
/js/jquery.js latest jQuery library version known to work well with Cotonti. You can also use jQuery from a CDN instead.
/js/jquery.plugin_name.js a jQuery plugin “plugin_name”.

#5. /lang – core language files

Language files are generally organized into “language packs” by 2-character ISO language code. This folder contains common and core language files whereas each extension (module or plugin) usually ships with its own language files in a “lang” subfolder (see below in /modules and /plugins). In the list below you can substitute lang_code with a 2-character ISO code of an actual language.

 /lang/lang_code/admin.lang_code.lang.php Administration backend localization.
/lang/lang_code/countries.lang_code.lang.php localized country names.
/lang/lang_code/main.lang_code.lang.php common lexis.
/lang/lang_code/message.lang_code.lang.php localized service messages.
/lang/lang_code/translit.lang_code.lang.php for languages other than English, it may represent tables for forward and backward transliteration.
/lang/lang_code/users.lang_code.lang.php user account related language strings.

#6. /lib – third party libraries

These are the open source libraries which have been developed outside of Cotonti project and are used by some part of Cotonti. They are put in /lib folder to make it clear that they can be updated separately from Cotonti itself.

#7. /modules – extensions providing their own locations

Modules and plugins share the same structure and are called together with one wod “extensions”, so it is only described once. Structure of an extension follows the structure of the engine itself, which makes them self-sufficient. Most parts are optional, the only required part for an extension is setup file which informs the engine what it is. Substitute ext_name with an actual module or plugin name in the list below and lang_code with 2-character ISO language code.

/modules/ext_name each of such directories represents extension contents.
 /modules/ext_name/img contains images and other static files for extension layout.
 /modules/ext_name/inc contains “include files”, scripts which are executed from other scripts.
 /modules/ext_name/inc/ext_name.functions.php represents extension API, a set of functions, classes and globals which an extension utilizes itself and exports for use in other extensions.
/modules/ext_name/inc/ext_name.resources.php contains resource strings used by the extension.
 /modules/ext_name/inc/ext_name.part_name.php a general purpose include file; part_name usually means some action or sublocation of the extension.
 /modules/ext_name/js contains JavaScript files.
/modules/ext_name/lang contains extension localization (language) files.
/modules/ext_name/lang/ext_name.lang_code.lang.php localized strings in lang_code language for extension ext_name.
 /modules/ext_name/lib contains third-party libraries used by the extension, which are maintained independently from it.
 /modules/ext_name/setup contains auxiliary scripts used upon extension setup events; please remember that SQL handlers are always called before PHP handlers for the same event.
 /modules/ext_name/setup/ext_name.configure.php  this PHP script is called when extension configuration is updated.
/modules/ext_name/setup/ext_name.configure.sql this SQL script is called when extension configuration is updated.
 /modules/ext_name/setup/ext_name.install.php  this PHP script is called when extension is installed.
/modules/ext_name/setup/ext_name.install.sql  this SQL script is called when extension is installed.
 /modules/ext_name/setup/ext_name.uninstall.php  this PHP script is executed when an extension is removed with all of its data.
/modules/ext_name/setup/ext_name.uninstall.sql this SQL script is executed when an extension is removed with all of its data
 /modules/ext_name/setup/php_version-number.inc  such PHP patches are executed when an extension is being updated from previous version to version-number; all patches between current version and latest available are applied sequentially.
/modules/ext_name/setup/sql_version-number.sql such SQL patches are executed when an extension is being updated from previous version to version-number; all patches between current version and latest available are applied sequentially.
 /modules/ext_name/tpl contains extension template files.
/modules/ext_name/lib/ext_name.tpl main template file for the extension ext_name.
 /modules/ext_name/lib/ext_name.part_name.tpl a secondary template file for the extension ext_name which visually represents action or sublocation part_name.
 /modules/ext_name/ext_name.admin.php extension backend part.
/modules/ext_name/ext_name.ajax.php AJAX request handler.
 /modules/ext_name/ext_name.rc.php JavaScript/CSS static resource loader part.
/modules/ext_name/ext_name.setup.php extension meta information, public details and configuration is defined in this file, it is required for any extension.
/modules/ext_name/ext_name.php usually the main executable part of the extension.
/modules/ext_name/ext_name.part_name.php generic executable part of the extension ext_name, implementing action or sublocation part_name.

#8. /plugins – extensions which plug into other extensions or core

See section above for /modules. Plugins have same structure as modules.

#9. /setup – files used to install or update the system

Cotonti install/update utility uses files and subfolders located in this directory to install and update the core of the system while each extension ships with its own setup information. The description given below is mostly for core developers, other people usually don't need to do anything inside of this folder.

Please remember that for the same step or revision SQL patches are always applied before PHP patches.

/setup/branch_name Such a folder contains all patches developed within branch branch_name.
 /setup/branch_name/patch-prev_branch_name.inc  This PHP patch is executed after SQL patch when performing a branch upgrade from prev_branch_name to branch_name.
/setup/branch_name/patch-prev_branch_name.sql This SQL patch is executed before PHP patch when performing a branch upgrade from prev_branch_name to branch_name.
 /setup/branch_name/php_rrevision_number.inc  Such PHP patches are applied when updating to revision revision_number from a previous revision within the same branch. Such patches are applied revision by revision (both SQL and PHP).
/setup/branch_name/sql_rrevision_number.sql Such SQL patches are applied when updating to revision revision_number from a previous revision within the same branch. Such patches are applied revision by revision (both SQL and PHP).
/setup/install.sql Core database installation script.

#10. /system – core files and APIs

This directory contains core files required for the system to exist. It also contains the basic framework used by extensions and built-in modules which cannot be removed.

/system/admin Administration backend
/system/admin/img Contains standard administration icons.
/system/admin/tpl Contains standard administration layout templates
/system/admin/tpl/img Contains images used by the standard administration layout.
/system/admin/tpl/admin.part_name.tpl Template for the part_name part layout in the Administration panel.
/system/admin/admin.part_name.php Script which implements part_name part of the Administration backend.
/system/auth.php Authentication and authorization management API.
/system/cache.php Cache API.
/system/common.php Common include file which loads Cotonti system environment and basic entities.
/system/configuration.php Configuration management API, used mostly in system maintenance scripts related to extension management.
/system/cotemplate.php CoTemplate class library (template engine).
/system/database.php Database abstraction and manipulation layer (extends PDO).
/system/debug.php Debugging utilities, included when debug mode is on.
/system/extensions.php Extensions management API, used by backend scripts.
/system/extrafields.php ExtraFields API.
/system/footer.php Standard script executed when it is time to render page footer.
/system/forms.php Form generation API. Use it to generate form elements.
/system/functions.php Core API. Contains vital functions and functions used in all parts of the system.
/system/header.php Standard script executed when it is time to render page header.
/system/resources.php Standard resource strings. All of them can be overridden in theme resource files.
/system/uploads.php File uploading API.

#11. /themes – layout themes

Layout themes are stored in this folder. By default Cotonti searches for a template file in a current selected theme. If cannot find the template, it falls back to a file provided in extension’s “tpl” subfolder. Most files in the table below are optional, required files are pointed explicitly.

/themes/theme_name Such folders contains all files within a specific theme called theme_name.
/themes/theme_name/admin If a theme implements Administration panel theme too, then it contains backend templates in this subfolder.
/themes/theme_name/css This is not a requirement, but often CSS files are put in such a subfolder.
/themes/theme_name/img Static theme images are stored here.
/themes/theme_name/js Theme-specific JavaScript files can be stored in such a subfolder (optional).
/themes/theme_name/modules It is recommended to put module templates in this subfolder.
/themes/theme_name/modules/module_name.module_part.tpl Redefines layout for module_part of the module module_name for this theme (module_part may be missing if it the main module template).
/themes/theme_name/plugins Contains overridden templates for plugins.
/themes/theme_name/plugins/plugin_name.plugin_part.tpl Redefines layout for plugin_part of the plugin plugin_name for this theme (plugin_part may be missing if it the main plugin template).
/themes/theme_name/theme_name.php Contains general theme information, list of supported color schemes and overridden resource strings. This file is required.
/themes/theme_name/theme_name.lang_code.php Localization of specific theme language strings for lang_code language.
/themes/theme_name/theme_name.rc.php Special loader of theme-specific JS/CSS files.
/themes/theme_name/footer.tpl Page footer template. Required.
/themes/theme_name/header.tpl Page header template. Required.
/themes/theme_name/index.tpl Body part of the home page. Required for most sites with index page.
/themes/theme_name/message.tpl A template for service messages page. Required.
/themes/theme_name/plugin.tpl A fallback template used for plugins with no specifc template. Required if such plugins are used.
/themes/theme_name/warnings.tpl A custom template often embedded into a page for error/status messages output.
/themes/theme_name/module_name.module_part.tpl This is the legacy path used to store a template for module_part of the module module_name. Using /themes/theme_name/modules subfolder is recommended instead.


Frequently Asked Questions

None have been asked so far.

 



1. milleja46  2013-01-29 00:24

Ok have to admit, the last section on themes is definitely worthwhile to see. Especially would be great in it's own section on a tutorial for writing themes ;)

Only registered users can post new comments