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
