The Kurogo framework requires very little setup to operate initially. For a production system, however, you are going to want to be familiar with many of the site and module options that can affect file locations, debugging information and module behavior.
All of the site’s configuration is controlled using .ini files. You can either edit these files manually or use the Administration Module to edit most of these values.
Most developers and administrators should find the structure of .ini files familiar. For a complete explanation on ini files, see the documentation for the parse_ini_file() function in the PHP manual.
The basic element contained in an INI file is the property. Every property has a name and a value, delimited by an equals sign (=). The name appears to the left of the equals sign. Strings should be enclosed in double quote marks. Constants can be included outside quote marks. A unique feature of the framework allows you to reference other values in included ini files by using braces {} around the key name to include.
key1="value"
key2=CONSTANT
key3=ANOTHER_CONSTANT "value"
key4="Using value {key3}"
Properties may be grouped into arbitrarily named sections. The section name appears on a line by itself, in square brackets ([ and ]). All properties after the section declaration are associated with that section. There is no explicit “end of section” delimiter; sections end at the next section declaration, or the end of the file. Sections may not be nested.
[section]
Semicolons (;) indicate the start of a comment. Comments continue to the end of the line. Everything between the semicolon and the End of Line is ignored.
; comment text
When running a module, the following config files are loaded automatically:
Other modules may also load files from the SITE_DIR/config/MODULEID folder for external data configuration, and specific configuration for module output and formatting. Refer to the documentation for a particular module to know the composition of those files.
The framework supports overriding configuration files for local server customization. Unless the configuration value CONFIG_IGNORE_LOCAL (defined in config/kurogo.ini) is set to 1, the framework will also load files with a -local in the file name for each configuration file loaded. I.e. SITE_DIR/config/site.ini can be overridden with SITE_DIR/config/site-local.ini. SITE_DIR/config/home/module.ini can be overridden with SITE_DIR/config/home/module-local.ini. It is not necessary to duplicate the entire file. Only the values that are different need to be in the -local file. It could also include additional values that are not present in the base config.
These files are ignored by the git version control system and are an excellent place to put sensitive file paths or credentials that should not be part of a public source code repository. It can also aid in deployment since your development machine may use different settings than a production server.
If CONFIG_IGNORE_LOCAL is set to 1, then -local files will be ignored. This is useful if you do not use them and may slightly improve performance.
In addition to -local files. There is also an option to include configuration override files by specifying a mode string. This string is like -local but can be set to any value. This will allow you to create multiple versions of configuration files, with slightly different versions of certain values and instantly switch between them. This option is set in the CONFIG_MODE value of config/kurogo.ini These files are not ignored by git.
One use of this would be to create development and production versions of some of your configuration files. You can have SITE_DIR/site-development.ini and SITE_DIR/site-production.ini with differing values for debugging. Then you can set CONFIG_MODE to development or production. If CONFIG_MODE is empty (the default), than no files will be searched. Another example would be to include authorization values for certain modules in a production environment.
Keep in mind that this setting is independent of -local files. -local files will override any option presuming CONFIG_IGNORE_LOCAL is not enabled.
Kurogo has included a series of example -production.ini files to indicate recommended values for production servers
There are a variety of methods that are used to retrieve values from the configuration files. Please see Module Configuration for more information on how to retrieve these values in your module.
The SITE_DIR/config/site.ini file configures the basic site configuration. It is broken up into several sections
The properties in this section are used during development. Most of them are boolean values (0 is off, 1 is on)
You should turn the _DEBUG options to off in a production environment and enable the Production Error Handler with an appropriate developer email address.
In the [urls] section you can put a series of values that allow you to map a url to another. Typically this would be if you want to map a module’s url to several possible values, perhaps to maintain historical bookmarks. The entered url will be redirected to the value you specify. For example:
Take care that you do not create infinite redirect loops.
There is a special case for the DEFAULT url. This is the module that is loaded when users enter your site without a module name (i.e. the root of your site). You can configure this to show a different module depending on the type of device/platform. In the initial setting, users browsing your site from a computer will be presented with the info module and users browsing your site from a mobile device will be shown the home module.
The default option will look for the most specific value when determining which default page to show. You can create entries like such (in uppercase)
- DEFAULT-PAGETYPE-PLATFORM - matches the specific pagetype/platform combination. like DEFAULT-COMPLIANT-COMPUTER or DEFAULT-TOUCH-BLACKBERRY.
- DEFAULT-PAGETYPE - matches all the devices from a particular pagetype. Like DEFAULT-COMPLIANT or DEFAULT-BASIC
- DEFAULT will match any device if a more specific entry is not found
This allows you to customize the front door experience for your users.
See Device Detection for more information on configuration values.
The main database connection can be used by a variety of modules for storing and retrieving values. See the database section for specific information on configuration values.
Each module contains an configuration file in SITE_DIR/config/moduleID/module.ini. This file contains values common to all modules, as well as module specific values.
When CREATE_DEFAULT_CONFIG in site.ini is set to 0, if you remove a module’s config folder it will be permanently disabled and will not be accessible.
See Home Module for information on configuring the look and layout of the home screen. You can also set HOME_MODULE equal to a different module.
There are a number of strings that are used throughout the framework to identify the site name the organization it is a part of. These include:
In addition to editing these files, you can use the administration module to manage the configuration. The admin module is located at /admin and does not have an icon on the home screen.