CourseForum and ProjectForum

Changing List Styles.

If you have nested numeric lists, ProjectForum follows the default HTML approach of numbering them with decimal numbers, for each level of the list. But, you can change this if you'd like, so that nested levels are 'numbered' using a different scheme.

For example, insert the following bit of CSS into the main stylesheet of a custom theme:

    div > ol { list-style-type: decimal; } 

    div > ol > li > ol { list-style-type: lower-alpha; } 

    div > ol > li > ol > li > ol { list-style-type: lower-roman; }

The first level will still appear as "1, 2, 3...", but the second level will now be "a, b, c", and the third level will use "i, ii, iii...".

This tip courtesy of Pancho Castano.

Tip: Hiding the 'Create New Group' button.

The site home page (which lists all groups on the server) contains a form with a 'Create New Group' button in it. The way most sites are set up, pressing the button will ask for the 'create group' or 'site administrator' passwords. (There is of course an 'anyone can create groups' setting in Site Admin to bypass this).

If you really do want to hide the button (from everybody, including admins), you can do so via a little HTML and Javascript trick. In Site Admin, go into 'Messages', and then at the end of your 'Home page message', add this:

	<script>document.forms[0].style.display = 'none';</script>

If you later want to create a new group, you could just remove the line, create the group, and put it back.

Making your Wiki Successful.

For those people wondering about how best to introduce your ProjectForum wiki to your workgroup, encouraging more and better use, or wondering why nobody really cares, there's a great web site you need to check out.

The site is wikipatterns.com. It contains a set of so-called "patterns" and "anti-patterns" — generally good (or generally bad) strategies and approaches that may be of help (or may hinder) your wiki's usage and adoption.

A book version of the site was also published a month or two ago.

Version Six Editing Tips

Thanks to Wayne MacPhail at w8nc, who has kindly let us share this information on the new editor he prepared for one of this clients using ProjectForum.

Originally, there was just one way to markup text for use in ProjectForum.

That was by using the simple markup language, you are all familiar with.

Later versions introduced a toolbar:

to add bold, italic, headline, underline and formatted list formats to our text.

We could even use it to add links to other wiki pages, websites or email addresses.

Now, with Version 6 of the ProjectForum software, we have a new way, called Rich Text Editing. Rich Text Editing allows you to create formatted text in ProjectForum much like you would when you use Microsoft Word or another word processor.

You also still have the option of using the older Source Code Editing you're used to.

Here's how to switch between the two.

If you look in the upper right-hand corner of any editing window, you'll now see a set of three icons beside the "Preview" text link:

In the image above, the editor is set to the Rich Text Editing mode. You can tell this because the icon has the <> symbol in it. To shift to the older Source Code Editing mode, just click on the icon circled in red above. The icon will now look like this:

And you'll be able to format text the way you have in the past. You can work in either mode, the choice is yours.

What's the advantage of the new Rich Text Editing?

Let's take a look. Here's a snapshot of text formatted and displayed using the old style, Source Code Editor:

and here's the same text as it appears when you're using the new Rich Text Editor:

As you can see, the Rich Text Editor version looks more like regular word processor text. So, it should be easier for you to enter and format text than using the old Source Code Editor.

You'll also notice that there are some additional icons in the tool bar at the top of the Rich Text Editor window.

You can now indent (and outdent) paragraphs you've formatted as ordered lists, using the new indent and outdent tools:

You must first convert a paragraph to an ordered list prior to using the indent or outdent tool. Here's an example:

• Line one
  
  • Line two
    
• Line three
  

In the example above I made a bulletted list (a form of ordered list) of Lines One, Two and Three. I then used the Indent tool to make Line Two a sub-bullet under Line One. You'll note that the line not only moved over to the right, but also gained a hollow bullet point automatically.

You'll also notice you have two more new icons, undo and redo, the curved blue arrow icons:

These allow you to easily undo, or redo the last change you made to the page.

Finally, there is the powerful table icon:

It's long been possible to make simple tables in ProjectForum, but it involved the careful use of | symbols as cell and row end dividers. Tables are much more powerful and easy using the Rich Text Editor. When you click on the table icon, now you'll see an empty, four-celled table inserted in your text. In the image below, I've filled each cell with some text.

Once your cursor is in your new table, you'll see that the table icon will have a new set of icons strung out to the right of it, as show here:

From left to right, these icons allow you to:

• Insert a column to the right of the column your cursor is in
  
• Insert a column to the left of the column your cursor is in
  
• Insert row beneath the row your cursor is in
  
• Insert a row above the row your cursor is in
  
• Delete a column
  
• Delete a row
  
• Left justify the text in a cell
  
• Centre the text in a cell
  
• Right justify the text in a cell
  
• Add a border to your table (the default state is no border)
  

Tip: Bug Reports

When you're running into problems or think you've found a bug in CourseForum or ProjectForum, we'd obviously like to hear about it.

When it comes to us tracking down and fixing the bug, the process generally involves us trying to duplicate the bug in our environment, which makes fixing it much easier. The more information we have from you, the more likely we are to be able to duplicate it. That's where your bug report is so important.

For starters, we want to know some basic things: what operating system are you running your server on, what operating system and web browser version are you running on your own machine, and so on.

Next, a description of what you're seeing, and how that is different than what you expected, is very helpful.

