[phpwebapp-commits] CVS: web_app/doc changes_5.txt,NONE,1.1 ToDo.txt,1.10,1.11 changes.txt,1.21,1.22
Brought to you by:
dashohoxha
Menu
▾
▴
[phpwebapp-commits] CVS: web_app/doc changes_5.txt,NONE,1.1 ToDo.txt,1.10,1.11 changes.txt,1.21,1.22 to_do.txt,1.19,1.20
|
From: Dashamir H. <das...@us...> - 2005-08-31 07:59:59
|
Update of /cvsroot/phpwebapp/web_app/doc In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv30386/doc Modified Files: ToDo.txt changes.txt to_do.txt Added Files: changes_5.txt Log Message: --- NEW FILE: changes_5.txt --- Changes made to the application framework that the framework users should know: =========================================== ------------------------------------------------------------------- * The tag <textarea> is treated as preformated (similar to <pre>, <xmp> and <example>). This means that the indentation and the white-space of its contents are preserved by the framework. ------------------------------------------------------------------- * GoTo() can have a second optional parameter which specifies the action where the form is to be submitted. Default is the previous action. If it is 'index' then the filename will be removed from the previous action (ant the action will become in fact index.php in the path). ------------------------------------------------------------------- * WebApp::addSVar() or $this->addSVar() initialize a state variable by calling $session->addVar(). Now the behaviour of $session->addVar() is modified so that it will not re-initialize a variable (it will not change the value of a variable, if it already exists). This is done in order to be able to set some state variables of a webbox without being afraid that init() will override them. ------------------------------------------------------------------- * Added function: WebApp::fill_template($tpl_file, $vars) This function processes the given template, replacing any variables, including any other templates, etc. and returns the resulting string. The parameter $vars(optional) is an array of variables (associative array), which can be used to replace the template vars. This function is different from: WebApp::getHtmlPage($tpl_file) and from WebApp::constructHtmlPage($tpl_file) because they assume that the given template file is a main template (which has a prolog <?xml ...?> and an <html> root element), and also they append some extra things to the consructed page, like debug information, session variables, etc. ------------------------------------------------------------------- * Function WebApp::popup_window($name, $url, $features ='nil') can be used to open a pop-up window (in a new browser). Parameters $name, $url, and $features will be used in a javascript statement like this: $name = window.open($url, $name, $features); ------------------------------------------------------------------- * Added function: WebApp::GoTo($target_page, $target_object =UNDEFINED, $event_name =UNDEFINED, $event_args =UNDEFINED) This function stops constructing the current page and starts loading and constructing the given target page. Similar to the JS function GoTo(), it can also send an event to the new page that is going to be constructed. ------------------------------------------------------------------- * Added debug options DEBUG_INCLUDES and DEBUG_WEBOBJECTS. They should be included in 'config/const.Debug.php' like this: /** * if this constant is true, the framework outputs a box * around each file that is included in the page */ define("DEBUG_INCLUDES", false); /** * if this constant is true, the framework outputs a box * around each webobject that is used in the page */ define("DEBUG_WEBOBJECTS", false); ------------------------------------------------------------------- * Added the (framework) tag <unindented>. By default the framework indents all the templates that are processed or included. However sometimes may be usefull not to indent a part of a template. This can be done by including it inside the <unindeted> tag, like this: <unindented> {{file_revision}} </unindented> ------------------------------------------------------------------- * Added support for multiple languages to the framework. translation / internationalization (i18n) / localization (l10n) It can use any one of the packages: - PHP-gettext (http://savannah.nongnu.org/projects/php-gettext/) - GNU gettext (http://www.gnu.org/software/gettext/gettext.html, http://www.php.net/gettext) since both of them have some advantages or disadvantages. The disadvantages of GNU gettext are that it does not work if gettext package is not installed, or if the system is not configured for using translations of a language. Also, the gettext functions in the php seem not to be reliable, sometimes they get the translation from one place, sometimes from another (maybe this is a caching problem?). In general, it is a headache to make it work. The disadvantages of PHP-gettext are that it may not be as fast as GNU gettext, and there may be some gettext functionality that is not supported yet (not implemented yet). The application programer can choose the one that suits him best. The choice is made at 'config/const.Options.php': /** if true, then use the php-gettext instead of GNU gettext */ define('USE_PHP_GETTEXT', true); Other translation constants that are defined at the options file are LNG and CODESET: /** * The constants LNG and CODESET set a default language and codeset for * the application. They are used for the localization (translation) * of the messages. They can be changed by calling: * $l10n->set_lng($lng, $codeset) * where $l10n is a global variable and $codeset is optional. * LNG can be something like 'en_US' or 'en' or UNDEFINED. * CODESET can be UNDEFINED, 'iso-latin-1', etc. */ define('LNG', 'sq_AL'); define('CODESET', 'iso-latin-1'); LNG sets a default language for the application, but it can also be changed dynamically, calling $l10n->set_lng($lng). With GNU gettext, LNG can also be UNDEFINED, and in this case the system default will be used. However, with PHP-gettext it should have a value (or a value should be set with $l10n->set_lng()). CODESET is used in GNU gettext, but it is not needed by PHP-gettext, so it can also be UNDEFINED. See the documentation of gettext (`info gettext`) for more information about when and why it is needed. The framework allows to have separate translation (localization) files foreach template that is included and for each webobject. If the directory that contains the template (or webbox) contains also a subdirectory named 'l10n', then the framework will look inside this directory for the file that contains the translations of the messages of the template/webbox. It will look for the file l10n/lng/LC_MESSAGES/tplname.mo (or l10n/lng/LC_MESSAGES/webboxid.mo) which contains the translation messages of the template (or webbox). If the subdirectory 'l10n/' does not exist, the framework will look for the file tplname.mo (or webboxid.mo) in the first 'l10n/' in the parent directory or in the ancestors. If even the application directory does not contain a 'l10n/' subdir, then the last place to look for will be the system default (usually /usr/share/locale/). About the language code, if it is e.g. 'en_US', then it will search first the folder 'en_US/' and then the folder 'en/'. If the file tplname.mo (or webboxid.mo) is not found at all in the searched directories, then the last translation (*.mo) file that was found will be used for translating messages. This is usually the translation (*.mo) file of the containing template or webbox (from which this template/webbox is included directly or indirectly). This way of finding the translation files allows for modularity, because each webbox/template can have its own translation files, so using them in other applications can be done by just copying them there. But it is also flexible and does not enforce unnecessary or unneeded modularity, so that for example the whole application can have a single translation file, or sub-webbox-es can use the translation files of the main webbox. In general, translation files (*.mo) can be organized like this: - A single translation file 'app_name.mo' can be used for all the application. It can be placed in /usr/share/locale/lng/LC_MESSAGES/ or in app_path/l10n/lng/LC_MESSAGES/ - Generic webboxes, which are used in more that one application, can have their own translation file 'webbox_id.mo' (besides the application file 'app_name.mo'), which is placed in the same directory as the application file (see above). - Each important webbox can have a subdirectory 'l10n/', in which is placed the translation file of the webbox, in /path/to/webbox/l10n/lng/LC_MESSAGES/webbox.mo . This file can contain the translations of all the sub-webbox-es and sub-templates as well (the ones that are included from this webbox), or they (their translations) can be in separate files in the same directory, which are named according to the template name or the webbox id. - Each webbox can have its own 'l10n/' directory, which contains its own translation files. This is the most modular aproach but it may not be always needed. Other combinations are possible as well, so it is up to the application and its developer to decide about it. In order to make a string translatable, it should be placed as an argument of the T_() function and should be surrounded by double quotes, like this: T_("Hello!") . This can be used both in the PHP code and in the HTML templates (but not in JS files, because they are not processed by the framework). Then, the rest is the same as described by the gettext documentation (see `info gettext`): the translatable strings are extracted automatically from the PHP code and HTML templates using the xgettext program (see `info xgettext`), creating *.po files, then the strings are translated, then *.po files are converted to *.mo files using `msgfmt`, then they are installed (placed at the propper location in the application). The xgettext program should be called with the '-kT_' parameter, which means that 'T_' is the name of the function whose strings will be extracted. Tip: In order to translating attribute values, use a {{variable}} inside the attribute value, and then in the PHP code that adds the variable, get the appropriate translation. E.g. <input type="button" value="{{Search>>}}" /> (in HTML) WebApp::addVar('Search>>', T_("Search>>")); (in PHP) Tip: Some templates contain text, not just messages, which can also be mixed with HTML tags (see e.g. 'templates/search/help.html' in this case it is difficult to translate it using translation messages. The best way is to use a separate template for each language, like 'help_en_US.html', 'help_sq_AL.html', etc. When the template is included, something like this can be used: <include src="{{./}}help_{{lng}}.html" /> where {{lng}} can be defined in the php code like this: function onParse() { global $l10n; WebApp::addVar('lng', $l10n->lng); } Tip: Since xgettext has the C syntax in mind, for strings in multiple lines, it gives a warning: "unterminated string literal" and it does not get them right. To bypass this problem, a slash (\) can be added at the end of the lines, like in C strings. The framework will take care to remove it automatically and the lines will be as if there was no break between them. In case that you do want to preserve the break between the lines, then use '\n\' at the end of the lines. This is just a dirty trick, the clean solution would be to modify xgettext so that it reckognizes the syntax of php and html strings, but it is not so easy for me to do this, and until somebody does it, this trick solves the problem. ------------------------------------------------------------------- * Now it is possible to use translatable messages in the JS code (e.g. in the messages that are displayed by alert()). Same as in PHP and HTML, strings are translated by the function: T_("...."). Attention: double quotes must be used ("), otherwise xgettext will not be able to extract them. In order to have variables inside a message, you have to make some tricks. E.g., to make translatable this message: --code var new_node_id = prompt("Rename node '" + node_id + "' to:"); ---- It can be written like this: --code var msg = T_("Rename node 'v_node_id' to:").replace(/v_node_id/, node_id); //var msg = T_("Rename node 'v_node_id' to:"); //msg = msg.replace(/v_node_id/, node_id); var new_node_id = prompt(msg); ---- This allows the translator to change the position of the variable, if needed. Note: How it Works The JS function T_(msgid), which is included in the page by the framework, returns the translation msgstr of the given msgid. This translation is retrived from a list of translated messages, which is contained by the JS object l10n of class L10n, which is included in the page by the framework. If you view the source of the page, you will see near the end something like this: --code <script type="text/javascript" language="javascript" src="web_app/l10n/class.L10n.js"></script> <script type="text/javascript" language="javascript"> //<![CDATA[ l10n = new L10n(); l10n.addMsg("You are deleting this node and all the subnodes.", "You are deleting this node and all the subnodes."); l10n.addMsg("ID cannot be empty.", "ID cannot be empty."); l10n.addMsg("Title cannot be empty.", "Title cannot be empty."); l10n.addMsg("Please give an ID.", "Please give an ID."); l10n.addMsg("Please give a title.", "Please give a title."); l10n.addMsg("Rename 'v_item' to:", "Rename 'v_item' to:"); l10n.addMsg("Your are deleting 'v_item'!", "Your are deleting 'v_item'!"); l10n.addMsg("Uploading:", "Uploading:"); l10n.addMsg("Please wait...", "Please wait..."); //]]> </script> ---- This is generated automatically by the framework. For each JS file that it includes in the <head> of the page, it also scans it for translatable messages, gets their translation, and includes lines l10n.addMsg(msgid, msgstr), as above. ------------------------------------------------------------------- ------------------------------------------------------------------- ------------------------------------------------------------------- Index: ToDo.txt =================================================================== RCS file: /cvsroot/phpwebapp/web_app/doc/ToDo.txt,v retrieving revision 1.10 retrieving revision 1.11 diff -C2 -d -r1.10 -r1.11 *** ToDo.txt 13 Jun 2005 06:55:21 -0000 1.10 --- ToDo.txt 31 Aug 2005 07:59:48 -0000 1.11 *************** *** 55,64 **** again in the structure that they were before. ------------------------------------------------------------- - * - The messages of the framework (errors, warnings, etc) should - support multiple languages. - - - The messages displayed from JS code (alerts) should support - multiple languages. - ------------------------------------------------------------- * - Build a tool for the web (graphical) designer so that he can preview the templates. (The "browse.php" does this). --- 55,58 ---- Index: changes.txt =================================================================== RCS file: /cvsroot/phpwebapp/web_app/doc/changes.txt,v retrieving revision 1.21 retrieving revision 1.22 diff -C2 -d -r1.21 -r1.22 *** changes.txt 22 Jun 2005 12:56:29 -0000 1.21 --- changes.txt 31 Aug 2005 07:59:48 -0000 1.22 *************** *** 5,298 **** ------------------------------------------------------------------- - * The tag <textarea> is treated as preformated (similar to <pre>, - <xmp> and <example>). This means that the indentation and the - white-space of its contents are preserved by the framework. - ------------------------------------------------------------------- - * GoTo() can have a second optional parameter which specifies the action - where the form is to be submitted. Default is the previous action. - If it is 'index' then the filename will be removed from the previous - action (ant the action will become in fact index.php in the path). - ------------------------------------------------------------------- - * WebApp::addSVar() or $this->addSVar() initialize a state variable - by calling $session->addVar(). Now the behaviour of $session->addVar() - is modified so that it will not re-initialize a variable (it will - not change the value of a variable, if it already exists). This is - done in order to be able to set some state variables of a webbox - without being afraid that init() will override them. - ------------------------------------------------------------------- - * Added function: - WebApp::fill_template($tpl_file, $vars) - This function processes the given template, replacing any variables, - including any other templates, etc. and returns the resulting - string. The parameter $vars(optional) is an array of variables - (associative array), which can be used to replace the template vars. - This function is different from: - WebApp::getHtmlPage($tpl_file) and from - WebApp::constructHtmlPage($tpl_file) - because they assume that the given template file is a main template - (which has a prolog <?xml ...?> and an <html> root element), - and also they append some extra things to the consructed page, - like debug information, session variables, etc. - ------------------------------------------------------------------- - * Function WebApp::popup_window($name, $url, $features ='nil') - can be used to open a pop-up window (in a new browser). - Parameters $name, $url, and $features will be used in a - javascript statement like this: - $name = window.open($url, $name, $features); - ------------------------------------------------------------------- - * Added function: - WebApp::GoTo($target_page, $target_object =UNDEFINED, - $event_name =UNDEFINED, $event_args =UNDEFINED) - This function stops constructing the current page and starts - loading and constructing the given target page. Similar to - the JS function GoTo(), it can also send an event to the new - page that is going to be constructed. - ------------------------------------------------------------------- - * Added debug options DEBUG_INCLUDES and DEBUG_WEBOBJECTS. They - should be included in 'config/const.Debug.php' like this: - - /** - * if this constant is true, the framework outputs a box - * around each file that is included in the page - */ - define("DEBUG_INCLUDES", false); - - /** - * if this constant is true, the framework outputs a box - * around each webobject that is used in the page - */ - define("DEBUG_WEBOBJECTS", false); - - ------------------------------------------------------------------- - * Added the (framework) tag <unindented>. By default the framework indents - all the templates that are processed or included. However sometimes may - be usefull not to indent a part of a template. This can be done by - including it inside the <unindeted> tag, like this: - <unindented> - {{file_revision}} - </unindented> - ------------------------------------------------------------------- - - * Added support for multiple languages to the framework. - translation / internationalization (i18n) / localization (l10n) - - It can use any one of the packages: - - PHP-gettext (http://savannah.nongnu.org/projects/php-gettext/) - - GNU gettext (http://www.gnu.org/software/gettext/gettext.html, - http://www.php.net/gettext) - since both of them have some advantages or disadvantages. - - The disadvantages of GNU gettext are that it does not work if gettext - package is not installed, or if the system is not configured for - using translations of a language. Also, the gettext functions in the php - seem not to be reliable, sometimes they get the translation from one - place, sometimes from another (maybe this is a caching problem?). - In general, it is a headache to make it work. - - The disadvantages of PHP-gettext are that it may not be as fast - as GNU gettext, and there may be some gettext functionality that is - not supported yet (not implemented yet). - - The application programer can choose the one that suits him best. - The choice is made at 'config/const.Options.php': - - /** if true, then use the php-gettext instead of GNU gettext */ - define('USE_PHP_GETTEXT', true); - - Other translation constants that are defined at the options file - are LNG and CODESET: - - /** - * The constants LNG and CODESET set a default language and codeset for - * the application. They are used for the localization (translation) - * of the messages. They can be changed by calling: - * $l10n->set_lng($lng, $codeset) - * where $l10n is a global variable and $codeset is optional. - * LNG can be something like 'en_US' or 'en' or UNDEFINED. - * CODESET can be UNDEFINED, 'iso-latin-1', etc. - */ - define('LNG', 'sq_AL'); - define('CODESET', 'iso-latin-1'); - - LNG sets a default language for the application, but it can also be - changed dynamically, calling $l10n->set_lng($lng). With GNU gettext, - LNG can also be UNDEFINED, and in this case the system default will - be used. However, with PHP-gettext it should have a value (or a - value should be set with $l10n->set_lng()). - CODESET is used in GNU gettext, but it is not needed by PHP-gettext, - so it can also be UNDEFINED. See the documentation of gettext - (`info gettext`) for more information about when and why it is needed. - - The framework allows to have separate translation (localization) files - foreach template that is included and for each webobject. If the - directory that contains the template (or webbox) contains also - a subdirectory named 'l10n', then the framework will look inside - this directory for the file that contains the translations of the - messages of the template/webbox. It will look for the file - l10n/lng/LC_MESSAGES/tplname.mo (or l10n/lng/LC_MESSAGES/webboxid.mo) - which contains the translation messages of the template (or webbox). - - If the subdirectory 'l10n/' does not exist, the framework will - look for the file tplname.mo (or webboxid.mo) in the first 'l10n/' - in the parent directory or in the ancestors. If even the application - directory does not contain a 'l10n/' subdir, then the last place - to look for will be the system default (usually /usr/share/locale/). - - About the language code, if it is e.g. 'en_US', then it will search - first the folder 'en_US/' and then the folder 'en/'. - - If the file tplname.mo (or webboxid.mo) is not found at all in - the searched directories, then the last translation (*.mo) file - that was found will be used for translating messages. This is usually - the translation (*.mo) file of the containing template or webbox - (from which this template/webbox is included directly or indirectly). - - This way of finding the translation files allows for modularity, - because each webbox/template can have its own translation files, - so using them in other applications can be done by just copying them - there. But it is also flexible and does not enforce unnecessary - or unneeded modularity, so that for example the whole application - can have a single translation file, or sub-webbox-es can use the - translation files of the main webbox. - - In general, translation files (*.mo) can be organized like this: - - - A single translation file 'app_name.mo' can be used for all the - application. It can be placed in /usr/share/locale/lng/LC_MESSAGES/ - or in app_path/l10n/lng/LC_MESSAGES/ - - - Generic webboxes, which are used in more that one application, - can have their own translation file 'webbox_id.mo' (besides - the application file 'app_name.mo'), which is placed in the - same directory as the application file (see above). - - - Each important webbox can have a subdirectory 'l10n/', - in which is placed the translation file of the webbox, - in /path/to/webbox/l10n/lng/LC_MESSAGES/webbox.mo . - This file can contain the translations of all the sub-webbox-es - and sub-templates as well (the ones that are included from this - webbox), or they (their translations) can be in separate - files in the same directory, which are named according to - the template name or the webbox id. - - - Each webbox can have its own 'l10n/' directory, which contains - its own translation files. This is the most modular aproach - but it may not be always needed. - - Other combinations are possible as well, so it is up to the - application and its developer to decide about it. - - In order to make a string translatable, it should be placed - as an argument of the T_() function and should be surrounded - by double quotes, like this: T_("Hello!") . This can be used - both in the PHP code and in the HTML templates (but not in - JS files, because they are not processed by the framework). - - Then, the rest is the same as described by the gettext documentation - (see `info gettext`): the translatable strings are extracted - automatically from the PHP code and HTML templates using the - xgettext program (see `info xgettext`), creating *.po files, - then the strings are translated, then *.po files are converted - to *.mo files using `msgfmt`, then they are installed (placed at - the propper location in the application). The xgettext program - should be called with the '-kT_' parameter, which means that - 'T_' is the name of the function whose strings will be extracted. - - Tip: In order to translating attribute values, use a {{variable}} - inside the attribute value, and then in the PHP code that - adds the variable, get the appropriate translation. E.g. - - <input type="button" value="{{Search>>}}" /> (in HTML) - - WebApp::addVar('Search>>', T_("Search>>")); (in PHP) - - Tip: Some templates contain text, not just messages, which can - also be mixed with HTML tags (see e.g. - 'templates/search/help.html' in this case it is difficult - to translate it using translation messages. The best way is - to use a separate template for each language, like - 'help_en_US.html', 'help_sq_AL.html', etc. - When the template is included, something like this can be - used: - <include src="{{./}}help_{{lng}}.html" /> - where {{lng}} can be defined in the php code like this: - function onParse() - { - global $l10n; - WebApp::addVar('lng', $l10n->lng); - } - - Tip: Since xgettext has the C syntax in mind, for strings - in multiple lines, it gives a warning: "unterminated string - literal" and it does not get them right. To bypass this - problem, a slash (\) can be added at the end of the lines, - like in C strings. The framework will take care to remove it - automatically and the lines will be as if there was no break - between them. In case that you do want to preserve the break - between the lines, then use '\n\' at the end of the lines. - - This is just a dirty trick, the clean solution would be to - modify xgettext so that it reckognizes the syntax of php and - html strings, but it is not so easy for me to do this, and - until somebody does it, this trick solves the problem. - - ------------------------------------------------------------------- - - * Now it is possible to use translatable messages in the JS code - (e.g. in the messages that are displayed by alert()). Same as - in PHP and HTML, strings are translated by the function: - T_("...."). - - Attention: double quotes must be used ("), otherwise - xgettext will not be able to extract them. - - In order to have variables inside a message, you have to make - some tricks. E.g., to make translatable this message: - --code - var new_node_id = prompt("Rename node '" + node_id + "' to:"); - ---- - It can be written like this: - --code - var msg = T_("Rename node 'v_node_id' to:").replace(/v_node_id/, node_id); - //var msg = T_("Rename node 'v_node_id' to:"); - //msg = msg.replace(/v_node_id/, node_id); - var new_node_id = prompt(msg); - ---- - This allows the translator to change the position of the variable, - if needed. - - Note: How it Works - The JS function T_(msgid), which is included in the page by - the framework, returns the translation msgstr of the given msgid. - This translation is retrived from a list of translated messages, - which is contained by the JS object l10n of class L10n, which is - included in the page by the framework. If you view the source of - the page, you will see near the end something like this: - --code - <script type="text/javascript" language="javascript" - src="web_app/l10n/class.L10n.js"></script> - <script type="text/javascript" language="javascript"> - //<![CDATA[ - l10n = new L10n(); - l10n.addMsg("You are deleting this node and all the subnodes.", - "You are deleting this node and all the subnodes."); - l10n.addMsg("ID cannot be empty.", "ID cannot be empty."); - l10n.addMsg("Title cannot be empty.", "Title cannot be empty."); - l10n.addMsg("Please give an ID.", "Please give an ID."); - l10n.addMsg("Please give a title.", "Please give a title."); - l10n.addMsg("Rename 'v_item' to:", "Rename 'v_item' to:"); - l10n.addMsg("Your are deleting 'v_item'!", - "Your are deleting 'v_item'!"); - l10n.addMsg("Uploading:", "Uploading:"); - l10n.addMsg("Please wait...", "Please wait..."); - //]]> - </script> - ---- - This is generated automatically by the framework. For each JS file - that it includes in the <head> of the page, it also scans it for - translatable messages, gets their translation, and includes lines - l10n.addMsg(msgid, msgstr), as above. - - ------------------------------------------------------------------- ------------------------------------------------------------------- ------------------------------------------------------------------- --- 5,8 ---- Index: to_do.txt =================================================================== RCS file: /cvsroot/phpwebapp/web_app/doc/to_do.txt,v retrieving revision 1.19 retrieving revision 1.20 diff -C2 -d -r1.19 -r1.20 *** to_do.txt 6 Jul 2005 14:07:21 -0000 1.19 --- to_do.txt 31 Aug 2005 07:59:48 -0000 1.20 *************** *** 1,3 **** --- 1,7 ---- * - Make i18n/l10n for the messages of the framework itself. + - The messages of the framework (errors, warnings, etc) should + support multiple languages. + - The messages displayed from JS code (alerts) should support + multiple languages. * - Write in DocBookWiki a programmer's guide for phpWebApp. |
