| HelpSet Table of Contents | Back to Project Home Page |
The Global Definitions File is a configuration file called definitions.inc, located in your Project Hirtius application directory (typically /srv/www/htdocs/hirtius/). Some of the parameters in this file will need to be tailored during installation to adapt to the specificities of your environment. This should be dealt with by the Administrator responsible for the server hosting the Project Hirtius application. For security reasons, access to this file should be restricted to the system administrator ('root') and the user account defined for the Apache web server ('wwwrun'). When editing this file, please use a UTF-8 compatible editor.
The goal of this help page is not to cover the installation process as such (as this is already covered in another document, outside of this HelpSet: a file called 'INSTALL' in the root of the Project Hirtius distribution archive), but rather to give more detailed information about each of the parameters that are defined there. There are three different kinds of parameters:
The following parameters have to be defined at installation time to match the specificities of the local environment. Please refer to the 'INSTALL' document provided at the root of the distribution archive.
| Param | Def. | Description |
|---|---|---|
| $url_base | (none) | The official URL that leads to your Project Hirtius installation. |
| $admin_email | (none) | The email address of the administrator in charge of your Project Hirtius installation. Will appear as a mailto: link in the footer of every page. Feel free to use a mailing list / alias if applicable. |
| $mysql_passwd | (none) | The password for $mysql_user (see below). |
| $webstore_base | (none) | The URL that leads to the website that stores your digital pictures (Slides, in Hirtius parlance). It may reside on the same server as the web-based application front-end, or somewhere else. The URL should be meaningful to all users of the application, so avoid things like http://localhost/.... |
The following parameters come with sensible default values, but may be tailored to your local installation if you so desire.
| Param | Def. | Description |
|---|---|---|
| $tll | 4 | Tag Level Length. The number of characters that
identify all nodes sharing the same parent in your INXtree
structure. The value you select for this parameter will determine the
maximum number of leaves each node will support, as well as the maximum
depth of your tree. The resulting values for both these parameters is
displayed on the Database Statistics Page.
More technical details on the meaning of this parameter can be found on the Database Layout help page. This parameter value can only be modified during initial program installation (see 'INSTALL' document). Any change later on may corrupt your database. Recommended range: between 2 and 6 (the selected value should be a submultiple of the inxtree.tag column length (currently 120). |
| $tidlen | 4 | Tray ID Length. The number of characters reserved
for the tray ID part of a slide's in-tray address.
This parameter value can only be modified during initial program installation (see 'INSTALL' document). Any change later on may corrupt your database. Range: between 1 and 4 (4 is current length of trays.tray_id column). |
| $debug | $DBG_OFF (0) | Enables debugging code within the application when set to
a non-zero value, typically through the insertion of HTML comments in the
rendered pages, or through pop-up messages in the case of JavaScript code.
Usage: enable or disable specific categories of debugging messages by combining the appropriate flags (defined just above in the configuration file -- see section below) using the bitwise 'OR' operator, e.g.: $debug = ($DBG_ALGO | $DBG_QUERIES); |
| $is_dev | 0 | When set to '1' (one), visually identifies a development
Project Hirtius instance by prefixing the application title with the
content of $dev_markT or $dev_mark (see
below). Range: 0 (zero) or 1 (one). |
| $mysql_host | localhost | The hostname of the server that hosts your 'hirtius' database. You can use 'localhost' if the same server hosts both the back-end database and the web-based application front-end, but you can easily split these two functions if desired using this parameter. |
| $mysql_user | hirtius | The user account that the web-based application front-end will use to authenticate against the back-end database. |
| $mysql_db | hirtius | The name of the database that the web-based application front-end will connect to. You can change this if you want to host a test and production database on the same server. |
| $authfile | /etc/webusers | Fully-qualified name of the file used to manage the Apache-based authentication to the web-based application front-end. All user accounts for Project Hirtius will need an entry there. |
| $htpasswd | /usr/bin/htpasswd2 | Fully-qualified name of the htpasswd or htpasswd2 provided by Apache to manage the content of the authentication file declared through $authfile above. The location of this utility can vary between Linux distributions. |
| $htbciter | 12 | Number of iterations to be performed by the
'bcrypt' algorithm (for password hashing). Acceptable range is
between 4 and 17. Suggested default is 12. The higher the value, the
stronger the hash (but beware: computing cost is exponential). Please make sure to read and understand 'man htpasswd2' (the '-C' parameter section) before modifying this value. |
| $min_pwd_len | 7 | Min. password length. Considered as recommendation only when the password is set/reset by an administrator. |
| $max_pwd_len | 255 | Maximum password length. It is not recommended to use a value larger than 255 due to a limitation in the underlying 'htpasswd' utility. |
| $html_charset | UTF-8 | The character set used by the HTML front-end. Make sure to use the same as the one used by the database client. "ISO-8859-15" is supported as well, but at this stage, I don't see any reason to select anything else than UTF-8 here. |
| $def_content_lang | fr | Defines the language in which most of the application
contents is expected to be written. Set it to the short code for one of
the languages defined in $supported_langs (see
below). It will be used, among others, to localise some the predefined strings used by the application, such as the textual templates for auto-events descriptions. All these strings are defined in the Translatable Strings File. |
| $allMTs | (array) | List of MIME types available during attachment upload. By default, the proper MIME type will be autodetected by the browser. But if this is not reliable, you can override its choice (or update it after the fact) using this list. Feel free to add more MIME types if needed. |
| $allshottypes | (array) | List of predefined values for the shot type field on the Slides Edition Page. They are stored in the database as the 3-letter code in the first field of the array. Feel free to add more values if needed. |
| $tiddly_pref_delete | 1 | Whether or not deletion of Tiddler records is allowed (subject to appropriate rights, of course). When set to '0' (zero), no deletion is allowed. When set to '1' (one), deletion is allowed based on the rights of the logged-in user. |
| $tiddly_pref_vers | 10 | Whether or not revision history information will be kept
for Tiddler records. Set to '0' (zero) to disable this feature
altogether. When set to '-1', an unlimited amount of past versions
are kept. Set to any positive integer value, the size of the version
history is limited to that value (10 by default). Changing the value of this parameter post installation is allowed, but the history size for existing Tiddlers will not be adapted immediately: only if and when such Tiddlers are further modified. |
The following parameters represent default values as well as lower and upper limits (where applicable) for user-selectable preferences. They may also be changed to provide defaults better suited to your environment or user population.
Please be careful when modifying lower or upper limits (they should make sense and not risk overly taxing the resources of your server or clients). Default values should also be sensible and obviously be situated between the lower and upper limit.
More information about the effect and meaning of the users preferences they control can be found on the Users Edition Page.
| Param | Def. | Description |
|---|---|---|
| $low_editbox_height | 5 | Height for editboxes when they contain less than 6 lines of text. Also serves as minimal value for user's preference for editbox height. |
| $high_editbox_height | 15 | Default height for editboxes when they contain 6 lines of text or more. This value can be overriden in the user profile. |
| $max_editbox_height | 60 | Maximum value the user can select for editbox height when they contain 6 lines of text or more. |
| $def_thsd_sep | ' ' | Default character used as thousands separator (space). This value can be overriden in the user profile. |
| $def_decm_sep | ',' | Default character used as decimal separator (comma). This value can be overriden in the user profile. |
| $min_query_lim | 10 | Minimum value for the "Records per page" user preference. See next field for meaning. |
| $def_query_lim | 100 | Default value for the "Records per page" user preference. It represents the maximum number of data rows that will be displayed on a given page as the result of a database query. This applies to all the application pages that use the "First - Prev - All - Next - Last" navbar. |
| $max_query_lim | 1000 | Maximum value for the "Records per page" user preference. See previous field for meaning. |
| $min_con_len | 10 | Minimum value for the "Context length" user preference. See next field for meaning. |
| $def_con_len | 60 | Default value for the "Context length" user preference. It represents the number of characters in front and after the match, used as context (aka "mini quote") on the Basic and Timeline Search Page result page (basic search mode only). |
| $max_con_len | 500 | Maximum value for the "Context length" user preference. See previous field for meaning. |
| $def_evt_type_code | 'EVEN' | Default value for the 'Default Event Type' drop-down list on the new user creation form. If you wish to specify a different default, make sure to use the 'event_type_code' column of an existing Event Type as listed on the Event Types Management Page. |
The following parameters were not meant to be changed and should not be tampered with (unless you really know what you do, as always).
| Param | Def. | Description |
|---|---|---|
| $app_name | (string) | Application name, used in headers on the web-based front-end and in reports. |
| $app_title | (string) | Application title, used in headers on the web-based front-end. |
| $app_version | (string) | Application version string. |
| $app_date | (string) | Application release date. |
| $exp_db_schema_version | (integer) | 'hirtius' database schema version expected by the application front-end. It is of course vital that both are in line. The database schema version will be queried first by each individual application page, and the current schema version doesn't match the expected one, an error message will be issued, and any further interaction with the database through the application front-end will be blocked. |
| $map_query_url | (URL) | URL for the Google Maps geolocation interface. |
| $dumpzone | reports | Name of the folder where user-generated report files will be created and made available for download. It should be a sub-folder of the main application installation subdirectory, and it should be made accessible to users through the Apache web server. |
| $icnsfldr | ./buttons | Name of the folder where the application icons are stored. This folder should NOT be called "icons" to avoid a clash with a similarly named folder in the default Apache setup when installing Hirtius as a virtual Apache host. Please note that this variable is only used in the application code. In case the folder is renamed, impacts in the HelpSet files is to be taken care of manually. |
| $helpzone | help | Name of the folder that contains the application on-line help system documents. It should be a sub-folder of the main application installation subdirectory. |
| $supported_langs | (array) | List of supported languages (two-letter code and English name) that can be selected as global default contents language, as target language for LaTeX project report generation, and for which a set of translated strings has been provided in the Translatable Strings File. |
| $punct_marks | '.,;:!?' | List of punctuation marks to consider when deciding whether or not to use a separator in 'title' and 'subtitle' concatenation. If the last char. of 'title' is within this list, the separator is dropped. |
| $anchor_mark | (HTML) | HTML code for the "anchor mark": ♠ (identifies those Slides marked as "entry point"). |
| $lanchor_mark | (LaTeX) | LaTeX code for the "anchor mark" (see previous field for meaning). Used in reports. |
| $autevt_mark | (HTML) | HTML code for the "auto-event mark": Æ (identifies those Events marked as "auto-events"). |
| $lautevt_mark | (LaTeX) | LaTeX code for the "auto-event mark" (see previous field for meaning). Used in reports. |
| $reqf_mark | (HTML) | HTML code for the marker that visually identifies required fields on HTML entry forms (*). |
| $clopro1, $clopro2 |
(HTML) | HTML code for the font style that visually identifies closed projects or the Tiddlers they contain on HTML entry forms (Example). |
| $nexobj1, $nexobj2 |
(HTML) | HTML code for the font style that visually identifies non-existent objects or non-local Biref/Srcref in the output of the auto-URLification function (Example). |
| $deld_mark | (HTML) | HTML code for the marker that visually identifies deleted objects on HTML entry forms (†). |
| $obsol_bgcol | BurlyWood | Background color that helps visually identify Slide objects that have been flagged obsolete. |
| $bg_sex_M | #b9cfe7 | Background colour for Male Individuals cells. The colour code is the same as that used by Gramps. |
| $bg_sex_F | #ffcdf1 | Background colour for Female Individuals cells. The colour code is the same as that used by Gramps. |
| $bg_day_shots, $bg_day_events, $bg_day_titles, $bg_day_SandE, $bg_day_SandT, $bg_day_EandT, $bg_day_all | #f8f30d, #0dd1f8, #f67a7a, #67f30d, #fd8000, #fa00fd, #676767 | Background colour for Calendar View days where event-like objects are linked. Each colour codes the event type or a combination thereof. The scheme was based on the use of primary colours for single objects and the mix between them for combinations. The resulting colour key is displayed beneath the calendar. |
| $dev_markT | DEV | Text content for the marker that visually identifies development instances of Project Hirtius. |
| $dev_mark | (HTML) | HTML code for the marker that visually identifies development instances of Project Hirtius (DEV). |
| $hbsthl_bgcol | (HTML) | HTML code for the highlight used by the HelpSet Navigator on search term matches. |
| $entlstmaxhi | 20 | Maximum height (in lines) for entity list selection control (as used on the Basic and Timeline Search Page, for instance). |
| $max_ttip_len | 500 | Maximum length for 'comment' fields when they
are displayed as tooltips. Any content that exceeds this value
will be truncated (for display purposes only) and suffixed with
'...' to denote the truncation. The HTML spec doesn't set an upper bound to the size of 'title=' properties, but some browsers may have issues with larger sizes. |
| $twk_db_table_name | tiddlers | Name of the 'hirtius' database table that contains Tiddlers. |
| $twk_db_bak_table_name | tiddler_versions | Name of the 'hirtius' database table that contains past versions of Tiddlers (their revision history). |
| (string) | Application name used in RSS/XML feeds. | |
| $tiddly_site_url | (URL) | Application URL used in RSS/XML feeds. |
| $tiddly_site_desc | (string) | Application description used in RSS/XML feeds. |
| $tiddly_site_lang | en-us | Application language used in RSS/XML feeds. |
| $tiddly_site_email | (string) | Application administrator email used in RSS/XML feeds. |
| $locked_titles | (array) | The list of default Tiddlers (the ones created at Project creation) that users won't be able to delete or modify. |
| $proj_site_url | (string) | URL of the official Hirtius Project website. Use this link to check for updated versions of the software or to get support. |
| $alllevels | (array) | Definition of the user authorisation levels supported by the application. |
| $allobjtypes | (array) | Short and long code equivalents for the fully-fledged object types supported by the application. |
| $allentities | (array) | Short code and description of all entities (objects, lesser objects and non-object entities) supported by the application. |
| $lat_choices | (array) | Choices for "latitude" field. Used on the Slides Edition Page. |
| $long_choices | (array) | Choices for "longitude" field. Used on the Slides Edition Page. |
| $quality_choices | (array) | Choices for "shot quality" field. Used on the Slides Edition Page. |
| $regular_latex_struct | (array) | LaTeX hierarchical structure used by the Projects Report Page when the Project has no more than 4 levels in its INXtree structure. |
| $deep_latex_struct | (array) | LaTeX hierarchical structure used by the Projects Report Page when the Project has 5 or more levels in its INXtree structure. |
| $all_severities | (array) | Definition of the different severities used by the Event Log entries, in decreasing order of importance. The log in question can be consulted via the Event Log Viewer. |
| $negINTfinity | -2147483648 | Bottom limit for signed INT data type in MySQL/MariaDB. Used to represent NULL/unspecified dates in JDN format in the 'events' and 'titles' tables for predictable sorting purposes. |
| $DBG_OFF, $DBG_ALGO, $DBG_QUERIES, $DBG_JS, $DBG_ALL | 0, 1, 2, 4, 255 | Definition of the different debugging categories. To
be combined as flags in '$debug' using the bitwise 'OR'
operator (see above). Here is the meaning of each
flag:
|
| $all_dbg_flags | (array) | Naming of the different debugging categories. This array is used on the Database Statistics Page to identify those categories that are currently enabled. |
Please note: Some values (such as $birth_string or $death_string), that used to be defined here, have now been moved to the Translatable Strings File.
The variables below are all defined in support of the perpetual calendar feature and associated functions (such as Julian Day Number or ISO Week number computation). None of them should be altered, except for $J2G_trans (the list of known Julian to Gregorian transition dates) that could be expanded if needed.
Most of the arrays contents has been taken from Ginzel's book, but some come from other sources -- see Bibliography.
| Param | Def. | Description |
|---|---|---|
| $sign_choices | (array) | Supported values for year "sign" drop-down ("ACN/BCE" and "PCN/AD"). |
| $supported_eras | (array) | Supported "eras" (Julian, Gregorian, Transitional). Please refer to Supported Eras for more details. |
| $month_names | (array) | Month names in English. |
| $month_lengths | (array) | Length of each month (regular year). |
| $month_lengths_bis | (array) | Length of each month (leap year). |
| $mnth_strt_off | (array) | Offset of the first day of each month in a continuous day numbering scheme throughout the year (regular year). |
| $mnth_strt_off_lp | (array) | Offset of the first day of each month in a continuous day numbering scheme throughout the year (leap year). |
| $v1, $v2 | (array) | Indexes into the Dominical Letter matrix that follows ($v1 for regular years, $v2 for leap years). |
| $domi_jul | (array) | Dominical Letters for Julian century years. |
| $domi_greg | (array) | Dominical Letters for Gregorian century years. |
| $table_simple, $table_bissex | (array) | Day table (regular years, leap years). |
| $greg_century | (array) | Gregorian calendar centuries used as index into the Dominical Letter matrix that follows. |
| $domi_tab | (array) | Dominical Letter matrix. |
| $jul_domi_tab | (array) | Julian calendar Dominical Letter matrix used by Hirtius for ACN/BCE years only. |
| $J2G_trans | (array) | List of known transitions dates from Julian to Gregorian era, including the geographical region / political area of influence where they applied. Please refer to Supported Eras for more details. |
| $NonaePos | (array) | Day index of the Nonae in the traditional Roman calendar. |
| $IdusPos | (array) | Day index of the Idus in the traditional Roman calendar. |
Project Hirtius, © Les Ateliers du Héron, 2012.
Last updated: Thursday, Aug. 1st, 2024.
| HelpSet Table of Contents | Back to Project Home Page |