I was on such-and-such page at such-and-such time. Looking at the edit screen, I expected to see X, but instead I saw Y. I then tried to do operation A, and expected to see B as a result. Instead, I got C.

Screenshots that show the problem are also very helpful. On Windows, here is a web page that describes how to create and mail a screenshot. On Mac OS X, hit Command-Shift-3, which will save a picture of your entire screen to your desktop, which can then be attached to an email.

Web browser errors, particularly Javascript errors, can also be very useful to us. You'll find an item in the menus of most web browsers named "Error Console" or "Javascript Console" that will display any of these errors. For Internet Explorer, this page describes how to look for and view Javascript errors. In either case, sending us the full contents of the error message may be a big help.

Tip: Copying data from Excel

Here's a simple little trick, courtesy of Ian Yorston. If you've got a bunch of data in an Excel spreadsheet that you'd like to copy into ProjectForum, you can use Excel's 'concatenate' function to build up a ProjectForum table from your data.

So let's say you've got a three column table, starting at cell A1, and going down a whole bunch of rows. Somewhere else in the spreadsheet, enter this into a cell:

=concatenate("| ", A1, " | ", A2, " | ", A3, " |")

Next, use 'Fill Down' to create lines for each row of the table (B1/B2/B3, C1/C2/C3, etc.).

Copy the resulting cells (one column wide by the number of rows in your original table high) into ProjectForum, perhaps prefacing it with "[tablestyle:borders]" if you'd like to show a grid.

Tip: Getting a sense of forum activity.

If you've ever wondered how much people are using your forum, whether making contributions or just reading the material that is there, it's easy to get an overall feel for this.

In a ProjectForum group, go into the Group Administration pages, and click on "Activity" at the top. This page will let you see a summary of all the activity in the group over a period of time, broken down by number of page views, number of page edits, number of posted comments, and number of downloaded files. If you have the group set up so that people require passwords, you'll also see this breakdown for each user.

Because most people don't use this information, by default collecting activity information is turned off. Turn it on by changing the "Keep activity logs for:" setting and clicking "Save Changes". You probably only want to keep a limited amount of activity (say, the last month). This will both make the statistics more meaningful for recent activity on the forum, and also save collecting possibly large amounts of data which can sometimes slow the system down a bit.

Tip: Archive old groups.

It's not unusual that after using ProjectForum for some particular piece of work, that you'd like to then move on to some other task. While you're not going to be working on the older stuff any longer, you'd like to keep it around for future reference.

It makes sense to start a new group for the newer work, rather than continue using the old group and mixing up the new and old material. Luckily, this doesn't mean that you need to purchase a larger ProjectForum license to accomplish this. You can instead archive old groups that you're no longer using.

Archiving takes a group and makes it read-only; you can no longer make any changes to it, but you can browse through the group to view all the material in it. You can have as many archived groups as you like, and they don't count against the number of groups permitted in your license. So every time you archive a group, you can create an additional group for current work.

To archive a group, you need to sign in as the Site Administrator. On the ProjectForum home page, click on the icon next to the group you'd like to archive, and then on the subsequent page, click the Archive button. If you find you'd like to later re-activate the group, and you have room left on your license, this can also be done from the same page.

Tip: Co-existing with another web server.

At its heart, you can think of ProjectForum as just a web server, albeit a very special-purpose one. If you're already running a traditional web server (Apache, IIS, etc.) on the machine you'd like to run ProjectForum on, you might want to think about how the two will co-exist with each other.

It's worth noting that you normally don't have to worry about this. ProjectForum runs independently of your existing web server; it does not depend on it, nor any components (e.g. PHP, MySQL, etc.) that your web server may normally use. As well, by default ProjectForum runs on a different port (3455, vs. 80 for your web server) so you shouldn't have conflicts there.

What if you want them both to run on port 80? This might be because of firewalls, convenience for your users, or some other reason. Depending how your machine is set up, this can be done in several ways.

Do you have multiple IP addresses for your machine? If so, you can use the -address flag to get ProjectForum to listen on just one of the addresses. You'll also of course have to make sure that your existing web server also is just listening on one address (not the same one obviously). All web servers should allow specifying a single IP address to listen to (rather than by default listening to all addresses), but some are a bit more reluctant to do so than others (*cough* IIS *cough*).

If you have a single IP address but can provide multiple network names for that address, you can use name-based web proxying, which is often used for virtual hosting. We have a Proxying HOWTO that describes in more detail what this is about and how you might go about setting it up.

