Ubiquitous D3E User Guide
Ubiquitous-D3E enables you to publish and maintain a discussion environment linked to any website. (The “ubiquitous” bit refers to the fact that you don’t have to have the target page on your hard disk to process it. This is the case with Full-D3E, which uses the Publisher’s Toolkit to process documents more richly. Ubiquitous-D3E’s processing is ‘lighter’, in that it does not modify the target page in any way, hence you can discuss any website that may use any media.)
Ubiquitous-D3E generates an on-line discussion with optional thread topics specified by the creator who ‘owns’ this discussion. Once the discussion is created Ubiquitous-D3E will email its creator to confirm the site’s URL and password protected admin URL, that provides an interface to configure your discussion forum’s behaviour, the look and feel of the site, and manage postings.
The creator can invite colleagues to join the discussion by simply editing/forwarding a second ‘canned text invitation’ email that the server sends.
The web interface includes normal message operations such as list, read and post; send email alert to the interested parties; and providing some other services like message search and statistics.
Please note that you need to understand web server administration to install this properly. Problems may be sent to the Ubiquitous-D3E developer, Gary Li <G.Li@open.ac.uk>, who will deal as best as he can (he has a day job!)
See the demonstration article for an example of a document using Ubiquitous-D3E (where you can post test comments).
Ubiquitous-D3E requirements in brief:
· Software: known to run on the Apache web server and Microsoft's Internet Information Server (IIS); written in PHP; uses MySQL database.
· Hardware Platform: Windows 9x/ME/NT/2000, or Unix/Linux.
If you’ve come this far we assume that you already know something about the Digital Document Discourse Environment (D3E). Relevant background at http://d3e.open.ac.uk
Ubiquitous-D3E is a discussion environment that is used to generate an on-line digital document discourse environment. It also provides tools to maintain the forum including administration, user control, message filtering, moderating and editing.
This version of Ubiquitous-D3E is designed for multiple moderators: the creation, administration and maintenance of all discussion forums can be carried out by multiple users.
Ubiquitous-D3E needs to be installed on a server that runs PHP and MySql:
version 3.22.25 or later http://www.mysql.org
Php4 version 4.0.1pl2 compiled with --enable-track-vars http://php.net/
(most ISPs compile PHP with --enable-track-vars)
or PHP3 version 3.0.6 compiled with --enable-track-vars http://php.net/
(most ISPs compile PHP with --enable-track-vars)
3. Web server
Apache version 1.3.3 http://www.apache.org/, or IIS4+
Download Ubiquitous-D3E from the D3E download site: http://luntan.open.ac.uk/download/d3e/d3e-download.php
You can choose to run it from this site or save it on your hard drive and run it later. Once you start to run it, an installation process will start automatically. You will see the following screen:
Follow the instructions from the screen, until you see the following window:
By default it will install Ubiquitous-D3E into directory "C:\temp\ubiquitousd3e". You are advised to change "C:\temp" to your web root. For example, if your web root on your web server configuration is "E:\web\pubroot", replace "C:\temp" into "E:\web\pubroot", so in the above screen shot, you will have "E:\web\pubroot\ubiquitousd3e". Click "next" to continue. The installer will install Ubiquitous-D3E into your web root and copy all the files into "ubiquitousd3e" directory automatically. Follow screen instructions until finish.
We planned initially to create the database and connect the database from automatic scripts, but for security reasons we will leave this to you to do manually. If you have managed to install MySql, the following procedure will be straightforward. Otherwise please consult MySql documentation.
Under DOS prompt, goto "mysql/bin/" directory and run mysqladmin.exe.
here, <user> is the MySql root user or a granted user who has the privilege to create a database; <password> is the password used by that user.
We assume you now have the privilege to access MySql with full access. The first task is to create a user and password that will be used by the Ubiquitous-D3E scripts. The privileges the user needs are select, insert, update, delete, create, alter and drop for operate. The scripts will use this name and the password to access MySql. To grant a user, we use mysql.exe (client) rather than mysqladmin.exe (server).
If you have a problem accessing mysql, most likely you have used a wrong user name and password. Please make sure you have the correct user name and password. Once you have entered mysql, issue the following statement terminated with ";"
If you want access from another machine rather than where the MySql is installed, you also need to grant the
same user access on any other machines by using the same grant command but change localhost to @%.
Here "d3eforumuser" is the user name and "admin" is the password. You can replace them by anything you like. However, whatever you chose, you need to take a note because they will be asked for later in the configuration.
Copy file "ubiqd3e-phorum.sql" from "ubiquitousd3e\db" directory into the directory where your mysql.exe resides (normally in "C:\mysql\bin\").
This will create three tables: forums, forums_seq and user.
Go to Ubiquitous-D3E administration page from a web browser (http://../d3e-phorum/admin/) and you should see this page.
If you cannot see this page, open file "forum.php.php" in "ubiquitousd3e/include" directory, check that the value of the $forum_url matches the file path in your file structure. Change it if it is not. Try to reload from your web browser. If you still have a problem to see the admin page after reloading, change the value of the $forum_url to "localhost/ubiquitousd3e". Once you see the admin page you can change it back to the full URL of the Ubiquitous-D3E in your web server from the admin page.
Click "Global Settings" on the menu, and "database" from the next level menu as shown in the next screen shot.
The following screen will be displayed on your screen.
Change MySql server name to the name of your local machine, e.g. d3e.blah.org. Input the name of the database you have created by using mysqladmin.exe in this case it is "ubiqforum", then the name and password you have granted by using mysql.exe. Then hit the "Update" button. It will tell you that your operation is successful.
Change your password to keep your site safe.
You are advised to change your Ubiquitousd3eadmin password now (though you can change it any time you like).
Click "Change password" from the "Global settings" then input your new password twice, and finally hit "Update". It has been illustrated in the next screen shot.
Publish your Ubiquitous-D3E web site with URL: http://www.blah.org/ubiquitoused3e
Now your Ubiquitous-D3E is ready for service. You can now broadcast your web page to any interested parties. May be with this document. Once someone has created a discussion by Ubiquitous-D3E. Inevitably, you need to do some administration works such as monitoring, moderating, editing and other security tasks. Ubiquitous-D3E has a lot of administration facilities to support these kinds of tasks. Refers to the next section.
All the forums created by a user initially will take the defaults from the system. You can modify these defaults.
A forum's look and feel, once it is created, is taken from the default feel and look. This is where you can change it. Click "Forum Look and Feel" from the "Global settings". You will see the following form (we have added the visual key on the right to help).
The value of a variable has been indicated on the right hand side of the screen. Enter the value you want then hit the "Update" button on the bottom of the screen. If you are not sure the value of a variable, it is not crucial, you can check it from newly created forums and change it any time you want.
As a system administrator you may be asked to create a completely new feel and look for a discussion site created by Ubiquitous-D3E. This may be because the user wants the discussion to match with the discussion main site or to show their specific logo.
You can create a discussion-specific "header and footer" file. An example is given with this distribution in "example/exHeaderandFooter/" directory. You can view them from your browser. Take them as sample, modify them and save them in the "include" directory. Notice that the name of the files is important. If you want forum 'dics5' (table name of the discussion, can be find from the "Edit Forum Properties") has the new header and footer, you need re-name them to header_disc5.php and footer_disc5.php respectively.
There are a number of options, which will affect a forum's look-and-feel. You can switch them on/off here. Click "Forum Options" from the "Global settings" you will see the following form:
Variables you may wish to change are d3e_forum_name, default email, and smilies.
* D3e_forum_name is used when an email alert is sent to a user through your email system. It appears in the subject field to indicate the source. The current setting will thus look like this in the email message Subject line:
* Default email address is used in two places. One is used in the "From" field in an email message; the other is to set an email account with this "box name" so that a user reply the email message will be inserted into the forum (threading email replies back into the web page is not available in this version).
* Smilies are a set of preset small icons that can be used to indicate the nature of a message. This function can be switched on/off from here. Managing the actual smilies themselves is explained in the next section.
Similar to email, smilies in Ubiquitousd3eare icons used in subject and body of a message to indicate either the sender’s feelings/emotions, or perhaps to classify a message (e.g. you could design icons for Action Item, Question, Problem, CounterArgument, etc). It can add flavour, but it can also make a serious message appears less formal. Therefore use it or not is merely a preference.
Smilies work only in a ‘smilies-aware’ forum. It works through typing "short-cut" into desired place like subject or body of a message. The number of icons, the appearance and the shortcut can be modified, deleted and added through this facility. Clicking on "Smilies" from the "Global settings" gives the following screen:
and remove existing smilies.
Default smilies are listed in the table (see above). Notice that each smilie has a short-cut associated with it. You can change the short-cut by typing in the new one; you can also remove a smilie by ticking its Remove checkbox. Hit the "Update" button to register the changes.
In order to add a new smilie, you have to create the new smilie first. You can either select one smilie from the directory "d3e-phorum/images/extra_smilies/" or create a brand new one in an image processing tool. If you create a new smilie, you need to be aware of the image size (check an existing one). You then move the smilie into " d3e-phorum/images/smilies/" directory.
Now you can go to Ubiquitousd3eadmin and click "Add smiles" button. In the next screen type the smilie's src in a format of "smilies/boo.gif" then the short-cut you want to be associated with that smilie. Hit the 'Add' button. See next screen shot.
Once the system has been installed by the administrator (as above), there are then two kinds of users: forum creators and the end users. The forum creator uses Ubiquitous-D3E to publish a discussion site. The end user participates in the discussion (see section 3.5 end user notes).
A forum creator can use Ubiquitous-D3E’s administration interface to:
From your web browser go to Ubiquitous-D3E site. The following screen will appear:
Complete the form and hit the "Generate D3E Discussion Site" button.
Your name is used to identify the discussion’s creator to other users, and the email is used to send you the URLs for both the discussion site and the administration site. The password gives you access to the forum administration site.
Once a discussion site is generated for you, the system will send you two email messages and two URLs.
The first email looks like this, with Subject: "Discussion about <URL> has been created":
The administration site needs the password you set when completing the form (also sent to you in the email as a reminder).
The second email message is prepared for you to forward to your colleagues as an invitation to the discussion, which you can of course edit/augment as you please before forwarding:
Ubiquitous-D3E provides two separate methods to customise a forum's look and feel.
Go to forum admin (ubiquitousd3e/admin/) from a web browser. Enter the password you entered once you were creating the discussion. A list of forums you have created will be listed. Choose the one you want to change.
In the next page, click "Edit Forum Look and Feel". A form will show up with a list of variables and default values. See the next screen shot.
Enter the desired value and click "Update" button. Once it backs to the menu, you can check your change by click "Changes Check Up". You can do this repeatedly until you are satisfied.
You can further customize your forum by adding images at the top or bottom of the discussion:
Contact your system administrator about creating new "header and footer" files for your forum.
Once your forum is published on the web, you can control the whole discussion and study the discussion through Ubiquitous-D3E administration facilities.
There are many properties in a forum that can be modified from the default values. These include the discussion title, email list, and many other switches. Click on "Edit forum's property", once you have chosen a forum, the following screen will appear:
Edit as necessary, and hit the "Update" button at the bottom of the page.
Once you choose
"moderation", you have to provide a moderator's email address. It is
used to send an email message to the moderator when a new message has been
posted, who can then click on a URL to either accept, reject or edit the
posting (see section 3.5.1).
"HTML allow and disallow" has the following differences. "HTML disallow" defines a forum which still allows limited HTML formatting tags: <b>, <u>, <i>, <ul>, <ol>, <li>. In addition, any URL will be made an active link.
“Full HTML” can be
used if the forum is set to "HTML allow".
"Use Smilies" allows such icons to appear anywhere in a message.
You can change the password you used to create the forum. If you use a single password in all your forum creation, once you enter that password in the administration site, all the forums you have created will be displayed in a list. You can therefore use different passwords to group your forums into different groups. Once you enter a password, only the forum by that password will be displayed.
Change password is done by entering a new password in "moderator's password" from "Edit forum's property". Look the following screen shot:
The new password will be effective after reload or re-lunch your browser.
Asking your browser to remember your password using cookies occasionally does not take effect immediately, but usually works.
Ubiquitous-D3E administration provides two different ways to access a message in a forum. One is "Easy admin" another is "quick access".
· "Easy admin" gives full access to all the messages in a forum.
Click on "Easy Admin (Delete/Edit/Hide Msgs)". In the next screen all messages are listed Specifically, the message id, author and post date are displayed (you may need to know id for other quick operations such as delete, edit, approve or hide).
On the right of screen three possible actions are supported. Delete purges the message from the forum. Once a message has been deleted it can not be recovered. You can edit a message by click 'Edit'. You can hide a message by click 'Hide'. Hidden message becomes invisible to user. You can always turn it into visible by click 'Approve'. 'Approve' option only appears once the message has been hidden.
· Quick access is a shortcut to operations on a message that you know its message number. See next screen shot. The message ID number can be found from either an email you received or in the "easy admin" display above.
There is not a lot of maintenance work needed in Ubiquitous-D3E (one of the reasons why you may like using it!). However if you need, Ubiquitous-D3E allows you to do:
· Reset the sequence of message ID
· Deactive/re-active your forums
· Remove your forums from service
Once you carry out many message deletions on a forum. It is most likely that the message id will be disoriented. You can reset msg Id to the next maximum id number in a forum. so the msg id will not appear in a large number. Click on "Reset Sequence of Msg Id" (See next screen shot).
Deactivating an existing forum removes the forum from visible service but does not completely remove it from the system. It can always be activated later. People subscribed to the forum will receive a friendly message saying that the forum is temporary down for servicing.
“Dropping” a forum purges it permanently. It is wise to deactivate a forum for a while before dropping it.
Moderation is another feature of Ubiquitous-D3E, allowing you to check submissions before they appear.
Click "Edit Forum Property", then from the drop down list select moderation method, enter your email address, if you want a new password you can change it by entering a new password (that will be your new password to enter the forum's administration page. It is illustrated in the following screen shot.
Once "moderation" is set to "before post", for any message posted to the forum the moderator will receive an email message offering three actions: accept, reject or edit (and three corresponding URLs):
then one could simply click on different links for different operations.
Alternatively, the moderator can always go to "Easy Admin" from the administration page to do the same. In a moderated forum, new messages will not appear on the discussion site. The next screen shot illustrates this. A message from Simon is posted after "moderation -- All message before post" has been switched on. This message is not visible to end users on the discussion site but is visible from "Easy Admin", with "Approve" offered as an action.
(However, a message posted by "Gary" is visible to all users even after the forum has been switched to "moderation -- All message before post". The reason is that "Gary" himself is the moderator, and we assume that postings from him don’t require moderation)
Ubiquitous-D3E provides a simple statistic facility to shows the usage of your forums. A more thorough analysis can be achieved from a specialist information server log.
This statistics offered appear as follows:
Click "Show Statistics on Forum" from the menu, select the duration from the drop down list, then click button "Show". </div></div><div class="ack"><div class="back"><div class="section"><div class="middle">
The threaded discussion interface is relatively straightforward and self-explanatory. However, here are a few hints on things that are not so obvious, e.g. getting formatting into the content of messages.
Ubiquitous-D3E has two different email lists in a published document. One is on the document level. If you subscribe to this list, Ubiquitous-D3E will send you an email copy of any new comments posted to the forum. The other level is on the message level, where you can specify that you want to be notified by email of any new replies to a specific message.
To subscribe at the document/whole discussion level, click on "Subscribe" at the top-left corner of the discussion page (see next screen shot):
A new page prompts you to enter your email address. Hit "Submit" button:
You can always unsubscribe once you have received an email message. Every email message has a footer with a link that will direct you to the unsubscribe page.
To request email notification of all replies to a specific comment you have made, in a forum's post comment page (see next screen shot), simply tick the box at the bottom: "Email replies to this thread, to the address above":
When you compose a comment, you can use some HTML tags and links in your message. The following box lists what you can use and how.
In addition, if a forum has been set to "allow html" (contact your moderator), full html is allowed that means you can post your message in a completely html format.
You can also quote the message you are replying to by clicking "Quote". The text appears, ready to insert your comments.
Ubiquitous-D3E is developed at the Knowledge Media Institute, Open University, UK by Gangmin (Gary) Li and Simon Buckingham Shum. The D3E Project gratefully acknowledges the support of BP Amoco Exploration, Sunbury-on-Thames, UK, in developing this software.