1====== DokuWiki Chat AJAX-driven plugin ====== 2 3===== Info ===== 4 5Finally I finished the [[:dokuwiki|DokuWiki]] Chat plugin. After some painstaking polishing it 6is working as expected. 7 8Though the code base is probably not yet ready for public deployment, you can already test its 9functionality here. 10 11This chat plugin is AJAX driven so it means that you do not have to reload page to see new 12incoming messages. 13 14In the info-bar you can see the AJAX engine progress. 15 16If you have Java enabled you can as well have nice sound notification of new messages, even 17with sound volume / muting. 18 19There is already a bunch of AJAX chatting modules available out there. So why I made this one? 20It started as a improvement of Discussion plugin and ended in fully AJAX driven chat. I wanted 21to test the technology and to learn something new. 22 23How to use it? Just type your message into text field below and hit [Enter]. That's it... 24 25 26 27===== Installation ===== 28 29If anybody wish to test this under own DokuWiki installation, feel free to {{:dokuwiki:plugin:dokuwiki-chat-1.1.2.zip?nocache|download it here}} (version 1.1.2),\\ 30[[http://pv.no-ip.org/bin/dokuwiki-chat-1.1.2.zip|Mirror 1 here]] (version 1.1.2), or \\ 31[[http://www.box.net/public/je8m1btjvg|Mirror 2 here]] (all versions). 32 33As have been said, code is probably not ready yet so it may fail to work for you under some 34circumstances, especially if you have older DokuWiki version. Improvements shall follow... 35 36 37 38==== Installation ==== 39 40Unzip ''chat/'' directory into your DokuWiki plugins folder. 41Use included ''local.php.dist'' and add its contents to your ''local.php'' settings file. Change the values accordingly at your will. 42 43The DokuWiki uses the **AJAX tookit library SACK** for all AJAX operations. 44For the chat plugin to work correctly, you need to update **SACK** with latest 1.6 version. 45I provide in the installation zip updated version of **SACK**. It is only one file ''tw-sack.js''. You will have to copy this file over the original file in ''/lib/scripts/'' directory. 46Original ''tw-sack.js'' 1.6 version comes from [[http://www.twilightuniverse.com/resources/code/sack/]] where you can download complete package with documentation and demo. 47\\ Original file miss some ''";"'' on the end of declarations and it did not work well with DokuWiki javascript compression. That is the only modification I made. 48 49==== User rights ==== 50 51Chat messages are stored into separate ''chat'' namespace under the page where it is included. 52So this current page stores chat into '':dokuwiki:plugin:chat:chat'' page. ++ Physical file would be ''data/pages/dokuwiki/plugin/chat/chat.txt'' ++\\ 53 54You will have to setup user-rights (ACL) for ''chat'' namespace. 55 56When only ''Read'' right is set, user can see the messages list but is not allowed to send 57the messages. 58 59==== Chat include ==== 60 61To include chat on your page, use: 62 63%%~~CHAT~~%% 64 65Chat can be included only once per page. 66 67==== Older DokuWiki versions ==== 68 69Chat plugin has been developed under latest development 70DokuWiki version. 71 72If you wish to run it on older versions, you will probably need 73to do some adjustments: 74 75 * If your installation does not include {{:dokuwiki:plugin:events.js}}, download it and put it into ''lib/scripts'' directory 76 * Edit ''ajax.php'' and change all occurrencies of <code>$auth->getUserData(...)</code> into <code>auth_getUserData(...)</code> 77 78==== Server logs ==== 79 80In case you have access to your server configuration, consider excluding Chat 81plugin accesses from access.log. 82 83This is how it can be done for Apache2 (example): 84 85<code> 86SetEnvIf Request_URI "^/wiki/lib/plugins/chat/ajax\.php$" dontlog 87SetEnvIf Request_URI "^/wiki/lib/exe/indexer\.php$" dontlog 88CustomLog /var/log/apache2/access.log combined env=!dontlog 89</code> 90 91===== Internal logic ===== 92 93There are rotating four AJAX checking states: 94 95 - First, new messages are polled each 5 seconds. 96 - After 30 seconds, checking interval is prolonged to 10 seconds. 97 - After another 30 seconds, checking interval is changed to 30 seconds. 98 - Now, mouse-movement over document window is monitored. If no mouse movement occures on document window in one minute, interval is again prolonged to 5 minutes which is longest checking interval. 99 100Now as soon as any mouse movement occures, checking interval is changed back to 10110 seconds and the cycle repeats again. 102 103At any time if something is typed into message box, checking interval is changed back 104to fastest 5 seconds immediately. 105 106This logic ensures that if chatting heat goes high, messages are refreshed fast enough 107and still if there are no people chatting for some time, the polling cools down so 108the web-server is not overloaded with AJAX requests. 109 110You can modify the timings of course, but use common sense here. Although AJAX polling 111requests and responses are short chunks of data and usually complete very quickly, 112if there is a lot of users that have the page with the chat plugin open in browser, 113enough traffic can be generated to bring your server to its knees. So use it wisely... 114 115It is also advised to use some sort of PHP accelerator on the server side to improve 116performance((Latest [[http://eaccelerator.net|eAccelerator]] is maybe the best bet 117if you do not have this already)). 118 119 120==== History ==== 121 122 * <date>2006,11,8</date>, **Version 1.1.2** 123 * Security: Limited length of Name field to 30 characters. 124 * Security: Limited length of Message field. Can be specified in configuration 125 * Security: Filtering of Name field. Now it can consist of alphanumeric characters, dashes, underscores, dots or spaces only. 126 * Added ''audio-notify'' setting into configuration. 127 * Fixed cookies handling to work with newest DokuWiki 128 * Provided updated Ajax toolkit library ''tw-sack.js'' (SACK 1.6 modified), you have to copy this over file in ''/lib/scripts/'' directory. Original comes from [[http://www.twilightuniverse.com/resources/code/sack/]] 129 130 * <date>2006,2,21</date>, **Version 1.1.1** 131 * Fixed regular expression in line parsing. 132 133 * <date>2006,2,21</date>, **Version 1.1** 134 * Optimized sent data, really only new messages are transferred 135 * Limited sending rate so it is not possible to send more than 1 message per second 136 * Added ''$conf['chat']['show-progress']'' for enabling info bar 137 * ''[Clear messages]'' button is now visible for logged-in user that has edit rights for current page 138 * Improved user-rights handling, now user must have write-rights for chat page to be able to see ''[Send]'' button and chat prompt. 139 * More small fixes 140 141 * <date>2006,2,20</date>, **Version 1.0** 142 * Added user rights checking 143 * Added "Loading messages..." text on initial page load 144 * Added error messages when user has insufficient rights 145 146