Finally, you may also want to integrate ProjectForum so that it appears as part of your existing web site. Again, proxying will help you do this (though in this case, it won't be name-based proxying, but proxying from a particular directory in your web server). You may also want to think about creating a new theme to modify the appearance of ProjectForum to look more like other pages on your existing web site.

Tip: Using ProjectForum as a Content Management System

This tip is courtesy of Steve Landers of Digital Smarties, an innovative software consultantcy based in Perth, Australia.

We manage a bunch of websites both for ourself and our clients, and for a long time we've thought it would be nice to use ProjectForum to manage the content of some of them. With the Web Views feature in version 5.5 we've been able to do just that!

Web Views provide a view-only mirror of a forum whose content is updated as the forum changes. This in itself is great for managing a website, but there are a few ProjectForum features that allowed us to take this further - Custom Themes, the Include Markup, Key Pages, the Comments Markup and HTML tags.

We use Custom Themes to create two versions of a theme - one for maintaining the site (we just picked one of the built-in themes) and a copy of it to use with the Web View. In the theme for the web view, we then modified the #pageheader and #pagefooter sections in the Main Stylesheet with something like "#pageheader, #pagefooter { display: none }" so that the page header and footer don't appear (they'll actually still be there, but just not visible to the user). This stops the current page, forum name and key pages from appearing in the web view.

We wanted to include standard headers and footers on most pages. We did this with the Include Markup - e.g. added a line containing "[include Header]" to the top of each page visible in the Web View, then created a page called "Header" containing the markup we wanted to appear on each page. A typical use might be to include a logo at the top of each page, and some shortcut links at the bottom of each page. We found it convenient when maintaining the Header and Footer pages to add them to the Key Pages section of the Group Administration page.

An addition to web views that we requested has helped a lot with maintaining the site. Now if you include a comments divider on the page ("===comments===" on its own line), anything after that won't be shown on the web view. So now we can post comments in the page that won't appear on the site. This provides a convenient way for us to document the reason for changes, leave notes for each other, or maintain a To Do list on each page.

To get some of the cosmetics just the way we wanted them, we used a small amount of HTML tags in addition to the built-in ProjectForum markup (available by selecting the "Allow use of HTML tags" checkbox in the Settings section of the Group Administration page).

Tip: Ideas for getting the most out of collaboration.

Everyone's got their favorite weblogs, and I wanted to share one that will likely be of interest to many CourseForum and ProjectForum users.

Michael Sampson is an independent analyst and consultant, based in New Zealand. His expertise is in collaboration technology, and how best to apply it within organizations. While a lot of his energies are devoted towards enterprise-scale deployments, there's still obviously a lot of overlap with the workgroup-sized situations where ProjectForum is most often used.

Almost every day he publishes his "Enterprise Collaboration and Virtual Teams (EC/VT) Report", pulling together various bits of information from the industry, media, blogosphere etc. into a nice concise report. His reports consist of three parts. The first, the "People part" of EC/VT is the most relevant, providing all kinds of insights and strategies into making collaborations and teams successful. The second part, "Technology trends" of EC/VT is helpful if you're interested in keeping up with the latest from many of the various collaboration tools vendors. Finally, "Insights on being productive and effective as an individual" brings together various tools, techniques and ideas for personal rather than group productivity.

Keeping up with all that's going on in this rich and diverse area is tough, but Michael's blog helps make it easier.

Tip: Structured information.

A wiki like ProjectForum doesn't force a particular structure on pages, which can be both a strength and a weakness. Keeping things flexible makes it easy to adapt to particular circumstances and exceptions, because rather than everything being a strict field, it's just text.

That doesn't preclude keeping information that is more traditionally structured in ProjectForum. Let's say you want to keep track of a set of people who have contacted your company, with the usual information like name, company name, phone number, and so on.

The ProjectForum model for doing this is to first create a page template for 'Contacts'; a page template being some boilerplate that you can choose to insert into a newly created page. For our contact page, it would have the usual name, company etc. areas. Again though, these would be plain or simply formatted text (look at some of the built-in templates for examples). Each page would also contain a link at the bottom to a page named 'Category Contacts'. That page can contain a list of all the contact pages (automatically built up by the links in each to the category page).

So when someone wants to add a new contact, they'd first select 'New Page', and then choose your 'Contacts' template from the menu at the top. The template would be added to the page, and they could begin filling in the information. Also, since it is freeform, they can delete information that isn't relevant, or add other information that is relevant. And because it's just like any other page, others can edit the information, add their own notes about the contact to the page, and so on.

Want to find all the contacts? Visit the 'Category Contacts' page, or do a search for 'Category Contacts' (since you know that appears in each page). Want a report of all the contacts, including the full information on each? From the search results page, select the 'Include page contents in results' checkbox and search again.

Tip: Convincing your group.

One of the challenges in incorporating a system like ProjectForum into your workplace is getting people to actually use it. We hear comments like this one all the time:

As the administrator, I think the software is fabulous.  It’s getting the users to actually use it that has become our problem.  It’s a behavior modification that people find hard to adopt, apparently.  We send tantalizing emails to get them to go to the wiki  for information.  I'm thinking of deliberately putting up incorrect information just to make them fix it...

Or this one:

I am actively encouraging my team to use the ProjectForum wiki now to improve collaboration. As we have traditionally not had anything 'central' to support our collaboration efforts, many people in the team have created their own way of doing things, e.g. their own websites, public folders, email lists etc. Encouraging them to change to all use a standard wiki is going to be an interesting challenge. I have to show them that there is value to going to the effort of changing to the wiki, otherwise they won't adopt it.

If these sound familiar to you, you're not alone. Changing existing behaviors is a lot harder than just installing some software and crossing your fingers! This is especially true with software that supports groups, because even with one or two holdouts (if they are critical) it can derail the whole thing.

In fact the whole issue of how to adopt so-called groupware technologies is a not only a large practical question (and one where there are a lot of consultants who may be able to help) but also an ongoing topic of interest in the research communities involved with these sorts of technologies.

We don't have any silver bullets to offer, but here is some general advice:

• first and foremost, make sure there is a benefit for the people using the system; if it's not useful or helpful to them, you've got an uphill battle right from the start. If the system only benefits others (e.g. upper management) and so is instituted by decree, there will be a lot of resistance, not to mention many more Dilbert cartoons appearing on cubicle walls
  
• lead by example; the more you (and anyone else in the initial group of people that was motivated to start using the system) need to generate a lot of the content, taking the lead in migrating other sources of information into the system, spend time helping people get started, and so on
  
• start small, but keep building; obviously, coming in and replacing everyone's existing work practices all of a sudden will cause a huge amount of anxiety. Pick an area that's been a problem in your group, and use that as the first thing you put up on the system, and get people using it. You'll want to add other types of materials to keep the initial momentum going
  
• look for opportunities to transition from other communication media; for example, if you want all meeting agendas to be in the system, email the group a link to the page in question, rather than the contents of it, which will provide more exposure to the system. Similarly, if people are emailing documents around, create a wiki page with the latest version, and point people there. Questions that come up in meetings might better be answered with "I'll create a wiki page about that" instead of "I'll email you about it"
  
• and of course, work with your team, not against them; you'll figure out as a group what things make sense to put into the system, and what things are better left elsewhere. Listen to people's concerns, and realize that any change in work practices may be not only uncomfortable but can have both intended and unintended consequences in terms of productivity, work satisfaction and more
  

Any suggestions of ways that you've found that have made it easier for a group to more successfully adopt ProjectForum?

Tip: Collaborating on documents.

A great use for a wiki like CourseForum or ProjectForum is collaborating to produce some new document, such as a report. While it may be obvious, at least in the early stages it probably makes sense to do a lot of your work directly as wiki pages. Collecting references, making outlines, writing sections and commenting and discussing as you go just make sense. This is particularly true when you have tools like 'versions' and 'track changes' to help you keep track of what's changed.

Sometimes though, you'll end up with your material in a Word or Excel document, or something else, but you still want to work together on it. In the "bad old days" you'd end up mailing multiple copies around to everyone in the group as you make changes, clogging up everyone's mailbox with large attachments and leaving everyone to wonder what the latest version is.

In ProjectForum, you can at least attach documents to each page (and replace them with newer versions), so at least you'll save the hassle of emailing things around and wondering where to go to find the latest one. But if you've got several people working on things at once, you need more than that to keep coordinated.

We often get asked if there's a way to "lock" a document, so nobody else can make changes (i.e. while you're making your own changes). There's not, and that is on purpose. There is a better way: communicate.

