Difference between revisions of "GNUrc"
(→Services and modules: wikitable...) |
|||
(96 intermediate revisions by the same user not shown) | |||
Line 80: | Line 80: | ||
;AJAX | ;AJAX | ||
:[https://en.wikipedia.org/wiki/Ajax_%28programming%29 Asynchronous JavaScript and XML] | :[https://en.wikipedia.org/wiki/Ajax_%28programming%29 Asynchronous JavaScript and XML] | ||
+ | |||
+ | = Data format specification = | ||
+ | |||
+ | In this section we document various data types and data formats used within the system. | ||
+ | |||
+ | == Langtag format == | ||
+ | |||
+ | Languages in the i18n subsystem are identified by a value known within the GNUrc system as a "langtag", short for "language tag". | ||
+ | |||
+ | The langtag format is defined by [http://tools.ietf.org/html/rfc5646 RFC-5646, Tags for Identifying Languages]. | ||
+ | |||
+ | See the [https://www.progclub.net/~jj5/webstat/web/index.php?r=langagg webstat langagg report] for examples of encountered Accept-Language HTTP headers. | ||
+ | |||
+ | == Translation content-types == | ||
+ | |||
+ | The translation content-types indicate the type of content in the translation subsystem: | ||
+ | |||
+ | ; <span id="html">html</span> | ||
+ | : Content is HTML content, including HTML elements and HTML entities. HTML content is not preprocessed or converted before inclusion in HTML content. It is assumed to be safe (e.g. no malicious <script> elements, etc...) This type of content cannot be put directly into HTML attributes. | ||
+ | |||
+ | ; <span id="attr">attr</span> | ||
+ | : Content is suitable for use in HTML attributes. I.e. no HTML elements (angle brackets) but HTML entities are supported. Note that attr content may be included in HTML attributes and therefore quote marks (both double and single) should be properly encoded as &quot; and &apos;. This HTML Attribute content is not preprocessed or converted before inclusion in HTML content. It is assumed to be safe (e.g. no malicious <script> elements, etc...) | ||
+ | |||
+ | ; <span id="text">text</span> | ||
+ | : Content is in plain text format. Will be converted to HTML before inclusion in HTML content. This means that no markup is supported by this content type. | ||
+ | |||
+ | ; <span id="safe">safe</span> | ||
+ | : Safe content is textual content that does not contain any HTML element or HTML entity characters, i.e. <, >, and & -- this safe content can be included in other content, particularly HTML content, without HTML or other encoding as it cannot include unsafe characters. | ||
+ | |||
+ | = Database specification = | ||
+ | |||
+ | == Database data types == | ||
+ | |||
+ | You can read more about [https://dev.mysql.com/doc/refman/5.0/en/data-types.html MySQL data types]. | ||
+ | |||
+ | {|class="wikitable" | ||
+ | ! Name | ||
+ | ! MySQL Name | ||
+ | ! Size (Bytes) | ||
+ | ! Min | ||
+ | ! Max | ||
+ | |- | ||
+ | | <span id="ID8">ID8</span> | ||
+ | | TINYINT | ||
+ | | 1 | ||
+ | | -128 | ||
+ | | 127 | ||
+ | |- | ||
+ | | <span id="ID16">ID16</span> | ||
+ | | SMALLINT | ||
+ | | 2 | ||
+ | | -32,768 | ||
+ | | 32,767 | ||
+ | |- | ||
+ | | <span id="ID24">ID24</span> | ||
+ | | MEDIUMINT | ||
+ | | 3 | ||
+ | | -8,388,608 | ||
+ | | 8,388,607 | ||
+ | |- | ||
+ | | <span id="ID32">ID32</span> | ||
+ | | INT | ||
+ | | 4 | ||
+ | | -2,147,483,648 | ||
+ | | 2,147,483,647 | ||
+ | |- | ||
+ | | <span id="ID64">ID64</span> | ||
+ | | BIGINT | ||
+ | | 8 | ||
+ | | -9,223,372,036,854,775,808 | ||
+ | | 9,223,372,036,854,775,807 | ||
+ | |- | ||
+ | | <span id="Bool">Bool</span> | ||
+ | | TINYINT(1) | ||
+ | | 1 | ||
+ | | 0 | ||
+ | | 1 | ||
+ | |- | ||
+ | | <span id="Int8">Int8</span> | ||
+ | | TINYINT | ||
+ | | 1 | ||
+ | | -128 | ||
+ | | 127 | ||
+ | |- | ||
+ | | <span id="UInt8">UInt8</span> | ||
+ | | TINYINT UNSIGNED | ||
+ | | 1 | ||
+ | | 0 | ||
+ | | 255 | ||
+ | |- | ||
+ | | <span id="Int16">Int16</span> | ||
+ | | SMALLINT | ||
+ | | 2 | ||
+ | | -32,768 | ||
+ | | 32,767 | ||
+ | |- | ||
+ | | <span id="UInt16">UInt16</span> | ||
+ | | SMALLINT UNSIGNED | ||
+ | | 2 | ||
+ | | 0 | ||
+ | | 65,535 | ||
+ | |- | ||
+ | | <span id="Int24">Int24</span> | ||
+ | | MEDIUMINT | ||
+ | | 3 | ||
+ | | -8,388,608 | ||
+ | | 8,388,607 | ||
+ | |- | ||
+ | | <span id="UInt24">UInt24</span> | ||
+ | | MEDIUMINT UNSIGNED | ||
+ | | 3 | ||
+ | | 0 | ||
+ | | 16,777,215 | ||
+ | |- | ||
+ | | <span id="Int32">Int32</span> | ||
+ | | INT | ||
+ | | 4 | ||
+ | | -2,147,483,648 | ||
+ | | 2,147,483,647 | ||
+ | |- | ||
+ | | <span id="UInt32">UInt32</span> | ||
+ | | INT UNSIGNED | ||
+ | | 4 | ||
+ | | 0 | ||
+ | | 4,294,967,295 | ||
+ | |- | ||
+ | | <span id="Int64">Int64</span> | ||
+ | | BIGINT | ||
+ | | 8 | ||
+ | | -9,223,372,036,854,775,808 | ||
+ | | 9,223,372,036,854,775,807 | ||
+ | |- | ||
+ | | <span id="UInt64">UInt64</span> | ||
+ | | BIGINT UNSIGNED | ||
+ | | 8 | ||
+ | | 0 | ||
+ | | 18,446,744,073,709,551,615 | ||
+ | |- | ||
+ | | <span id="Single">Single</span> | ||
+ | | FLOAT | ||
+ | | 4 | ||
+ | | | ||
+ | | | ||
+ | |- | ||
+ | | <span id="Double">Double</span> | ||
+ | | DOUBLE | ||
+ | | 8 | ||
+ | | | ||
+ | | | ||
+ | |- | ||
+ | | <span id="Date">Date</span> | ||
+ | | DATE | ||
+ | | 3 | ||
+ | | 1000-01-01 | ||
+ | | 9999-12-31 | ||
+ | |- | ||
+ | | <span id="Time">Time</span> | ||
+ | | TIME | ||
+ | | 3 | ||
+ | | -838:59:59 | ||
+ | | 838:59:59 | ||
+ | |- | ||
+ | | <span id="Datetime">Datetime</span> | ||
+ | | DATETIME | ||
+ | | 8 | ||
+ | | 1000-01-01 00:00:00 | ||
+ | | 9999-12-31 23:59:59 | ||
+ | |- | ||
+ | | <span id="Timestamp">Timestamp</span> | ||
+ | | TIMESTAMP | ||
+ | | 4 | ||
+ | | 1970-01-01 00:00:01 | ||
+ | | 2038-01-19 03:14:07 | ||
+ | |- | ||
+ | | <span id="Char">Char</span> | ||
+ | | CHAR | ||
+ | | | ||
+ | | | ||
+ | | | ||
+ | |- | ||
+ | | <span id="Varchar">Varchar</span> | ||
+ | | VARCHAR | ||
+ | | | ||
+ | | | ||
+ | | | ||
+ | |- | ||
+ | | <span id="Longtext">Longtext</span> | ||
+ | | LONGTEXT | ||
+ | | | ||
+ | | | ||
+ | | | ||
+ | |- | ||
+ | | <span id="Enum">Enum</span> | ||
+ | | ENUM( ..., ... ) | ||
+ | | | ||
+ | | | ||
+ | | | ||
+ | |- | ||
+ | | <span id="Hash">Hash</span> | ||
+ | | CHAR | ||
+ | | 32 | ||
+ | | | ||
+ | | | ||
+ | |} | ||
+ | |||
+ | == Database collations == | ||
+ | |||
+ | We use the following collations for string data. You can read more about [https://dev.mysql.com/doc/refman/5.0/en/charset-general.html MySQL Character Sets and Collations]. | ||
+ | |||
+ | {|class="wikitable" | ||
+ | ! Name | ||
+ | ! MySQL Name | ||
+ | ! Bytes/Char | ||
+ | ! Case-sensitive | ||
+ | ! SQL | ||
+ | |- | ||
+ | | <span id="BINARY">BINARY</span> | ||
+ | | binary | ||
+ | | 1 | ||
+ | | Yes | ||
+ | | character set binary | ||
+ | |- | ||
+ | | <span id="ASCII_BIN">ASCII_BIN</span> | ||
+ | | ascii_bin | ||
+ | | 1 | ||
+ | | Yes | ||
+ | | charset ascii collate ascii_bin | ||
+ | |- | ||
+ | | <span id="ASCII">ASCII</span> | ||
+ | | ascii_general_ci | ||
+ | | 1 | ||
+ | | No | ||
+ | | charset ascii collate ascii_general_ci | ||
+ | |- | ||
+ | | <span id="UTF8_BIN">UTF8_BIN</span> | ||
+ | | utf8_bin | ||
+ | | 3 | ||
+ | | Yes | ||
+ | | charset utf8 collate utf8_bin | ||
+ | |- | ||
+ | | <span id="UTF8">UTF8</span> | ||
+ | | utf8_general_ci | ||
+ | | 3 | ||
+ | | No | ||
+ | | charset utf8 collate utf8_general_ci | ||
+ | |} | ||
+ | |||
+ | == Database tables == | ||
+ | |||
+ | The database has been completely replaced for v2.0. | ||
+ | |||
+ | === v2_exception_log table === | ||
+ | |||
+ | The v2_exception_log table is a registry of unhandled exceptions that have occurred in the application deployment. | ||
+ | |||
+ | {|class="wikitable" | ||
+ | ! Column | ||
+ | ! Type | ||
+ | ! Size | ||
+ | ! Collation | ||
+ | ! Null | ||
+ | ! Default | ||
+ | ! Extra | ||
+ | |- | ||
+ | | <!-- Column: --> id | ||
+ | | <!-- Type: --> [[#ID24|ID24]] | ||
+ | | <!-- Size: --> | ||
+ | | <!-- Collation: --> | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> AUTO_INCREMENT | ||
+ | |- | ||
+ | | <!-- Column: --> timestamp | ||
+ | | <!-- Type: --> [[#Timestamp|Timestamp]] | ||
+ | | <!-- Size: --> | ||
+ | | <!-- Collation: --> | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> CURRENT_TIMESTAMP | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_exception_log.previous_id column|previous_id]] | ||
+ | | <!-- Type: --> [[#ID24|ID24]] | ||
+ | | <!-- Size: --> | ||
+ | | <!-- Collation: --> | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> 0 | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_exception_log.type column|type]] | ||
+ | | <!-- Type: --> [[#Varchar|Varchar]] | ||
+ | | <!-- Size: --> 64 | ||
+ | | <!-- Collation: --> [[#ASCII|ASCII]] | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_exception_log.message column|message]] | ||
+ | | <!-- Type: --> [[#Longtext|Longtext]] | ||
+ | | <!-- Size: --> | ||
+ | | <!-- Collation: --> [[#UTF8|UTF8]] | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_exception_log.code column|code]] | ||
+ | | <!-- Type: --> [[#Int32|Int32]] | ||
+ | | <!-- Size: --> | ||
+ | | <!-- Collation: --> | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> 0 | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_exception_log.const column|const]] | ||
+ | | <!-- Type: --> [[#Varchar|Varchar]] | ||
+ | | <!-- Size: --> 128 | ||
+ | | <!-- Collation: --> [[#ASCII_BIN|ASCII_BIN]] | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_exception_log.file column|file]] | ||
+ | | <!-- Type: --> [[#Varchar|Varchar]] | ||
+ | | <!-- Size: --> 256 | ||
+ | | <!-- Collation: --> [[#ASCII_BIN|ASCII_BIN]] | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_exception_log.line column|line]] | ||
+ | | <!-- Type: --> [[#UInt32|UInt32]] | ||
+ | | <!-- Size: --> | ||
+ | | <!-- Collation: --> | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> 0 | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_exception_log.message_stack column|message_stack]] | ||
+ | | <!-- Type: --> [[#Longtext|Longtext]] | ||
+ | | <!-- Size: --> | ||
+ | | <!-- Collation: --> [[#UTF8|UTF8]] | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_exception_log.trace column|trace]] | ||
+ | | <!-- Type: --> [[#Longtext|Longtext]] | ||
+ | | <!-- Size: --> | ||
+ | | <!-- Collation: --> [[#UTF8|UTF8]] | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_exception_log.trace_data column|trace_data]] | ||
+ | | <!-- Type: --> [[#Longtext|Longtext]] | ||
+ | | <!-- Size: --> | ||
+ | | <!-- Collation: --> [[#UTF8|UTF8]] | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |} | ||
+ | |||
+ | ==== [[#v2_exception_log table|v2_exception_log]].previous_id column ==== | ||
+ | |||
+ | The ID of the previous exception, if any; otherwise zero. | ||
+ | |||
+ | ==== [[#v2_exception_log table|v2_exception_log]].type column ==== | ||
+ | |||
+ | The name of the PHP exception class. | ||
+ | |||
+ | ==== [[#v2_exception_log table|v2_exception_log]].message column ==== | ||
+ | |||
+ | The message of the PHP exception. | ||
+ | |||
+ | ==== [[#v2_exception_log table|v2_exception_log]].code column ==== | ||
+ | |||
+ | The exception code. When -ve values are [[#Declaring error numbers|error numbers]]. | ||
+ | |||
+ | ==== [[#v2_exception_log table|v2_exception_log]].const column ==== | ||
+ | |||
+ | When [[#v2_exception_log.code column|code]] is -ve this field is the ERROR CONST label at the time of the error. See [[#Declaring error numbers|declaring error numbers]] for details of format. | ||
+ | |||
+ | ==== [[#v2_exception_log table|v2_exception_log]].file column ==== | ||
+ | |||
+ | The full path to the PHP file that raised the exception. Note that only ASCII file/path names are supported. | ||
+ | |||
+ | ==== [[#v2_exception_log table|v2_exception_log]].line column ==== | ||
+ | |||
+ | The line number of the expression that raised the exception. | ||
+ | |||
+ | ==== [[#v2_exception_log table|v2_exception_log]].message_stack column ==== | ||
+ | |||
+ | All exception messages in a row. I.e. previous exception messages followed by consequent exception messages. | ||
+ | |||
+ | ==== [[#v2_exception_log table|v2_exception_log]].trace column ==== | ||
+ | |||
+ | The callstack at time of exception as a string with one function call per line. | ||
+ | |||
+ | ==== [[#v2_exception_log table|v2_exception_log]].trace_data column ==== | ||
+ | |||
+ | The callstack at time of exception as a JSON data structure representing the callstack. | ||
+ | |||
+ | === v2_url table === | ||
+ | |||
+ | The URL table stores URLs encountered by the system and indicates if redirection to particular URLs is permitted or not. | ||
+ | |||
+ | {|class="wikitable" | ||
+ | ! Column | ||
+ | ! Type | ||
+ | ! Size | ||
+ | ! Collation | ||
+ | ! Null | ||
+ | ! Default | ||
+ | ! Extra | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_url.hash_column|hash]] | ||
+ | | <!-- Type: --> [[#Char|Char]] | ||
+ | | <!-- Size: --> 40 | ||
+ | | <!-- Collation: --> [[#ASCII|ASCII]] | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_url.url_column|url]] | ||
+ | | <!-- Type: --> [[#Longtext|Longtext]] | ||
+ | | <!-- Size: --> | ||
+ | | <!-- Collation: --> [[#ASCII_BIN|ASCII_BIN]] | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_url.redirect_column|redirect]] | ||
+ | | <!-- Type: --> [[#Bool|Bool]] | ||
+ | | <!-- Size: --> | ||
+ | | <!-- Collation: --> | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> 0 | ||
+ | | <!-- Extra: --> | ||
+ | |} | ||
+ | |||
+ | ==== [[#v2_url table|v2_url]].hash column ==== | ||
+ | |||
+ | The SHA1 hash of the [[#v2_url.url_column|url column]]. | ||
+ | |||
+ | ==== [[#v2_url table|v2_url]].url column ==== | ||
+ | |||
+ | A URL. Supported URL schemes are 'http' and 'https'. | ||
+ | |||
+ | ==== [[#v2_url table|v2_url]].redirect column ==== | ||
+ | |||
+ | True if redirection to the URL is permitted, false otherwise. | ||
+ | |||
+ | === v2_intl_language table === | ||
+ | |||
+ | The v2_intl_language table defines languages supported by the user interface. | ||
+ | |||
+ | {|class="wikitable" | ||
+ | ! Column | ||
+ | ! Type | ||
+ | ! Size | ||
+ | ! Collation | ||
+ | ! Null | ||
+ | ! Default | ||
+ | ! Extra | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_intl_language.langtag_column|langtag]] | ||
+ | | <!-- Type: --> [[#Varchar|Varchar]] | ||
+ | | <!-- Size: --> 64 | ||
+ | | <!-- Collation: --> [[#ASCII|ASCII]] | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_intl_language.fallback_column|fallback]] | ||
+ | | <!-- Type: --> [[#Varchar|Varchar]] | ||
+ | | <!-- Size: --> 64 | ||
+ | | <!-- Collation: --> [[#ASCII|ASCII]] | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> 'en' | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_intl_language.english_name_column|english_name]] | ||
+ | | <!-- Type: --> [[#Varchar|Varchar]] | ||
+ | | <!-- Size: --> 64 | ||
+ | | <!-- Collation: --> [[#UTF8|UTF8]] | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_intl_language.local_name_column|local_name]] | ||
+ | | <!-- Type: --> [[#Varchar|Varchar]] | ||
+ | | <!-- Size: --> 64 | ||
+ | | <!-- Collation: --> [[#UTF8|UTF8]] | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_intl_language.active_column|active]] | ||
+ | | <!-- Type: --> [[#Bool|Bool]] | ||
+ | | <!-- Size: --> | ||
+ | | <!-- Collation: --> | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> 0 | ||
+ | | <!-- Extra: --> | ||
+ | |} | ||
+ | |||
+ | ==== [[#v2_intl_language table|v2_intl_language]].langtag column ==== | ||
+ | |||
+ | A language identifier in [[#Langtag format|langtag format]]. | ||
+ | |||
+ | ==== [[#v2_intl_language table|v2_intl_language]].fallback column ==== | ||
+ | |||
+ | A language identifier in [[#Langtag format|langtag format]] that indicates the 'fallback' translation for this language. That is, which translation will be used if there is no translation for the current language. The default value is 'en', which means fall back to the default English content. | ||
+ | |||
+ | ==== [[#v2_intl_language table|v2_intl_language]].english_name column ==== | ||
+ | |||
+ | The name of this language, in English. | ||
+ | |||
+ | ==== [[#v2_intl_language table|v2_intl_language]].local_name column ==== | ||
+ | |||
+ | The name of this language, in its own language. | ||
+ | |||
+ | ==== [[#v2_intl_language table|v2_intl_language]].active column ==== | ||
+ | |||
+ | True if language is available in the user-interface, false otherwise. Languages are created as deactivated during development and after translation is complete the language is activated making it a language available to users. | ||
+ | |||
+ | === v2_intl_context table === | ||
+ | |||
+ | The v2_intl_context table defines message contexts for use in translation. | ||
+ | |||
+ | {|class="wikitable" | ||
+ | ! Column | ||
+ | ! Type | ||
+ | ! Size | ||
+ | ! Collation | ||
+ | ! Null | ||
+ | ! Default | ||
+ | ! Extra | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_intl_context.context_column|context]] | ||
+ | | <!-- Type: --> [[#Varchar|Varchar]] | ||
+ | | <!-- Size: --> 64 | ||
+ | | <!-- Collation: --> [[#ASCII|ASCII]] | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_intl_context.seq_column|seq]] | ||
+ | | <!-- Type: --> [[#Int24|Int24]] | ||
+ | | <!-- Size: --> | ||
+ | | <!-- Collation: --> | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |} | ||
+ | |||
+ | ==== [[#v2_intl_context table|v2_intl_context]].context column ==== | ||
+ | |||
+ | The name of the translation context. | ||
+ | |||
+ | ==== [[#v2_intl_context table|v2_intl_context]].seq column ==== | ||
+ | |||
+ | The order of this record, i.e. its sequence. | ||
+ | |||
+ | === v2_intl_message table === | ||
+ | |||
+ | The v2_intl_message table supports ''messages'' which are English language content available for translation. | ||
+ | |||
+ | {|class="wikitable" | ||
+ | ! Column | ||
+ | ! Type | ||
+ | ! Size | ||
+ | ! Collation | ||
+ | ! Null | ||
+ | ! Default | ||
+ | ! Extra | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_intl_message.type_column|type]] | ||
+ | | <!-- Type: --> [[#Enum|Enum]]( [[#html|html]], [[#attr|attr]], [[#text|text]], [[#safe|safe]] ) | ||
+ | | <!-- Size: --> 4 | ||
+ | | <!-- Collation: --> | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_intl_message.context_column|context]] | ||
+ | | <!-- Type: --> [[#Varchar|Varchar]] | ||
+ | | <!-- Size: --> 64 | ||
+ | | <!-- Collation: --> [[#ASCII|ASCII]] | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_intl_message.hash_column|hash]] | ||
+ | | <!-- Type: --> [[#Hash|Hash]] | ||
+ | | <!-- Size: --> 32 | ||
+ | | <!-- Collation: --> [[#ASCII|ASCII]] | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_intl_message.content_column|content]] | ||
+ | | <!-- Type: --> [[#Longtext|Longtext]] | ||
+ | | <!-- Size: --> | ||
+ | | <!-- Collation: --> [[#UTF8|UTF8]] | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_intl_message.seq_column|seq]] | ||
+ | | <!-- Type: --> [[#ID24|ID24]] | ||
+ | | <!-- Size: --> | ||
+ | | <!-- Collation: --> | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> AUTO_INCREMENT | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_intl_message.words_column|seq]] | ||
+ | | <!-- Type: --> [[#UInt24|UInt24]] | ||
+ | | <!-- Size: --> | ||
+ | | <!-- Collation: --> | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |} | ||
+ | |||
+ | ==== [[#v2_intl_message table|v2_intl_message]].type column ==== | ||
+ | |||
+ | The message's [[#Translation_content-types|translation content-types]]. I.e. [[#html|html]], [[#attr|attr]], [[#text|text]], [[#safe|safe]]. | ||
+ | |||
+ | ==== [[#v2_intl_message table|v2_intl_message]].context column ==== | ||
+ | |||
+ | The message's ''message context''. Message contexts are a label that indicates the context of a message. For example the message contexts 'Nationality' and 'Language' could be used as the context for the message 'Japanese'; without contexts messages might be ambiguous. | ||
+ | |||
+ | ==== [[#v2_intl_message table|v2_intl_message]].hash column ==== | ||
+ | |||
+ | The message's hash is an MD5 hash of the normalized content. See [[#v2_intl_message.message_column|below]] for an explanation of the normalization process. | ||
+ | |||
+ | ==== [[#v2_intl_message table|v2_intl_message]].content column ==== | ||
+ | |||
+ | The message's ''content'' is a normalized English message available for translation. Normalization is the process of removing leading and trailing whitespace and converting duplicate space characters into a single space character. Message content is normalized before being hashed and/or stored. | ||
+ | |||
+ | ==== [[#v2_intl_message table|v2_intl_message]].seq column ==== | ||
+ | |||
+ | This is an auto-increment field which indicates the sequence the message contents was inserted. | ||
+ | |||
+ | ==== [[#v2_intl_message table|v2_intl_message]].words column ==== | ||
+ | |||
+ | The words column stores the number of English words in the message content. | ||
+ | |||
+ | === v2_intl_translation table === | ||
+ | |||
+ | The v2_intl_translation table contains native language translations of message content. | ||
+ | |||
+ | {|class="wikitable" | ||
+ | ! Column | ||
+ | ! Type | ||
+ | ! Size | ||
+ | ! Collation | ||
+ | ! Null | ||
+ | ! Default | ||
+ | ! Extra | ||
+ | |- | ||
+ | | <!-- Column: --> [[#v2_intl_translation.langtag_column|langtag]] | ||
+ | | <!-- Type: --> [[#Varchar|Varchar]] | ||
+ | | <!-- Size: --> 64 | ||
+ | | <!-- Collation: --> [[#ASCII|ASCII]] | ||
+ | | <!-- Null: --> No | ||
+ | | <!-- Default: --> | ||
+ | | <!-- Extra: --> | ||
+ | |} | ||
+ | |||
+ | ==== [[#v2_intl_translation table|v2_intl_translation]].langtag column ==== | ||
+ | |||
+ | A language identifier in [[#Langtag format|langtag format]]. | ||
= Functional specification = | = Functional specification = | ||
Line 85: | Line 759: | ||
The functional specification describes what the project does. | The functional specification describes what the project does. | ||
− | == Administration | + | == Administration features == |
− | + | === Administration dashboard === | |
− | # User administration | + | The administration dashboard ([[#admin-home.php|admin-home.php]]) is an administrator's home page. From the administration dashboard an administrator can access: |
− | # | + | |
− | # Group administration | + | # [[#User administration|User administration]] |
− | # Error reporting | + | # [[#Translation administration|Translation administration]] |
+ | # [[#Group administration|Group administration]] | ||
+ | # [[#Error reporting|Error reporting]] | ||
=== User administration === | === User administration === | ||
− | === | + | === Translation administration === |
=== Group administration === | === Group administration === | ||
Line 102: | Line 778: | ||
=== Error reporting === | === Error reporting === | ||
− | == | + | == Translation features == |
− | == | + | == Standard features == |
== Role-based security == | == Role-based security == | ||
Line 119: | Line 795: | ||
The i18n functional spec is documented on the [https://www.gnurc.com/dev/jj5-mvc/intl-help.php Language Administration Help] page. | The i18n functional spec is documented on the [https://www.gnurc.com/dev/jj5-mvc/intl-help.php Language Administration Help] page. | ||
+ | |||
+ | == Backend features == | ||
+ | |||
+ | === Error logging === | ||
+ | |||
+ | ==== Error log testing ==== | ||
= Technical specification = | = Technical specification = | ||
Line 170: | Line 852: | ||
|} | |} | ||
− | Each | + | Each layer depends on (up to) all of the previous layers. So controllers use views, BOM, ORM, DAL, objects, and libraries. Views use BOM, ORM, DAL, objects, and libraries. The BOM uses the ORM, DAL, objects, and libraries. And so on. Generally controllers should call on the services of the BOM rather than calling on the services of the DAL directly, so the BOM encapsulates business logic and mediates it into the DAL. If higher layers can encapsulate functionality in lower layers that is a good thing to do. |
== Services and modules == | == Services and modules == | ||
Line 178: | Line 860: | ||
The idea of software modules is to split functionality into parts which can be managed by one developer at a time. For example consider the Data Access Layer (DAL) service. We could have one DAL object that had methods for manipulating thermostats, users, and groups. The problem is that if Miguel is working on thermostats and Federico is working on users, if they both edit the single DAL class then they run the risk of overwriting each others' work. By splitting functionality for thermostats, users, and groups into DAL modules each of our developers can work on their modules without interfering with code used by other developers. | The idea of software modules is to split functionality into parts which can be managed by one developer at a time. For example consider the Data Access Layer (DAL) service. We could have one DAL object that had methods for manipulating thermostats, users, and groups. The problem is that if Miguel is working on thermostats and Federico is working on users, if they both edit the single DAL class then they run the risk of overwriting each others' work. By splitting functionality for thermostats, users, and groups into DAL modules each of our developers can work on their modules without interfering with code used by other developers. | ||
− | So "services" are an interface into a collection of modules, and "modules" are a bunch of functionality implemented by one developer. | + | So "services" are an interface into a collection of modules, and "modules" are a bunch of features/functionality implemented by one developer at a time. |
The software module pattern is employed by the following services: | The software module pattern is employed by the following services: | ||
Line 186: | Line 868: | ||
! Modules | ! Modules | ||
|- | |- | ||
− | | DAL | + | | [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/3-dal/mysql-pdo/GrcDal.php?root=remotecontrol&view=markup DAL] |
− | | [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/3-dal/mysql-pdo/module/?root=remotecontrol /src/3-dal/ | + | | [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/3-dal/mysql-pdo/module/?root=remotecontrol /src/3-dal/*/module] |
|- | |- | ||
− | | BOM | + | | [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/5-bom/GrcBom.php?root=remotecontrol&view=markup BOM] |
| [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/5-bom/module/?root=remotecontrol /src/5-bom/module] | | [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/5-bom/module/?root=remotecontrol /src/5-bom/module] | ||
|- | |- | ||
− | | AJAX Controller | + | | [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/7-ajax/GrcAjax.php?root=remotecontrol&view=markup AJAX Controller] |
| [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/7-ajax/module/?root=remotecontrol /src/7-ajax/module] | | [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/7-ajax/module/?root=remotecontrol /src/7-ajax/module] | ||
|- | |- | ||
Line 287: | Line 969: | ||
* [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/2-obj/GrcMessage.php?root=remotecontrol&view=markup GrcMessage.php] -- a class for declaring system messages (and aiding their translation). | * [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/2-obj/GrcMessage.php?root=remotecontrol&view=markup GrcMessage.php] -- a class for declaring system messages (and aiding their translation). | ||
* [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/2-obj/GrcPageLinks.php?root=remotecontrol&view=markup GrcPageLinks.php] -- a class for modelling page links, e.g. first/last/next/previous/size=N/etc. | * [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/2-obj/GrcPageLinks.php?root=remotecontrol&view=markup GrcPageLinks.php] -- a class for modelling page links, e.g. first/last/next/previous/size=N/etc. | ||
+ | * [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/2-obj/GrcService.php?root=remotecontrol&view=markup GrcService.php] -- an object for composing modules. | ||
* [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/2-obj/GrcTableView.php?root=remotecontrol&view=markup GrcTableView.php] -- a class for rendering tabular data as HTML. | * [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/2-obj/GrcTableView.php?root=remotecontrol&view=markup GrcTableView.php] -- a class for rendering tabular data as HTML. | ||
* [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/2-obj/GrcUrl.php?root=remotecontrol&view=markup GrcUrl.php] -- an API for modelling URLs. | * [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/2-obj/GrcUrl.php?root=remotecontrol&view=markup GrcUrl.php] -- an API for modelling URLs. | ||
Line 296: | Line 979: | ||
* [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/3-dal/GrcDal.php?root=remotecontrol&view=markup GrcDal.php] -- the include file for the Data Access Layer; defaults to MySQL/PDO API. | * [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/3-dal/GrcDal.php?root=remotecontrol&view=markup GrcDal.php] -- the include file for the Data Access Layer; defaults to MySQL/PDO API. | ||
+ | * [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/3-dal/GrcDalModule.php?root=remotecontrol&view=markup GrcDalModule.php] -- a base class for DAL Modules. | ||
===== [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/3-dal/mysql-pdo/?root=remotecontrol /src/3-dal/mysql-pdo] ===== | ===== [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/3-dal/mysql-pdo/?root=remotecontrol /src/3-dal/mysql-pdo] ===== | ||
Line 303: | Line 987: | ||
====== [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/3-dal/mysql-pdo/module/?root=remotecontrol /src/3-dal/mysql-pdo/module] ====== | ====== [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/3-dal/mysql-pdo/module/?root=remotecontrol /src/3-dal/mysql-pdo/module] ====== | ||
− | The [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/3-dal/mysql-pdo/module/?root=remotecontrol /src/3-dal/mysql-pdo/module] | + | The [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/3-dal/mysql-pdo/module/?root=remotecontrol /src/3-dal/mysql-pdo/module] directory contains DAL [[#Services and modules|modules]]. |
==== [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/4-orm/?root=remotecontrol /src/4-orm] ==== | ==== [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/4-orm/?root=remotecontrol /src/4-orm] ==== | ||
+ | |||
+ | The [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/4-orm/?root=remotecontrol /src/4-orm] directory contains Object/Relational Mappers. The ORM strategy that we employ is known as the [https://en.wikipedia.org/wiki/Active_record_pattern Active Record pattern]. An Active Record is a class that mediates data between the program (a PHP object) and the database (a record in a table). As a general rule (which can be broken) the Active Record is supposed to be [https://en.wikipedia.org/wiki/Create,_read,_update_and_delete CRUD] only, any other business logic and/or validation should be implemented as a business process in the Business Object Model. | ||
+ | |||
+ | * [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/4-orm/GrcUser.php?root=remotecontrol&view=markup GrcUser] | ||
==== [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/5-bom/?root=remotecontrol /src/5-bom] ==== | ==== [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/5-bom/?root=remotecontrol /src/5-bom] ==== | ||
+ | |||
+ | The [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/5-bom/?root=remotecontrol /src/5-bom] directory contains an interface into "business process" via the Business Object Model (GrcBom): | ||
+ | |||
+ | * [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/5-bom/GrcBom.php?root=remotecontrol&view=markup GrcBom] -- the business process interface | ||
+ | |||
+ | ===== [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/5-bom/module/?root=remotecontrol /src/5-bom/module] ===== | ||
+ | |||
+ | The [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/5-bom/module/?root=remotecontrol /src/5-bom/module] directory contains business process modules accessed via the BOM. | ||
+ | |||
+ | * [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/5-bom/module/GrcBomUser.php?root=remotecontrol&view=markup GrcBomUser] | ||
==== [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/6-view/?root=remotecontrol /src/6-view] ==== | ==== [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/6-view/?root=remotecontrol /src/6-view] ==== | ||
+ | |||
+ | The [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/6-view/?root=remotecontrol /src/6-view] directory contains libraries of helper functions for view composition: | ||
+ | |||
+ | * [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/6-view/header.php?root=remotecontrol&view=markup header.php] -- HTML header. | ||
+ | * [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/6-view/footer.php?root=remotecontrol&view=markup footer.php] -- HTML footer. | ||
+ | * [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/6-view/library.php?root=remotecontrol&view=markup library.php] -- miscellaneous view components. | ||
==== [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/7-ajax/?root=remotecontrol /src/7-ajax] ==== | ==== [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/7-ajax/?root=remotecontrol /src/7-ajax] ==== | ||
The [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/7-ajax/?root=remotecontrol /src/7-ajax] directory contains AJAX controllers. | The [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/7-ajax/?root=remotecontrol /src/7-ajax] directory contains AJAX controllers. | ||
+ | |||
+ | * [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/7-ajax/GrcAjax.php?root=remotecontrol&view=markup GrcAjax] -- a service interface into AJAX operations (modules) | ||
+ | |||
+ | ===== [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/7-ajax/module/?root=remotecontrol /src/7-ajax/module] ===== | ||
+ | |||
+ | The [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/7-ajax/module/?root=remotecontrol /src/7-ajax/module] directory contains AJAX modules exposed by the GrcAjax service. | ||
+ | |||
+ | === [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/test/?root=remotecontrol /test] === | ||
+ | |||
+ | The [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/test/?root=remotecontrol /test] directory contains Unit Tests for the project. | ||
+ | |||
+ | ==== [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/test/php/?root=remotecontrol /test/php] ==== | ||
+ | |||
+ | The [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/test/php/?root=remotecontrol /test/php] directory contains test cases that demonstrate a PHP feature. | ||
+ | |||
+ | ==== [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/test/src/?root=remotecontrol /test/src] ==== | ||
+ | |||
+ | The [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/test/src/?root=remotecontrol /test/src] directory contains test cases that test a program feature. | ||
=== [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/web/?root=remotecontrol /web] === | === [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/web/?root=remotecontrol /web] === | ||
+ | |||
+ | The [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/web/?root=remotecontrol /web] directory contains front-facing components. Those are components which are accessible via HTTP(S). Each PHP file in the /web directory is known as a Page Controller. In addition to Page Controllers the /web directory includes: | ||
+ | |||
+ | * [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/web/images/?root=remotecontrol images] -- Graphics. | ||
+ | * [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/web/scripts/?root=remotecontrol scripts] -- JavaScript files. | ||
+ | * [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/web/styles/?root=remotecontrol styles] -- CSS files. | ||
== Managing errors == | == Managing errors == | ||
Line 388: | Line 1,116: | ||
In addition to the above API the [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/2-obj/GrcHtmlElement.php?root=remotecontrol&view=markup HTML composition system] supports automatic translation of content via the following methods: | In addition to the above API the [http://svn.savannah.gnu.org/viewvc/branches/development/jj5-mvc/src/2-obj/GrcHtmlElement.php?root=remotecontrol&view=markup HTML composition system] supports automatic translation of content via the following methods: | ||
− | * GrcHtmlElement->add_nbsp: add HTML after converting spaces to <nowiki> </nowiki> | + | * GrcHtmlElement->add_nbsp: add HTML after converting spaces to <nowiki>&nbsp;</nowiki> |
* GrcHtmlElement->add_html: add HTML content (no escaping) | * GrcHtmlElement->add_html: add HTML content (no escaping) | ||
* GrcHtmlElement->add_h01n: add HTML 01n paradigm | * GrcHtmlElement->add_h01n: add HTML 01n paradigm | ||
Line 413: | Line 1,141: | ||
If you're looking to set up a development environment for this project here's what you need to know: | If you're looking to set up a development environment for this project here's what you need to know: | ||
+ | |||
+ | === Setting up a development environment === | ||
+ | |||
+ | $ svn co svn+ssh://USERNAME@svn.savannah.gnu.org/remotecontrol/branches/development/jj5-mvc gnurc-jj5-mvc | ||
+ | |||
+ | Note: substitute USERNAME with your Savannah username. Make sure your firewall has ports 22 and 3690 open. | ||
+ | |||
+ | $ cd gnurc-jj5-mvc | ||
+ | $ cp config.example.php config.php | ||
= Tasks = | = Tasks = | ||
Line 423: | Line 1,160: | ||
* Generate task list | * Generate task list | ||
* Allocate tasks to developers | * Allocate tasks to developers | ||
− | |||
− | |||
== Done == | == Done == | ||
Line 430: | Line 1,165: | ||
Stuff that's done. Latest stuff on top. | Stuff that's done. Latest stuff on top. | ||
+ | * [[User:John|JE]] 2015-05-07: database specification progress | ||
* [[User:John|JE]] 2015-04-01: created project page | * [[User:John|JE]] 2015-04-01: created project page |
Latest revision as of 15:13, 11 December 2017
GNUrc is the GNU Remote Control software. That's the software that aids in the maintenance of your thermostats. For other projects see projects.
Status
v1.1 released, v2.0 under development.
Motivation
To seek operational efficiencies in air-conditioners thereby saving electricity and improving comfort.
Administration
Contributors
Members who have contributed to this project. Newest on top.
All contributors have agreed to the terms of the Contributor License Agreement. This excludes any upstream contributors who tend to have different administrative frameworks.
Upstream (GNU) contributors: GNU Remote Control Contributors
Copyright
Copyright 2015, Contributors.
License
Licensed under the AGPL.
Resources
Downloads
See the home page for downloads.
Source code
See the home page for source code.
Links
- www.gnurc.com, the GNUrc developer portal
Jargon
Following are definitions for abbreviations and acronyms that we use:
- i18n
- intl
- Internationalization/translation
Data format specification
In this section we document various data types and data formats used within the system.
Langtag format
Languages in the i18n subsystem are identified by a value known within the GNUrc system as a "langtag", short for "language tag".
The langtag format is defined by RFC-5646, Tags for Identifying Languages.
See the webstat langagg report for examples of encountered Accept-Language HTTP headers.
Translation content-types
The translation content-types indicate the type of content in the translation subsystem:
- html
- Content is HTML content, including HTML elements and HTML entities. HTML content is not preprocessed or converted before inclusion in HTML content. It is assumed to be safe (e.g. no malicious <script> elements, etc...) This type of content cannot be put directly into HTML attributes.
- attr
- Content is suitable for use in HTML attributes. I.e. no HTML elements (angle brackets) but HTML entities are supported. Note that attr content may be included in HTML attributes and therefore quote marks (both double and single) should be properly encoded as " and '. This HTML Attribute content is not preprocessed or converted before inclusion in HTML content. It is assumed to be safe (e.g. no malicious <script> elements, etc...)
- text
- Content is in plain text format. Will be converted to HTML before inclusion in HTML content. This means that no markup is supported by this content type.
- safe
- Safe content is textual content that does not contain any HTML element or HTML entity characters, i.e. <, >, and & -- this safe content can be included in other content, particularly HTML content, without HTML or other encoding as it cannot include unsafe characters.
Database specification
Database data types
You can read more about MySQL data types.
Name | MySQL Name | Size (Bytes) | Min | Max |
---|---|---|---|---|
ID8 | TINYINT | 1 | -128 | 127 |
ID16 | SMALLINT | 2 | -32,768 | 32,767 |
ID24 | MEDIUMINT | 3 | -8,388,608 | 8,388,607 |
ID32 | INT | 4 | -2,147,483,648 | 2,147,483,647 |
ID64 | BIGINT | 8 | -9,223,372,036,854,775,808 | 9,223,372,036,854,775,807 |
Bool | TINYINT(1) | 1 | 0 | 1 |
Int8 | TINYINT | 1 | -128 | 127 |
UInt8 | TINYINT UNSIGNED | 1 | 0 | 255 |
Int16 | SMALLINT | 2 | -32,768 | 32,767 |
UInt16 | SMALLINT UNSIGNED | 2 | 0 | 65,535 |
Int24 | MEDIUMINT | 3 | -8,388,608 | 8,388,607 |
UInt24 | MEDIUMINT UNSIGNED | 3 | 0 | 16,777,215 |
Int32 | INT | 4 | -2,147,483,648 | 2,147,483,647 |
UInt32 | INT UNSIGNED | 4 | 0 | 4,294,967,295 |
Int64 | BIGINT | 8 | -9,223,372,036,854,775,808 | 9,223,372,036,854,775,807 |
UInt64 | BIGINT UNSIGNED | 8 | 0 | 18,446,744,073,709,551,615 |
Single | FLOAT | 4 | ||
Double | DOUBLE | 8 | ||
Date | DATE | 3 | 1000-01-01 | 9999-12-31 |
Time | TIME | 3 | -838:59:59 | 838:59:59 |
Datetime | DATETIME | 8 | 1000-01-01 00:00:00 | 9999-12-31 23:59:59 |
Timestamp | TIMESTAMP | 4 | 1970-01-01 00:00:01 | 2038-01-19 03:14:07 |
Char | CHAR | |||
Varchar | VARCHAR | |||
Longtext | LONGTEXT | |||
Enum | ENUM( ..., ... ) | |||
Hash | CHAR | 32 |
Database collations
We use the following collations for string data. You can read more about MySQL Character Sets and Collations.
Name | MySQL Name | Bytes/Char | Case-sensitive | SQL |
---|---|---|---|---|
BINARY | binary | 1 | Yes | character set binary |
ASCII_BIN | ascii_bin | 1 | Yes | charset ascii collate ascii_bin |
ASCII | ascii_general_ci | 1 | No | charset ascii collate ascii_general_ci |
UTF8_BIN | utf8_bin | 3 | Yes | charset utf8 collate utf8_bin |
UTF8 | utf8_general_ci | 3 | No | charset utf8 collate utf8_general_ci |
Database tables
The database has been completely replaced for v2.0.
v2_exception_log table
The v2_exception_log table is a registry of unhandled exceptions that have occurred in the application deployment.
Column | Type | Size | Collation | Null | Default | Extra |
---|---|---|---|---|---|---|
id | ID24 | No | AUTO_INCREMENT | |||
timestamp | Timestamp | No | CURRENT_TIMESTAMP | |||
previous_id | ID24 | No | 0 | |||
type | Varchar | 64 | ASCII | No | ||
message | Longtext | UTF8 | No | |||
code | Int32 | No | 0 | |||
const | Varchar | 128 | ASCII_BIN | No | ||
file | Varchar | 256 | ASCII_BIN | No | ||
line | UInt32 | No | 0 | |||
message_stack | Longtext | UTF8 | No | |||
trace | Longtext | UTF8 | No | |||
trace_data | Longtext | UTF8 | No |
v2_exception_log.previous_id column
The ID of the previous exception, if any; otherwise zero.
v2_exception_log.type column
The name of the PHP exception class.
v2_exception_log.message column
The message of the PHP exception.
v2_exception_log.code column
The exception code. When -ve values are error numbers.
v2_exception_log.const column
When code is -ve this field is the ERROR CONST label at the time of the error. See declaring error numbers for details of format.
v2_exception_log.file column
The full path to the PHP file that raised the exception. Note that only ASCII file/path names are supported.
v2_exception_log.line column
The line number of the expression that raised the exception.
v2_exception_log.message_stack column
All exception messages in a row. I.e. previous exception messages followed by consequent exception messages.
v2_exception_log.trace column
The callstack at time of exception as a string with one function call per line.
v2_exception_log.trace_data column
The callstack at time of exception as a JSON data structure representing the callstack.
v2_url table
The URL table stores URLs encountered by the system and indicates if redirection to particular URLs is permitted or not.
Column | Type | Size | Collation | Null | Default | Extra |
---|---|---|---|---|---|---|
hash | Char | 40 | ASCII | No | ||
url | Longtext | ASCII_BIN | No | |||
redirect | Bool | No | 0 |
v2_url.hash column
The SHA1 hash of the url column.
v2_url.url column
A URL. Supported URL schemes are 'http' and 'https'.
v2_url.redirect column
True if redirection to the URL is permitted, false otherwise.
v2_intl_language table
The v2_intl_language table defines languages supported by the user interface.
Column | Type | Size | Collation | Null | Default | Extra |
---|---|---|---|---|---|---|
langtag | Varchar | 64 | ASCII | No | ||
fallback | Varchar | 64 | ASCII | No | 'en' | |
english_name | Varchar | 64 | UTF8 | No | ||
local_name | Varchar | 64 | UTF8 | No | ||
active | Bool | No | 0 |
v2_intl_language.langtag column
A language identifier in langtag format.
v2_intl_language.fallback column
A language identifier in langtag format that indicates the 'fallback' translation for this language. That is, which translation will be used if there is no translation for the current language. The default value is 'en', which means fall back to the default English content.
v2_intl_language.english_name column
The name of this language, in English.
v2_intl_language.local_name column
The name of this language, in its own language.
v2_intl_language.active column
True if language is available in the user-interface, false otherwise. Languages are created as deactivated during development and after translation is complete the language is activated making it a language available to users.
v2_intl_context table
The v2_intl_context table defines message contexts for use in translation.
Column | Type | Size | Collation | Null | Default | Extra |
---|---|---|---|---|---|---|
context | Varchar | 64 | ASCII | No | ||
seq | Int24 | No |
v2_intl_context.context column
The name of the translation context.
v2_intl_context.seq column
The order of this record, i.e. its sequence.
v2_intl_message table
The v2_intl_message table supports messages which are English language content available for translation.
Column | Type | Size | Collation | Null | Default | Extra |
---|---|---|---|---|---|---|
type | Enum( html, attr, text, safe ) | 4 | No | |||
context | Varchar | 64 | ASCII | No | ||
hash | Hash | 32 | ASCII | No | ||
content | Longtext | UTF8 | No | |||
seq | ID24 | No | AUTO_INCREMENT | |||
seq | UInt24 | No |
v2_intl_message.type column
The message's translation content-types. I.e. html, attr, text, safe.
v2_intl_message.context column
The message's message context. Message contexts are a label that indicates the context of a message. For example the message contexts 'Nationality' and 'Language' could be used as the context for the message 'Japanese'; without contexts messages might be ambiguous.
v2_intl_message.hash column
The message's hash is an MD5 hash of the normalized content. See below for an explanation of the normalization process.
v2_intl_message.content column
The message's content is a normalized English message available for translation. Normalization is the process of removing leading and trailing whitespace and converting duplicate space characters into a single space character. Message content is normalized before being hashed and/or stored.
v2_intl_message.seq column
This is an auto-increment field which indicates the sequence the message contents was inserted.
v2_intl_message.words column
The words column stores the number of English words in the message content.
v2_intl_translation table
The v2_intl_translation table contains native language translations of message content.
Column | Type | Size | Collation | Null | Default | Extra |
---|---|---|---|---|---|---|
langtag | Varchar | 64 | ASCII | No |
v2_intl_translation.langtag column
A language identifier in langtag format.
Functional specification
The functional specification describes what the project does.
Administration features
Administration dashboard
The administration dashboard (admin-home.php) is an administrator's home page. From the administration dashboard an administrator can access:
User administration
Translation administration
Group administration
Error reporting
Translation features
Standard features
Role-based security
We use role-based security to limit system functions to particular classes of users. There are three user roles and any given user can be in any combination of the roles:
- Administrator
- Translator
- Standard
Administrators have access to administration functions. Non-administrators do not have access to administration functions. Translators have access to translation functions. Non-translators do not have access to translation functions. All users have access to the standard functions.
Internationalization
The i18n functional spec is documented on the Language Administration Help page.
Backend features
Error logging
Error log testing
Technical specification
The technical specification describes how the project works.
Model-view-controller
GNUrc 2.0 implements the Model-View-Controller (MVC) design pattern.
Software layers
The GNUrc software is layered:
Layer | Directory | MVC role |
---|---|---|
Function Libraries | /src/1-lib | |
Objects | /src/2-obj | Model/View |
Data Access Layer (DAL) | /src/3-dal | Model |
Object/Relational Mapping (ORM) | /src/4-orm | Model |
Business Object Model (BOM) | /src/5-bom | Model |
View helpers | /src/6-view | View |
Ajax Controllers | /src/7-ajax | Controller |
Page Controllers | /web | Controller |
Each layer depends on (up to) all of the previous layers. So controllers use views, BOM, ORM, DAL, objects, and libraries. Views use BOM, ORM, DAL, objects, and libraries. The BOM uses the ORM, DAL, objects, and libraries. And so on. Generally controllers should call on the services of the BOM rather than calling on the services of the DAL directly, so the BOM encapsulates business logic and mediates it into the DAL. If higher layers can encapsulate functionality in lower layers that is a good thing to do.
Services and modules
In order to facilitate a team of developers working on the code base at the same time we implement a software module pattern. Note that this is a "political" rather than "technical" or "logical" categorisation of functionality. We separate our code into modules that developers can "own" while they're working on the project. The idea is to avoid changing files that other developers are working on so as to reduce conflicts.
The idea of software modules is to split functionality into parts which can be managed by one developer at a time. For example consider the Data Access Layer (DAL) service. We could have one DAL object that had methods for manipulating thermostats, users, and groups. The problem is that if Miguel is working on thermostats and Federico is working on users, if they both edit the single DAL class then they run the risk of overwriting each others' work. By splitting functionality for thermostats, users, and groups into DAL modules each of our developers can work on their modules without interfering with code used by other developers.
So "services" are an interface into a collection of modules, and "modules" are a bunch of features/functionality implemented by one developer at a time.
The software module pattern is employed by the following services:
Service | Modules |
---|---|
DAL | /src/3-dal/*/module |
BOM | /src/5-bom/module |
AJAX Controller | /src/7-ajax/module |
Page Controller | /web |
Directory structure
The software has the following directory structure starting in the base:
/
The base directory is /path/to/your/gnurc.
- .svn-ignore -- files for Subversion (svn) to ignore
- e.g.: $ svn propset svn:ignore -RF .svn-ignore .
- config.example.php -- an example config file
- config.php -- the production config file
- e.g.: $ cp config.example.php config.php; vim config.php
/dat
The /dat directory is for data files.
- lang.dat -- the language subtag registry
- lang.ser -- the serialized PHP data-structure of the processed lang.dat file.
/etc
The /etc directory is for miscellaneous scripts.
- download-language-data.sh -- downloads the lang.dat file
/etc/dbscripts
The /etc/dbscripts directory is an svn:externals for the database scripts:
svn://svn.sv.gnu.org/remotecontrol/branches/development/dbscripts
- .svn-ignore -- files for Subversion (svn) to ignore
- .svn-ignore.sh -- a script to apply the svn-ignore settings.
- README.md -- the README file for the dbscripts.
- gnurc-db.sql -- a script to create a "gnurc" database.
- gnurc-schema.sql -- a script to apply the GNUrc schema to the 'current' database.
- gnurc-data.sql -- a script to insert default/global data.
- gnurc-test.sql -- a script to load test data.
- make-db.sh -- a script to create/upgrade a GNUrc database.
/src
The /src directory is for most of the source code.
- include.php -- the main include file for loading the GNUrc software components.
- test.php -- the main include file for use by PHPUnit unit tests.
/src/1-lib
The /src/1-lib directory contains function libraries.
- 01-api.php -- an API for singletons and helper methods.
- 02-constants.php -- constants definitions.
- 20-array.php -- functions for working with arrays.
- 25-types.php -- functions for determining data types.
- 29-conversion.php -- functions for converting values.
- 30-formatting.php -- functions for formatting data.
- 35-validation.php -- functions for validating data.
- 37-defaults.php -- default settings.
- 40-late-constants.php -- late message and error definitions.
- 45-intl.php -- i18n helper functions/API.
- 55-calc.php -- functions for calculating.
- 60-html.php -- functions for working with HTML.
- 65-http.php -- functions for working with HTTP.
- 70-comparison.php -- comparison functions.
- 75-logic.php -- miscellaneous program logic.
- 80-datetime.php -- functions for working with dates and times.
- 98-handlers.php -- functions for error and exception handling.
- 99-screen.php -- global program logic.
/src/2-obj
The /src/2-obj directory contains PHP classes used by GNUrc that do not fit in another category.
- GrcDataPage.php -- represents and manipulates pagination settings.
- GrcDataSort.php -- represents and manipulates sorting settings.
- GrcError.php -- the API for declaring and raising software errors.
- GrcHtmlComposite.php -- an object to contain a list of HTML elements.
- GrcHtmlElement.php -- a class to model a HTML element. The global arrays in this file describe the various support for HTML by HTML4, XHTML and HTML5.
- GrcHtmlView4.php -- a class for rendering HTML 4.
- GrcHtmlView5.php -- a class for rendering HTML 5.
- GrcHtmlViewX.php -- a class for rendering XHTML.
- GrcIntl.php -- a class to support an internationalization (i18n) API.
- GrcListShuffler.php -- an object for shuffling a list, i.e. remove/first/previous/next/last.
- GrcMessage.php -- a class for declaring system messages (and aiding their translation).
- GrcPageLinks.php -- a class for modelling page links, e.g. first/last/next/previous/size=N/etc.
- GrcService.php -- an object for composing modules.
- GrcTableView.php -- a class for rendering tabular data as HTML.
- GrcUrl.php -- an API for modelling URLs.
- GrcValidation.php -- an API for data validation.
/src/3-dal
The /src/3-dal directory contains data access layer facilities.
- GrcDal.php -- the include file for the Data Access Layer; defaults to MySQL/PDO API.
- GrcDalModule.php -- a base class for DAL Modules.
/src/3-dal/mysql-pdo
The /src/3-dal/mysql-pdo directory contains data access layer facilities for the MySQL/PDO database connectivity.
/src/3-dal/mysql-pdo/module
The /src/3-dal/mysql-pdo/module directory contains DAL modules.
/src/4-orm
The /src/4-orm directory contains Object/Relational Mappers. The ORM strategy that we employ is known as the Active Record pattern. An Active Record is a class that mediates data between the program (a PHP object) and the database (a record in a table). As a general rule (which can be broken) the Active Record is supposed to be CRUD only, any other business logic and/or validation should be implemented as a business process in the Business Object Model.
/src/5-bom
The /src/5-bom directory contains an interface into "business process" via the Business Object Model (GrcBom):
- GrcBom -- the business process interface
/src/5-bom/module
The /src/5-bom/module directory contains business process modules accessed via the BOM.
/src/6-view
The /src/6-view directory contains libraries of helper functions for view composition:
- header.php -- HTML header.
- footer.php -- HTML footer.
- library.php -- miscellaneous view components.
/src/7-ajax
The /src/7-ajax directory contains AJAX controllers.
- GrcAjax -- a service interface into AJAX operations (modules)
/src/7-ajax/module
The /src/7-ajax/module directory contains AJAX modules exposed by the GrcAjax service.
/test
The /test directory contains Unit Tests for the project.
/test/php
The /test/php directory contains test cases that demonstrate a PHP feature.
/test/src
The /test/src directory contains test cases that test a program feature.
/web
The /web directory contains front-facing components. Those are components which are accessible via HTTP(S). Each PHP file in the /web directory is known as a Page Controller. In addition to Page Controllers the /web directory includes:
Managing errors
The error management subsystem is comprised of the /src/2-obj/GrcError.php class and the 'err' and 'Error' functions in /src/1-lib/01-api.php.
Errors are managed in two modes: first they are 'declared' and second they are 'raised'.
Declaring error numbers
To declare a possible error call the err()->define function. The first argument is the name of the error known as the error const. The error const has up to 6 parts separated by double-underscore:
- 'ERROR'
- type (e.g. 'LIB', 'OBJ', etc.)
- module/class (e.g. 'API', 'VALIDATION')
- function name
- variable name
- state (e.g. 'NOT_NULL', 'INVALID')
The second argument is the error message. The error messages will be translated if necessary and can include variables using the '%variable%' notation of the i18n subsystem.
Raising particular errors
After you have declared an error like this:
err()->define( 'ERROR__LIB__EXAMPLE', 'An error with %param% occurred.' );
you can raise it like this:
throw Error( ERROR__LIB__EXAMPLE, 'param', 'value', intl_context, previous_exception );
where intl_context is an i18n translation context and previous_exception is a previous exception if any.
Security features
In addition to role-based security we protect from XSRF and SQL-injection attacks.
XSRF protection
To prevent XSRF attacks we configure a session token that must be included in all HTTP POST submissions.
SQL-injection protection
To prevent SQL injection attacks we take care to escape inputs when building SQL strings and/or use parameters with our database API.
Character encoding
All textual content is encoded, stored, and transmitted as UTF-8.
HTML charset
Read about character encodings in HTML for information about how to declare the UTF-8 charset in various HTML versions.
HTTP Content-Type
When sending HTTP replies the Content-Type should be specified with a charset parameter as described here.
For HTML the Content-Type would be:
Content-Type: text/html;charset=utf-8
For JSON the Content-Type would be:
Content-Type: application/json;charset=utf-8
And so on.
Internationalization (i18n) API
Internationalization functions defined in /src/1-lib/45-intl.php are the interface into the i18n API. They expose functions for the 01n paradigm and for table-heading/HTML/HTML-attribute/text/safe-text content types. See the functional specification for details on the 01n paradigm and content types.
In addition to the above API the HTML composition system supports automatic translation of content via the following methods:
- GrcHtmlElement->add_nbsp: add HTML after converting spaces to
- GrcHtmlElement->add_html: add HTML content (no escaping)
- GrcHtmlElement->add_h01n: add HTML 01n paradigm
- GrcHtmlElement->add_attr: add HTML attribute content (no escaping, angle brackets should not be present)
- GrcHtmlElement->add_a01n: add HTML attribute 01n paradigm
- GrcHtmlElement->add_text: add text content (HTML characters escaped)
- GrcHtmlElement->add_t01n: add text 01n paradigm
- GrcHtmlElement->add_safe: add safe text content (content must not include HTML special chars)
- GrcHtmlElement->add_s01n: add safe text 01n paradigm
Web interface
admin-home.php
The admin-home.php
Notes
Notes for implementers
If you are interested in incorporating this software into your project, here's what you need to know:
Notes for developers
If you're looking to set up a development environment for this project here's what you need to know:
Setting up a development environment
$ svn co svn+ssh://USERNAME@svn.savannah.gnu.org/remotecontrol/branches/development/jj5-mvc gnurc-jj5-mvc
Note: substitute USERNAME with your Savannah username. Make sure your firewall has ports 22 and 3690 open.
$ cd gnurc-jj5-mvc $ cp config.example.php config.php
Tasks
TODO
Things to do, in rough order of priority:
- Document system design
- Generate task list
- Allocate tasks to developers
Done
Stuff that's done. Latest stuff on top.