20190322

CHANGELOG.md

@@ -9,10 +9,13 @@ Project: [PHP Atomchat](https://github.com/phhpro/atomchat)
 
 ## [20190322] - 2019-03-22
 ### Changed
-- Replaced AJAX with SSE. Polling option still available but deactivated.
+- Replaced AJAX with SSE. Polling option still available but disabled.
 - Fix: Access token condition was broken on login screen.
 - Fix: Missing hover state on box ID.
 
+### Added
+- New theme 'Poetry'.
+
 ## [20190321] - 2019-03-21
 ### Changed
 - Moved copy/paste trigger from symbol to timestamp.

CONTRIBUTING.md

@@ -2,8 +2,8 @@
 
 - Sources must satisfy CodeSniffer.
 - Maximum line length are 72 characters; except translations.
-- Only exit identifiers may be hard-coded; English only.
-- Keep it simple and effective.
+- Indent with four spaces.
+- Interface output must come from language file; only exit identifiers may be hard coded; English only.
 - Use meaningful comments where required.
 
 That's pretty much it. Happy coding.

README.md

@@ -5,61 +5,71 @@
 ## Features
 - Works OOTB and is completely anonymous
 - No registration or passwords ever
-- Emoji auto-conversion and auto-select
-- Fully themeable and multi-lingual
+- Emoji auto conversion and auto select
+- Fully themeable and multilingual
 - Responsive, cross browser, cross platform
 - File uploads, literally zero dependencies
-- One-click text select for easy copy/paste
+- One click text select for easy copy/paste
 - Absolutely no database required
 
 ### News
 
-As of v20190322 previous AJAX long polling has been replaced with SSE. The polling option is still available but deactivated.
+As of v20190322 AJAX has been replaced with SSE. The AJAX option is still available but disabled.
+
+While in theory quite possible, the script could actually run in hybrid mode, using both options at the same time. However, unless you really hate your server and just want to kill it as fast as possible, you are discouraged from attempting any such.
 
 ### Configuration
 
-The script generates a default configuration in `config.php` when first run or in case the file has been accidentally deleted. All relevant settings can be configured from the superuser screen and are usually effective immediately. Simply refresh the page if in doubt. You can also enable a timeout option to automatically logout inactive users after a given time. The default is to leave session handling to PHP settings.
+The script generates a default configuration in `config.php` when first run or in case the file has been accidentally deleted. All relevant settings can be configured from the superuser screen and are usually effective immediately. Simply refresh the page if in doubt. You can also enable a timeout option to automatically logout inactive users. The default is to leave session handling to PHP settings.
 
-Please visit the superuser screen before making the script public and change at least the prefix and suffix. The rest of the default settings should be fairly save to keep for the time being. Default login is `atomchat`.
+Please visit the superuser screen before making the script public and change at least the prefix and suffix. The rest of the default settings should be fairly save to keep for the time being. Default login as superuser is `atomchat`.
 
-Also please note that whatever you enter will be accepted AS IS. In other words, if you put text into a field expecting numbers, the script will accept that but likely break after reading the new configuration. In any such case your best option is to delete `config.php` and restart from scratch.
+Also please note that whatever you enter will be accepted *AS IS*. In other words, if you put text into a field expecting numbers, the script will accept that but likely break after reading the new configuration. In any such case your best option is to delete `config.php` and start over.
 
 ### Access And *Security*
 
-An optional query string check exists to restrict access without a valid access token, e.g. to keep bots out. You should also change the token value when using the feature. The setting is disabled per default to simplify testing the script but is strongly recommended to be enabled in public environments. Just make sure to let your users know the proper access token before they start hitting your inbox. Providing the complete URL would be the easiest, like `example.com/atomchat/?chat`
+An optional access token can be enabled to restrict access, e.g. to keep bots out. You should change the default token value when using the feature. The setting is disabled per default to simplify testing, but is strongly recommended to be enabled in public environments. Just make sure to let your users know the proper token before they start hitting your inbox. Providing the complete URL would be the easiest, like `example.com/atomchat/?chat`
 
-***This script is absolutely NOT fit to serve in secure environments!***
+***The script is neither meant nor prepared for use in secure environments!***
 
 ### Logging
 
-Logging applies to the chatlog. The script creates unmetered daily logs, which are; together with any uploaded files; auto deleted after 24 hours. The exact behaviour can be changed on the superuser screen. Downloaded logs maintain all formatting; no styles though or JavaScript features; and can be viewed offline with any HTML capable application. No other logging takes place; nor is planned to be implemented.
+Logging applies to the chatlog. The script creates unmetered daily logs, which are; together with any uploaded files; auto deleted after 24 hours. The exact behaviour can be changed on the superuser screen. Downloaded logs maintain basic formatting; no styles or JavaScript though; and can be viewed offline with any HTML capable application.
+
+***The script does not record any user data, like IP, date, browser, etc.***
 
 ### Emoji Auto Conversion
 
 When enabled, this feature attempts to automatically convert registered text tokens into graphical Unicode emojis. Hence, you'll get an image, which in fact is entirely text. However, Unicode support varies greatly across devices and platforms. 
 
-Google Chrome for desktops is particulary prone to fail. Interestingly though, the mobile version seems to have gotten all the Unicode support the desktop version is lacking; or maybe fonts on Android are just better prepared. Therefore, the definition file `emo.dat` only covers a minimal set. YMMV.
+Google Chrome for desktops is particulary prone to fail. Interestingly though, the mobile version seems to have gotten all the Unicode support the desktop version is lacking; or maybe fonts on Android are just better prepared. Therefore, the definition file `emo.dat` covers only a minimal set. YMMV.
 
-In addition to direct text input, the script also provides a point-and-click hover menu to insert emojis at the current cursor position and one-click text-select for easy copy/paste operations. Simply click the message's timestamp to auto select the corresponding text. These features require JavaScript.
+In addition to direct text input, the script also provides a point-and-click hover menu to insert emojis at the current cursor position and one click text select for easy copy/paste operations. Simply click the message's timestamp to auto select the corresponding text. These features require JavaScript.
 
 ### File Uploads
 
 Image types `gif, jpeg, jpg, png` are managed internally and converted to Base64 strings to be available in offline logs. Only these will render auto scaled thumbnails. Any other types produce standard text links. You may need to edit your CSP to add an exception for the `base` handler if you don't see the thumbnails.
 
 ### Multi Themes
 
-The script provides a small collection of pre-made themes. These are kept simple and primarily aim to serve as guidance to *'roll your own'*. Themes typically just provide colours. The actual core styles are managed in `default.css`. You are advised not to touch this file unless you know what you're doing. Multi themes are enabled per default to allow users to change themes as they see fit. You can disable this option if you prefer a fixed theme.
+The script provides a small collection of pre-made themes. Themes just provide colours, while core styles are managed in `default.css`. You are advised not to touch this file unless you know what you're doing. Multi themes are enabled per default to allow users to change themes as they see fit. You can disable this option if you prefer a fixed theme.
 
 ### Multi Lingual
 
-The script attempts to auto detect the browser's language preferences and checks if a translation exists. If so, the interface will use that language. Else, the  configured default language is applied. Users can change language settings at any time.
+The script attempts to auto detect the browser's language preferences and checks if a language file exists. If so, the interface will use that language. Else, the  configured default language is applied. Users can change language settings at any time.
 
-As an example, consider a native speaker of Japanese on vacation in Italy on a publci terminal configured to prefer Italian. The script would talk Italian. Open the settings screen and select Japanese from the list. The script talks Japanese instantly. Refer to `TRANSLATE.md` if your language is missing.
+As an example, consider a native speaker of Japanese on a terminal configured to prefer Italian. Since an Italian language file exists, the script would initally talk Italian. However, since there also exists a Japanese language file, opening the settings screen and selecting Japanese from the list will make the script talk Japanese instantly. Refer to `TRANSLATE.md` if your language is missing.
 
 ### Limitations And Issues
 
-Where JavaScript is not available, or when using a text-mode browser, the page needs manual refreshing to execute the selected action or to update the log. In this case neither character counter, nor emoji hover menu, nor auto select will have any effect. You can still input emojis by typing the assigned text token as illustrated on the settings screen. Text is auto cut after reaching the character limit.
+Where JavaScript is not available, or when using a text mode browser, the page needs manual refreshing to execute the selected action or to update the log. In this case neither character counter, nor emoji hover menu, nor auto text select will have any effect. You can still input emojis by typing the assigned text token as illustrated on the settings screen. Text input is auto cut after reaching the character limit.
+
+Setting a non-Western default as the page language META may produce strange effects. In mild cases just black and white emojis, in more extreme scenarios effectively placing the hover menu out of reach and hence making it completely unusable. Hard-linking a Western locale fixes the issue. Translations are not affected.
+
+### Support
+
+Please open an issue to request assistance; and be patient. I tend to follow-up on any feedback in due time and am open to suggestions; as long as they are meaningful.
 
-Setting a non-Western default as the page language META produces strange rendering. In mild cases it's just black and white emojis, in more extreme scenarios effectively placing the hover menu out of reach and hence making it completely unusable. Hard-linking a Western locale fixes the issue. Translations are not affected.
+Do *not* open an issue to request help setting up your server, or asking how to create a multi dimensional associative array or any other esoteric foo bar stuff.
 
 That all said, happy Atomchatting.

TRANSLATE.md

@@ -1,14 +1,17 @@
 # Translation Guide
 
+## Prepare
+
 Copy `en.php` and save as `xx.php` -- where `xx` is the language ID you are translating into, e.g. `sv.php` for Swedish. Visit the [IANA language subtag registry](https://www.iana.org/assignments/language-subtag-registry) if you don't know the language ID. Always use the macro language, e.g. the sub tag for Mesopotamian Arabic is `acm`, but we just say `ar` to indicate it's Arabic.
 
-Open the file in your favourite editor and update the `@language` tag. Don't touch any other `@tags` and keep the file structure exactly *AS IS*. Translate the strings and save as UTF-8 (without BOM) with Unix line endings.
+## Translate
+
+Open the file in your favourite *text* editor and update the `@language` tag. Don't touch any other `@tags` and keep the file structure exactly *AS IS*. Translate the strings and save as UTF-8 (without BOM) with Unix line endings.
+
+## Share
 
-Submit a request to the repository if you want to include your new translation. You should be prepared to maintain the file and keep in sync with future updates. Else, it will be purged. If you're a native speaker of any of the existing languages and spot an error, please report your suggestion, thank you.
+Submit a request to the repository if you want to share and include your new translation. However, you should be prepared to maintain your translation and keep in sync with future updates before posting a request. Abandoned language files will be purged.
 
-**Previous translations purged as of v20190315**
+## Help
 
-- EL
-- IW
-- PL
-- TR
+If you're a native speaker of any of the existing language files and spot any typos or errors, please report your suggestions, thank you.

chat.js

@@ -12,7 +12,7 @@
  * @link      https://github.com/phhpro/atomchat
  */
 
-
+//** Character counter
 function chars(chat)
 {
     if (chat.text.value.length >= char) {
@@ -22,6 +22,7 @@ function chars(chat)
     }
 }
 
+//** Insert emoji from hover menu
 function emo(str)
 {
     var txt = document.getElementById("text");
@@ -48,6 +49,7 @@ function emo(str)
     }
 }
 
+//** Select text of given ID
 function selectText(id)
 {
     var rng = document.createRange();
@@ -58,6 +60,7 @@ function selectText(id)
         sel.addRange(rng);
 }
 
+//** Select ID to select text from
 function selectID(id)
 {
     var id = document.getElementById(id);
@@ -67,18 +70,20 @@ function selectID(id)
 
 /*
  * As of v20190322 AJAX has been replaced with SSE, making the below
- * obsolete. It is kept here for the time being as a fallback in case
- * your main audience uses MSIE.
+ * section obsolete. It's kept here for the time being as a fallback
+ * if your main audience uses MSIE and you'd rather revert to AJAX
+ * because MSIE has very poor support for server sent events and may
+ * well throw an error and exit. To revrt to AJAX:
  *
- * MSIE has very poor support for server sent events and may throw an
- * error. Uncomment the below section and edit the "chatlog screen"
- * section in index.php to revert to polling.
+ * - Uncomment the below section.
+ * - Edit the "chatlog screen" section in index.php.
  */
 
 
 /*
 var http = null;
 
+//** Check browser support
 function ajax()
 {
     if (window.ActiveXObject) {
@@ -91,6 +96,7 @@ function ajax()
     }
 }
 
+//** Pseudo push new content
 function push()
 {
     http = ajax();
@@ -113,5 +119,6 @@ function push()
     setTimeout('push()', (1000 * rate));
 }
 
+//** Init polling
 push();
 */

index.php

@@ -1086,7 +1086,7 @@ function go($tag)
 
         if ($emo_ln[0] !== "") {
             echo "                        <input type=\"text\" " .
-                 "id=\"$emo_id\" class=\"emo_id\" " .
+                 "id=\"$emo_id\" class=\"emo_id\" size=\"1\" " .
                  "value=\"" . $emo_ln[1] . "\" " .
                  "title=\"" . $emo_ln[0] . "\" " .
                  "onclick=\"emo('$emo_id');\"/>\n";
@@ -1706,10 +1706,14 @@ function go($tag)
         } else {
 
             /*
-             * As of v20190322 AJAX has been replaced with SSE. MSIE
-             * has very poor support for server sent events and may
-             * throw an error. Uncomment the below include and comment
-             * out the entire script echo block to revert to polling.
+             * As of v20190322 AJAX has been replaced with SSE. MSIE has
+             * very poor support for server sent events and may throw an
+             * error. To revert to AJAX:
+             *
+             * - Uncomment the below include and comment out the entire
+             *   script echo block.
+             *
+             * - Edit chat.js and uncomment the corresponding section.
              */
 
             //** include $log;