If you're going to be making changes and you don't want anyone else mucking with it, just leave a note in the wiki page (e.g. as a comment, preferably placed right beside the attachment). Even better, let people know what you're mucking with, e.g. "Nancy is currently rewriting the introduction". Everyone else will see that note on the page, and not make their own changes until you're done, particularly in the introduction. Someone else may decide to work on another part, leaving notes like "Bill updating the data analysis.. will merge in after Nancy's changes are posted", followed by "Ok Bill, changes made, merge away - Nancy" and so on.

Being able to communicate in this way, right alongside the documents you're working on, brings with it all kinds of benefits, and provides a much richer way to coordinate than simply locking an entire document. It's one of the big advantages of using a tool like a wiki to coordinate document preparation, rather than a simple file store or shared drive.

Tip: America's loss is your gain, for now anyways.

Anybody who's been keeping even half an eye on currency markets over the last while has seen the American dollar tank against most other world currencies. Without commenting on any of the political decisions that might just possibly have led to the current lackluster economy (oops) and subsequent currency devaluation, there are some positives, especially for people outside the USA.

In particular, since the prices for CourseForum and ProjectForum licenses (priced in US$) have stayed the same since January 2006, for all you Europeans, Aussies, Canucks and others, licenses are effectively 15-20% cheaper than only a couple of years ago. So perhaps it might not be too bad a time to reconsider purchasing a new license or upgrading an existing one...?

Because we're in Canada, the currency drop unfortunately cuts into our bottom line. While for the time being our prices aren't increasing to compensate, this is something we'll be re-evaluating early in the new year. Something to consider if your purchasing decisions take a considerable amount of time, but rest assured if we do make any changes, we'll give at least a few weeks advance notice.

Power Users: Even more on theme customization.

Last week talked about some of the basic ways that themes can be customized, to change the look and feel of pages in CourseForum and ProjectForum. Things like adding images, changing fonts and colors, removing elements from the page, or moving things around are fairly straightforward to do with a working knowledge of CSS.

But there are limits in terms of what you can do. With regard to moving things far outside of where they were intended to be, we said:

Mucking with positioning is similarly straightforward... except when it isn't. Like most web pages, those in CourseForum and ProjectForum are built up with various nested divs, spans, and so on. If some element is defined within some other element, this can be tricky. For example, the "shortrecentchanges" <div> is located inside an outer <div> with an id of "viewbox". So if you want to position "shortrecentchanges" in an entirely different place on the page, effectively outside of the area occupied by the "viewbox" that can be almost impossible to sort out in CSS.

So as an example, here's what we'd like to accomplish. Take the "shortrecentchanges" area (which we've already shown how to hide from up near the top of the page), and place it just below the "post your comments" box, near the bottom of the page, which is itself located in a <div> with an id of "commentarea", definitely outside of the "viewbox" <div>.

Ok, so can it be done? Yes, but it requires using not just CSS, but also a bit of Javascript.

While using CSS doesn't require us to add anything to the HTML page, using Javascript does mean we need to modify the page. Luckily, themes give us the ability to insert arbitrary HTML (and thus Javascript) code into any page. This is done through "HTML includes", as described in the custom themes HOWTO.

For the sake of keeping the Javascript in this example a bit simpler, we'll use a Javascript library called Prototype, which takes some of the drudgery away from writing Javascript. Prototype is actually included in CourseForum and ProjectForum, as it's used on the edit page, and in a few other places. So the first thing we'll need to do is include Prototype itself into our pages. To do so, go into the theme editor and modify the "pagetop" include to read:

<script type="text/javascript" src="/admin/prototype.js"></script>

Now, what we want to do is insert the same HTML that is used in "shortrecentchanges" at the bottom of the "commentarea" <div>. Modify the "pagebottom" include in the theme editor to read:

<script>

/* only do this on the view pages that have a shortrecentchanges area! */

if (document.getElementById('shortrecentchanges')!=null) {

   new Insertion.Bottom($('commentarea'), $('shortrecentchanges').innerHTML);

}

</script>

After you save the theme changes, and then reload a forum page using that theme, you should see the recent changes area show up underneath the post your comments box.

This only scratches the surface of what is possible using Javascript to manipulate the DOM that describes the web page. It's possible to move things around, change existing elements, add new ones, and a lot more. No, it's not necessarily easy to do all this, and does require knowing CSS and Javascript, but with a bit of work, it is possible to make some changes you'd never thought were possible.

Tip: Existing documentation and resources.

Just a reminder of a few of the available resources to help you learn more about CourseForum or ProjectForum, the features that are available, and what to do if you get stuck:

• If you're just getting going, our getting started page is a great resource.
  
• The User's Guide is a PDF file that will take you through how to use the software in details.
  
• Our Frequently Asked Questions page contains answers to some of the most common questions about setting up, administering, using and licensing the software.
  
• On the top of our FAQ page you'll also find links to a number of "HOWTO" documents, which provide information on some of the more advanced and/or esoteric things you can do with ProjectForum.
  
• Our support forum is a ProjectForum site where you can ask questions and more
  
• Of course, you can also email us at support@courseforum.com about any aspect of the software. Whether it's a question, suggestion, compliment or complaint, we'll be happy to hear from you.
  

Power Users: Theme Customization.

CourseForum and ProjectForum come with a number of built-in themes, which govern the look and feel of each page. It is also possible to create a new custom theme, which is done by the Site Administrator, using the Theme Editor.

For the mostpart, creating a new theme requires some knowledge of CSS (a.k.a. "cascading style sheets", which is what most websites use to control their appearance). Typically, you'd create a new theme based on one of the existing ones, and then make one or more tweaks to the CSS for the theme to create the look you want.

Some things are pretty easy to do. For example, changing colors and fonts isn't too bad. Adding images (such as a company logo) is also pretty straightforward. You can also do things like playing with the positioning of certain elements, or hiding them altogether. To do this, you first need to figure out exactly what element to modify, which you can do by viewing the HTML source of a page using the theme.

For example, let's say you've created a new theme based on the standard one, but would like to remove the recent changes area at the top of each page in the forum, just under the blue bar. Go into a forum page, and do "view source" in your browser, and you'll find in there something like this bit of HTML code:

<div id="shortrecentchanges">

Changes [Sep 14, 2007]: 

<a title="Modified Sep 14, 2007" href="10">Home</a>, 

<a title="Modified Sep 14, 2007" href="8">Help</a>, 

 ... <a href="Changes">MORE</a>

</div>

So the recent changes area that is being displayed is contained in an HTML <div> having an id of "shortrecentchanges". If you then go into the CSS file for your theme, you'll find a style named "#recentchanges" which controls how that block of HTML is displayed. So if you wanted to remove it altogether, you could change it to read:

#shortrecentchanges { display:none; }

Mucking with positioning is similarly straightforward... except when it isn't. Like most web pages, those in CourseForum and ProjectForum are built up with various nested divs, spans, and so on. If some element is defined within some other element, this can be tricky. For example, the "shortrecentchanges" <div> is located inside an outer <div> with an id of "viewbox". So if you want to position "shortrecentchanges" in an entirely different place on the page, effectively outside of the area occupied by the "viewbox" that can be almost impossible to sort out in CSS.

Or is it? More on that next week...

Tip: Selectively restoring older content.

The "Versions" link near the bottom right of each forum page is a very useful facility that lets you review each and every change made to the page over time. You can quickly see who made each change, when the change was made, and exactly what on the page was changed.

It's also easy to restore the page to an older version. This can be useful if you'd like to remove one or more inappropriate changes to a page, and return to the last good version. To do this, you'd use the "Prev" and "Next" buttons to navigate to the version you want, and click the "Make this Version Current" button.

But what if you want to restore just a part of an older version of the page? So for example, there was some good material that was accidentally deleted a while ago, that you'd like to bring back. But, you don't want to lose all the other changes that have been made since then.

This too can be done with the Versions tool:

• Again, navigate using "Prev" and "Next" to the older version that contains the material you want to reintroduce to the page.
  
• From the "Show:" popup, choose "Unformatted version of the page". This will show you the content of the page as it would appear in the Edit window.
  
• Select the material you'd like to restore with your mouse, and copy it to the clipboard via the "Copy" command from your web browser's "Edit" menu.
  
• Click on "Back to Page" to exit the Versions area.
  
• Click on "Edit this Page" to bring up the Edit page, paste the material (with the browser's "Paste" command) into the editor in the appropriate location, and then save your changes.
  

Power Users: More on Automation.

Last week we provided an example of having a Perl script use ProjectForum's web interface to add a user to a page. Here's a similar example, this time where the script posts a comment to a forum page. The first part is pretty similar, setting up some variables with the information the program needs, and then logging in as site administrator to ensure our script has full access to the entire site.

my $siteurl = "http://127.0.0.1:3455/"; # base URL of the site
my $siteadminpass = "abc123" ; # site administration password
my $urlprefix = "1" ; # URL prefix of the group we're posting to
my $pagename = "Home" ; # name of page we're posting to
my $username = "Joe User" ; # name of user posting
my $message = "This is my post" ; # what to post

use HTML::Form;
use LWP;

my $ua = LWP::UserAgent->new;
$ua->cookie_jar( {} );

# signin as admin, which will set the cfadmintoken cookie
my $response = $ua->get($siteurl . "admin/adminsignin.html");
my $form = HTML::Form->parse($response->decoded_content, $response->base);
$form->value("adminpasswd", $siteadminpass);
$ua->request($form->click());


This next bit is what actually does the posting; it's a bit tricky in that we have to find the right form to post to (there are normally two, the search form and the comment posting form):


# now go to the page and do the post
$response = $ua->get($siteurl . $urlprefix . "/" . $pagename);
my @forms = HTML::Form->parse($response->decoded_content, $response->base);
for ($i=0;$i<@forms;$i++) {
   my $form = @forms[$i];
   my $attrs = %$form->{'attr'};
   if (%$attrs->{'name'} eq "commentform") {
     $form->value('comments', "[" . $username . "]: " . $message);
     $ua->request($form->click());
   }
}


The value of this isn't in these simple self-contained examples of course, but when you embed them into some other script. A few simple examples:

• You have some other program that runs every day to produce some summary sales data; it can then use this script to post the results to a ProjectForum page.
  
• Your ecommerce system can automatically post a record of every transaction into your forum.
  
• You can hook up your email (e.g. with postfix) so that when you receive email at a certain address, it runs a script which automatically posts that email into your forum. Your email script might use the subject of the email to decide exactly which page in the forum the email gets posted to.
  

Tip: Enabling tracking changes by email.

If you want to keep track of what's going on in a forum, continually going back to a page in your web browser to see what's changed isn't the most efficient way to do it. Probably the best way, if you use an RSS reader, is to subscribe to the RSS feeds that are automatically created for every forum (and there are even feeds for each individual page if you want). You can do this via the "Track Changes" link at the bottom right of each forum page.

The "Track Changes" also offers you the choice of being notified of changes by email. However, out of the box, this option isn't available, as the application doesn't know how to send mail from your particular system. To tell it, the site administrator has to go into the site's administration area. From there, visit the "Notification" page, and fill in information about your SMTP mail server, and web and email addresses. The email options on the "Track Changes" pages will then be available.

Power Users: Automating ProjectForum tasks.

A couple of weeks ago we talked about how to manipulate ProjectForum's underlying database files, and suggested that in almost all cases, there is a better way to do it. Today we'll talk about that better way.

We sometimes get asked if ProjectForum has an "API" (application programming interface), allowing other programs to do things like add users, post content to pages, and so on. In fact, there is, and it is the same API that you use whenever you use ProjectForum yourself - good old HTML and HTTP.

Want to get ProjectForum to do some repetitive task, but you don't want to sit there and click-click-click through all the forms to do it? You can write a script, in languages like Perl, PHP, Python, Tcl, Ruby, or any other language that lets you easily make web calls in it. Let that script simulate all that clicking around and filling in forms on your behalf.

This is a powerful technique; remember that everything you can do with ProjectForum can be done through the web, so that means you can write a program to do all those things for you. In fact, we use this technique to do a huge amount of completely automated testing every day on ProjectForum, making sure that as we add new features that they work, and we don't break any old features in the process. The amount of testing code we have is actually on par with the amount of code for the application itself.

Here is a short and simple example (albeit without error checking), written in Perl, demonstrating how a program can log in to a running ProjectForum server, and add a new user to a group. It does this by first logging in as the site administrator (so it has access to everything on the site), and then visits the group's accounts page, sees what users are already there, and adds a new user to the end of the list.

To run the example, save it to a file (e.g. addaccount.pl), edit the first few lines to provide information about your site, and then run the script.

my $siteurl = "http://127.0.0.1:3455/"; # base URL of the site
my $siteadminpass = "abc123" ; # site administration password
my $urlprefix = "1"; ; # URL prefix of the group we're adding the account to
my $newusername = "Bill"; ; # name of new user to add
my $newuserpass = "billpassword"; ; # password for new user

use HTML::Form;
use LWP;

my $ua = LWP::UserAgent->new;
$ua->cookie_jar( {} );

# signin as admin, which will set the cfadmintoken cookie
my $response = $ua->get($siteurl . "admin/adminsignin.html");
my $form = HTML::Form->parse($response->decoded_content, $response->base);
$form->value("adminpasswd", $siteadminpass);
$ua->request($form->click());

# now append the new account to the accounts screen
$response = $ua->get($siteurl . $urlprefix . "/admin/accounts.html");
$form = HTML::Form->parse($response->decoded_content, $response->base);
my $newaccount = "\n" . $newusername . ";" . $newuserpass;
$form->value("accountlist", $form->value("accountlist") . $newaccount );
$ua->request($form->click());


We'll talk more about this technique next week...

Tip: Keep an eye on the "Storage" page.

If you're a group administrator, it's a good idea to periodically take a look at the storage page in the group administration area. This tells you how large your group is, both in terms of how much space it is taking up on disk, as well as detailing things like how many pages are in the group, how many old versions are stored, and so on.

Why keep an eye on this? Doing so can help you both watch out for unexpected uses or problems, and also keep the overall system running as smooth as possible.

For example, a sudden and sustained jump in the number of older versions of pages (when there isn't a huge change in activity that you're aware of) may be a clue that a "spam robot" is automatically posting garbage to one or more of your pages - take a quick peek at the recent changes of each forum (main group and projects) to see if this is the case. Are your users suddenly attaching multiple large attachments? Again, if this is a change in normal behavior, you may want to investigate further.

If you're not using certain data that is being collected, it makes sense to clean it up, which will not only keep the size of your group down, but also give a bit of a speed boost to many operations (like any other system, the more stuff that ProjectForum has to keep track of, the longer certain things will take). Are older versions of pages important to you? If not, periodically remove them. Do you even look at user activity logs? If not, make sure to clean them up, and think about just turning them off altogether.

Power Users: Taking advantage of other Web 2.0 tools.

Because you can easily include information from other websites into a forum, it becomes possible to take advantage of all kinds of Web 2.0 tools that are available today. These offer a variety of web services, often focused on social networking, and providing new ways for your group to share things with each other. You can do that with ProjectForum too of course, but if you're using one of these more specialized tools already, why duplicate the effort?

Many of these tools rely on "tags" to group things together, allowing you to easily find all items having a specific tag. A tag is a short word, of the group's choosing, that you all agree to use. Let's see how we can take advantage of two of the popular Web 2.0 services: del.icio.us and flickr.

del.icio.us is a social bookmarking service that lets you share interesting web sites that you've found. The service also provides an RSS feed showing all the latest bookmarks for a specific tag. To include it into a forum page, you can just add this to the forum: "[rss:http://del.icio.us/rss/tag/MYGROUPTAG]".

Flickr is a well-known photo sharing site. To include the latest photos associated with a given tag, you can do something similar to what we just did with del.icio.us, just with a different URL (the "rssfull:" instead of "rss:" makes sure we show the photo, not just its name): [rssfull:http://api.flickr.com/services/feeds/photos_public.gne?tags=MYGROUPTAG&lang=en-us&format=rss]

You can also use Flickr to create slideshows, which can then be embedded into any web page by copying and pasting a small piece of HTML like the following:

<iframe align=center src=http://www.flickr.com/slideShow/index.gne?user_id=XXXXXXXX@XXX
     frameBorder=0 width=500 scrolling=no height=500></iframe>

To include this in a forum page, just put a line containing "===html===" just before and just after it, and make sure "enable HTML formatting" is turned on for the forum. This is also a prime example of where using a custom link would be very useful.

Tip: Showing news to your group.

Many news sources provide RSS feeds which help people with feedreaders keep track of breaking news on a particular topic. But not everyone uses a feedreader, or wants to dig out what feeds are worth tracking.

ProjectForum and CourseForum contain a built-in RSS feedreader, making it easy to embed an RSS feed right into a forum page. That way, the latest headlines from the feed will automatically be shown to everyone, even if they don't know a thing about feeds or RSS.

To display a feed, use the "rss:" tag, followed by the URL of the feed. For example, to include Yahoo's top stories feed in your forum, use "[rss:http://rss.news.yahoo.com/rss/topstories]".

Power Users: Reading and writing datafiles directly.

There's normally no reason at all to directly access the underlying database files (i.e. the "*.db" files) that hold the majority of the system's data. But for some people, particularly those wanting to run automated external tools to e.g. generate their own reports on usage, having a way to do so could be helpful.

The "*.db" files you see in the Course Data or Group Data directories are managed by an open source embedded database library called Metakit, which is included as part of the CourseForum or ProjectForum binaries. We've provided a HOWTO which provides a bit more information, and includes pointers to some tools that are useful for examining Metakit datafiles. They'll provide all you need to extract any data for use in another program.

Is the Metakit datafiles can be read from using these tools, can they also be written to? The answer here is a definite "yes, BUT". For starters, when CourseForum or ProjectForum are running, they assume they have exclusive access to these datafiles, meaning that if you try to write to them, there is the potential for data corruption. Therefore, make sure that any changes you want to make are done when the programs are not running. Second, as with any data modification, make sure that you understand exactly what you're modifying, so as to prevent creating data that doesn't make sense to the application.

There is actually a better way to programmatically make changes to the data stored in the Metakit datafiles, but we'll save that for another time.

Tip: Displaying links as images.

Placing a link to a web page into a forum is as easy as typing in the URL. Changing the name of the link (i.e. what is displayed in the page) can also be done: put a space after the URL, then type what you'd like to have displayed, and then put the whole thing in square brackets, e.g. "[http://www.foo.com my link]".

You can also have that link display as an image. Say for example you've got an image that you've uploaded into your forum that you'd like to make into a link. If you edit the page, you'll see that the place the image is shown in the page is marked with a tag like "[image:1234]" (the 1234 will be different for each image). To make it into a link, just put the URL inside the opening bracket, e.g. "[http://www.foo.com image:1234]".

Power Users: Site-wide Images.

One easy but very useful application of custom links is to create a new command so that inserting a standard image into a page is easy. This might be for example a company or product logo, or anything else that would be commonly found in different groups across the site.

Let's create a new custom link to make it easy to display the ProjectForum logo in any wiki page. First, go into the "Site Administration" area of your site, and then click on "Custom Links" along the top.

Hit "Create" to add a new custom link. Fill in the fields like this:

• Prefix: "img". This is the first part of the markup command that will be used to refer to the custom link.
  
• Selector: "pf". This custom link will only be invoked if the given selector is provided right after the "img:" prefix.
  
• Parameters: "0". We don't need users to provide any additional information to show this image.
  
• Type: "Inline HTML". We want the custom link to be replaced with the HTML we specify.
  
• Body: "<img border=0 src='http://www.projectforum.com/img/title_pf.jpg' />". This is the HTML to display when the custom link appears.
  

Save your changes. Then if you go into any forum on your site, and place "[img:pf]" on your site, it will get displayed as the ProjectForum logo, using the HTML we provided in the custom link. This makes it very quick and easy for your users to refer to the logo, and also means if you go back and change the custom link (to point to a new version at a different URL, for example) the new version will automatically show up everywhere.

Have more than one standard image you want users to have easy access to? For each one, create a new custom link. It should be the same as the one above, except you'll change the selector (e.g. "foo" if you want your users to be able to type in "[img:foo]"), and the URL of the image in the body. So this way you can provide a whole range of images for your users.

Obviously this technique isn't restricted to just images — you can use it to provide almost any standard material, such as common "boilerplate" that appears on many pages.

Tip: Viewing a page without all the menus etc.

Often it's useful to get a view of the page without all the various editing tools, commands, etc. that are part of the normal wiki page you see in ProjectForum — for example, when you want to print the page. To do this, you can click the "Print" link near the bottom of each page. While that does get rid of most everything, it does leave the overall page style intact, which can in some themes provide some large headings or margin areas.

If you really want to get rid of everything except just the page content, here is how. You'll notice when you do "Print", the browser shows a URL that looks something like "http://www.foo.com/mywiki/5?view=print". If you go into your browser's location bar and change the word "print" to "content" (so it reads ".../mywiki/5?view=content") and load that page. Voila, just your content!

Power Users: Custom Links

One often overlooked feature is the custom links feature. This helps you create entirely new formatting commands that your users can place in pages.

Why would you want to do that? While CourseForum and ProjectForum come with a good number of formatting commands, the number of these commands has been deliberately kept fairly small; each new one that gets added makes the system harder to use and work with. Sure, it's possible to embed HTML into the pages to accomplish pretty much anything you want, but that's not the most user-friendly approach unless your user community are all hardcore engineers.

So you can use custom links to create new formatting that your users may find particularly useful for the type of communication they're using the wikis for (again, keeping in mind that adding things just for the sake of adding them is usually counter-productive because of the learning curve). Some obvious candidates include color, blockquoting, other font changes, and so on.

But you can also do a lot more complex things beyond just providing wrappers to standard HTML markup. Some examples: incorporating standard corporate images or boilerplate text, providing hooks into other communications tools like IM or an issue tracker, and even extracting data from corporate databases. All of this within a wiki page.

Over the next while we'll explore some of the things you can do with custom links, but in the meantime, have a read through our custom links HOWTO to get a bit of a feel for the mechanics of how custom links are created.

Tip: Automatically redirect to a wiki.

If you've got a site with only a single group or course on it, you can set things up so that when a user loads the home page, they are automatically redirected into that single wiki. To do so, log in to the Site Administration area, and select the "Redirect to group/course when loading home page" checkbox.

Tip: Preventing spam.

These days, spam is unfortunately a reality if you're running any kind of public website that allows contributions from users, whether a forum, a blog that accepts comments, or a wiki.

For most users of ProjectForum and CourseForum, the sites are used internally, sometimes available only on a corporate network or VPN, in which case spam won't be an issue. For others, sites are already locked down completely with passwords, so that nobody can get into the site at all without a password. Again, spam shouldn't be an issue in this situation.

For even public sites, consider putting a password on the wiki in order to make any changes. This includes even posting comments; in fact, this is probably the most important area. Most spam is completely automated, and unfortunately most "spam robots" can take advantage of how easy it is to post comments into a forum.

Does this mean you need to prevent public access altogether? Usually not; you just need to make it easy for legitimate users to get access to the password. Because most spam is automated through robots, it's surprisingly effective to simply post a note on the Home page of your wiki saying "The password for this wiki is whatever-password-you've-set".