How To: Fixing CakePHP Broken GET Query Strings

After getting familiar with CakePHP 2.x for a little while, writing an application, I had a need to perform an AJAX action  using the query string of an HTTP GET request. I’ve done it countless times using straight PHP, ASP.Net, even custom constructed requests from C# desktop applications.  How difficult could it be? After all, the idea behind these PHP frameworks is to take all the heavy lifting out of writing your code, right? I set out writing the AJAX links to construct my query string using CakePHP’s JsHelper.

I started out by writing a simple query string with a single key/value and then retrieving it with some AJAX. It worked perfectly! Then I added a few more key/value pairs to the string and that’s when things went down hill. Apparently, I stumbled on to bug in the way CakePHP handles and encodes URL Query strings. Funny thing is, this bug was discovered and fixed in a previous version of the framework, but some how found it’s way into the code base again in version 2.x. Research revealed a number of work-arounds and hacks, most included editing a core file or two. I, however, did not want to have to resort to messing with core files of the framework, because they would likely be overwritten again after a version update or upgrade, leaving me back where I started. Instead I decided to “repair” the parts of the query string that CakePHP broke.

Continue reading “How To: Fixing CakePHP Broken GET Query Strings”

How To: Read Only DataGridView Control, C#

Quick Tip:
By Default, DataGridView control columns are set as editable, but in many cases, you may not want your grid data to be edited, or you may want to set your own controls that enable when and how the data get edited. The following C# code snippet will set the DataGridView columns of your DataGridView to ReadOnly.

foreach(DataGridViewColumn dc in My_DataGridView.Columns){
dc.ReadOnly = true;
}

This snippet iterates through the  DataGridView.Columns collection and sets  the ReadOnly property for each DataGridViewColumn item referenced as dc to true (boolean).

WordPress: Use Custom Fields To Add Keyword Metadata to Your Posts

Keywords at edwardstafford.com
Keywords for edwardstafford.com

One of the short-comings with using WordPress is that it does not provide an easy, built-in way to include metadata for your web page descriptions and keywords (and rightfully so). Why Not? The reason is simply that WordPress cannot read your mind. I know it’s hard to believe when you consider what you can do with wordpress, but it’s true. The issue with Description and Keyword page metadata is that, to be truely effective, it should be created to  describe the content found on each individual page. It’s how search engines like google determine how to categorize and index each page. Now, there are some SEO “experts” who will argue that this information is not very relevant anymore, and I do agree with that for the most part, but there are still SEO benefits to including this metadata vs. not including it at all.

I’ve been giving this some thought lately and developed a couple ideas of how to add these features into a wordpress site without too much difficulty. A bulb went off in a moment clarity when I started to think about using the Custom Fields to store page specific metadata. I was even naive enough to think I was on to something new (should have known better) but as I started researching some ideas, I realized there were others already doing similar things. Oh well, a minor detail. I took my own approach to the idea anyway, if for no other reason than a learning exercise. Ultimately, this could be added as a premium feature to any custom theme using a couple hooks and some custom theme options magic.

Continue reading “WordPress: Use Custom Fields To Add Keyword Metadata to Your Posts”

How-To: Using VBoxManage to Delete a Virtual Machine from VirtualBox

deleteOne common problem I see from people learning to manage Virtual Machines within VirtualBox using the VBoxManager command line is the error:

Cannot unregister the machine <Virtual-Machine-Name>  because it has 1 hard disks attached

Before a VM can be unregistered or deleted, all disks that have been “attached” need to first be disassociated from the VM. For this example, I’m using a virtual machine that I have set up and named “VNAS” that was used to test an OpenFiler NAS installation (which, by the way, worked great). Now that testing is complete, I am ready to remove it.

The removal for a standard VM install can be completed in a short list of steps.

Step one: Get the name or UUID and details of your VM

VBoxManage list vms

VirtualBox Command Line Management Interface Version 3.0.8
(C) 2005-2009 Sun Microsystems, Inc.
All rights reserved.

“VNAS” {8a48759d-4e6d-473f-ab0f-8ff59aa727eb}

That command will return the names of all registered VMs and their UUID. Make sure you get the correct name or UUID for the VM you will be modifying.

Step two: Get the disc information for your VM

There are two methods you can use to the get the information for each virtual disk registered to a virtual machine. The first is to list the VM info for a specified VM which includes the Virtual Disks that are in use by it.

VBoxManage showvminfo <Virtual Machine Name or UUID>

VBoxManage showvminfo VNAS
VirtualBox Command Line Management Interface Version 3.0.8
(C) 2005-2009 Sun Microsystems, Inc.
All rights reserved.

Name: VNAS
Guest OS: Other/Unknown
UUID: 8a48759d-4e6d-473f-ab0f-8ff59aa727eb
Config file: /secondary/.Virtual/machines/VNAS/VNAS.xml
Memory size: 512MB
VRAM size: 8MB
Number of CPUs: 1
Boot menu mode: message and menu
Boot Device (1): Floppy
Boot Device (2): DVD
Boot Device (3): HardDisk
Boot Device (4): Not Assigned
ACPI: on
IOAPIC: off
PAE: on

Primary master: /secondary/.Virtual/vdisks/OFInstallDisk (UUID: xxxxxxx)
Primary slave: /secondary/.Virtual/vdisks/VNASStore1 (UUID: xxxxxxx)
Secondary slave: /secondary/.Virtual/vdisks/VNASStore2 (UUID: xxxxxxx)

In this example you can see I have 3 disks registered with the vm.

  • Primary Master (hda)
  • Primary Slave (hdb)
  • Secondary Slave (hdd)

NOTE: You might be asking, Why does the sequence jump from hdb to hdd? What happened to hdc? The answer is, hdc is reserved for CD/DVD mounting, so you can’t add a virtual disk there.

The second, alternative method is to use the the VBoxManage command “list” with the “hdds” option to list all the Virtual Disks in the system. This will display a list of All the disks you have created and registered for ALL VMs. Information for each Virtual Disk and the VM it is registered to is displayed. Here you can see the three disks registered with my VNAS VM indicated by the “Usage” lines.

VBoxManage list hdds

UUID:         eebbb4c7-c539-4da4-b8ab-e5777b32520b
Format:       VDI
Location:     /secondary/.Virtual/vdisks/VNASStore1
Accessible:   yes
Usage:        VNAS (UUID: 8a48759d-4e6d-473f-ab0f-8ff59aa727eb)

UUID:         9f238d31-f794-420f-83a7-ccf811d52244
Format:       VDI
Location:     /secondary/.Virtual/vdisks/VNASStore2
Accessible:   yes
Usage:        VNAS (UUID: 8a48759d-4e6d-473f-ab0f-8ff59aa727eb)

UUID:         2ce976c9-0a37-49c1-8d34-3962c563a256
Format:       VDI
Location:     /secondary/.Virtual/vdisks/OFInstallDisk
Accessible:   yes
Usage:        VNAS (UUID: 8a48759d-4e6d-473f-ab0f-8ff59aa727eb)

In my opinion, method one the easiest quickest way to see what Virtual disks are assigned to a specific VM.

Step Three: Disassociate the Virtual Disk[s]

VBoxManage modifyvm <Virtual Machine Name or UUID> —hda none

VBoxManage modifyvm VNAS –hda none

If you have more than one disk registered with a vm as I do here, you’ll also need to disassociate those as well.

VBoxManage modifyvm VNAS —hdb none

VBoxManage modifyvm VNAS —hdd none

Step Four: Unregister and delete the VM

VBoxManage unregistervm <Virtual Machine Name or UUID> –delete

VBoxManage unregistervm VNAS –delete

Step Five: Confirm

VBoxManage list vms

VirtualBox Command Line Management Interface Version 3.0.8
(C) 2005-2009 Sun Microsystems, Inc.
All rights reserved.

[NOTE: there are no VMs listed]

This is the same command that was executed in step one. After running this command again you should no longer see your Virtual Machine listed.

Note: This process will only remove your VM from VirtualBox. It will not remove/delete the actual virtual disk file (.vdi). You can delete that manually, or save it to use with another virtual machine instance.

VirtualBox and Bridged Networking on a Headless Ubuntu Server Host

In the previous VirtualBox post, I explained how (and how not) to set up bridged networking with LAN access to a Virtual Machine running on a Windows XP Host. Today I will explain how to do the same thing (without the How Not To part) using a virtual Machine running on a Headless Ubuntu Server.

For this example we can assume a few things:

  1. You have already set up a headless VirtualBox server
  2. You have already created a Virtual Machine instance. For this sample, we will call the Virtual Machine “MyVM”.

Believe it or not, setting up bridged networking to allow your VM to access your network is pretty simple and completed by issuing the following VBoxManage command in a terminal window.

Command: VBoxManage modifyvm “MyVM” –nic1 bridged –nictype1 82540OEM –bridgeadapter1 eth0

Break it down

To understand a bit more about what’s happening here, let’s break down the command string from the beginning.

VBoxManage – This is the command line utility used to access, control, configure and manage your VirtualBox Virtual Machines.

modifyvm – This command allows you to make changes to the properties of a Virtual Machine, including the amount of memory assigned, nic interfaces, Virtual device boot sequence, number of CPUs, etc. It can be compared to the Settings dialog of the VirtualBox Graphical user Interface. The command line version, however, offers additional advanced options not found in the GUI.

Note: the VM must be registered within VirtualBox, but must not be running

MyVM” – This is simply the name of the VM you want to modify.

–nic1 bridged – The –nic1 parameter is used to set the type of networking your VM should use for each of the it’s virtual network cards. You can have more than one network card in use for a VM so the paramater is written as –nicX where X is the network card being targeted. Here, “–nic1” is the first network interface, –nic2 would be the second and so on. This portion of the command string is setting the type of networking on the first interface to “bridged”.

–nictype1 82540OEM – The –nictype1 parameter allows you to specify which networking hardware VirtualBox should emulate for the VM’s virtual network cards. Here we set the networking hardware to emulate an Intel PRO/1000 MT Desktop card or 82540EM.

–nictypeX follows the same sequence numbering and –nicX for multiple interfaces where –nictype1 is the first virtual card, –nictype2 is the second and so on.

Note:  The following is a list of the available nic hardware types and the associated ID recognized in VirtualBox.

  • AMD PCNet PCI II = Am79C970A
  • AMD PCNet FAST III = Am79C973 (the default)
  • Intel PRO/1000 MT Desktop = 82540EM
  • Intel PRO/1000 T Server = 82543GC
  • Intel PRO/1000 MT Server = 82545EM
  • Paravirtualized network adapter = virtio-net

–bridgeadapter1 eth0 – Finally we have the –bridgeadapter paramater. This is the only part of the command string that references a part of the VirtualBox host and tells your VM which physical host adapter to pass it’s traffic through.

Again, this uses the same sequence numbering as nicX and nictypeX for multiple interfaces. Here, we are setting the bridgeadapter for our first virtual network card to use the eth0  interface on the host. Note that is eth zero, as in the number and not the letter O.

And that’s it. Restart your VM and you should now have a working bridged network interface for you VM with full network and internet access.

VirtualBox 3.0.4 and Bridged Networking on XP Host with GUI

Photo: Wally Gobetz
Photo: Wally Gobetz

Editors Note:

While I was writing this, the solution to my problem struck me unexpectedly. Click here to skip the drama and jump right ot the solution.

Originally, this article started out as a complete rant and cry for help. I started to write about the failure and frustration of the installation and network configuration of a virtual machine in VirtualBox 3.0.4.  It just would not work. The problem, as it turned out, was that I was over thinking the process. BUT, that is not completely my own fault.

Continue reading “VirtualBox 3.0.4 and Bridged Networking on XP Host with GUI”

Add a Network Printer to an Ubuntu Desktop – The Easy Way?

The Rant

It’s no secret that I am a fan of Ubuntu Linux. BUT.. one of the annoying things about using Ubuntu is trying to set up a network printer on a desktop or workstation. Regarding nearly all administrative tasks under most Linux systems that would require root permissions, Ubuntu has done a nice job of making it possible to operate a system as a “normal” user without elevated privileges, and then easily gain the elevated (root) privileges temporarily assigned to complete some specific administrative task. Ubuntu detects when a user is trying to do something requiring the elevated (root) privileges and pops up a small window asking for the current user’s password to gain the required permission. All the magic happens behind the scene and the user never has to issue a text command. It wasn’t long ago that users would have had to open a command terminal and issue all the instructions by hand. Well.. we’ve come a long way.. With the exception of installing a network printer. For some reason, when installing a printer in Ubuntu, the user is not prompted with the normal su password pop-up that presents itself for all other administrative tasks. Instead, the CUPS system prompts the user for the root password – and under Ubuntu, there is no root password by default meaning that root can not complete any direct action requiring a password. In fact, root can not log directly into the system at all. Fortunately, the solution is fairly easy.

The Solution

Do not try to install a printer from System > Administration > Printing menu. It won’t work. Sure, it will allow you to go through the wizard and give you the false impression that you’re actually accomplishing something – until you reach the point where a driver needs to be installed and you’re prompted for the root password. Instead, go to the Applications > Accessories menu and select Terminal.

Once the terminal window opens, issue the following command

sudo system-config-printer

The next line in the terminal window will ask for your password. Type in your user password and hit enter. If all is correct, the printer setup and configuration window will open with elevated privileges enabled and you can finish installing and setting up your new printer from comfort of an easy to use GUI.

Sample Setup

Lets take a few minutes and walk through the process. In this example, I will be setting up a Dell 1700 Laser Printer in my Home Office. Before you get started, you will need to know a few things about the printer first. Continue reading “Add a Network Printer to an Ubuntu Desktop – The Easy Way?”

YouTube API Hack: Link Your Videos Directly to Your YouTube Channel

Wait! Your a Hacker?

Hack ItFirst of all, my use of the word “Hack” is not the version popularized by the media. It is used here in the context of using a tool (YouTube API) to accomplish a task that was not originally part of the tool’s design. By using some creative thinking and little trial and error, I was able to accomplish a desired result, and overcome a limitation of the API.

Ready, Set, GO!!

While working on a recent project I came across a mildly irritating limitation of the YouTube API. The thing is, I wanted to display a list of recently added YouTube video thumbnails to a web site that link back to the videos in the YouTube users channel.  Easy! right?

Not So Fast!

Here’s the thing. The channel feed returned by the API does include the link back to the YouTube Video, BUT it sends the visitor to the usual standard public YouTube page with the video embeded and NOT to the Channel of the YouTube member who uploaded it.

For most, this would be fine. But I wanted to be able to preserve a connection and identity between the web site and the YouTube Channel.

Unfortunately, the YouTube API does not provide a direct way to do this [link videos back directly to the YouTube Channel instead of the standard YouTube page]. So what’s a developer to do? … Come up with a hack, of course!! (even if is is a small one)..

First A Note:

This solution uses the Simplepie PHP Code Library to grab the Channel RSS feed

The Code:

<?php

require_once(‘php/simplepie.inc’);

$feed = new SimplePie(‘http://gdata.youtube.com/feeds/api/users/[user name]/uploads’);

$feed->handle_content_type();

$YT_PlayerPage = “http://www.youtube.com/user/[user name]#play/uploads/”;

$YT_VideoNumber = 0;
$ShowMax = 4;

foreach ($feed->get_items() as $item)
{

if ($enclosure = $item->get_enclosure())
{

$YT_VidID = substr(strstr($item->get_permalink(), ‘v=’), 2, 11);

echo ‘<a href=”‘ . $YT_PlayerPage . $YT_VideoNumber . “/” . $YT_VidID . ‘”title=”‘ . $item->get_title() . ‘”> <img src=”‘ . $enclosure->get_thumbnail() . ‘”/></a>’;

}
if($YT_VideoNumber == $ShowMax) break;
$YT_VideoNumber++;
}
?>

Tiptoe Through the Tulips (or walking through the code)

There you have it. A small block of PHP code and we have the result we’re looking for. Now let’s take a look at each line in the code.

require_once(‘php/simplepie.inc’);

This line does nothing more than call/include the Simplepie Library. The one thing you may need to change here is the location of the library. I stored it in a directory at the root of my web called “php”. So depending where you store your copy of the library, you may need to change this.

$feed = new SimplePie(‘http://gdata.youtube.com/feeds/api/users/[user name]/uploads’);

The next line creates a new feed and stores it as $feed. Pretty creative.. huh? Whats happening here is simplepie is grabing the rss feed for the YouTube Channel’s Uploaded videos.

An important note to make here is that the URI for the RSS passed to SimplePie is not the same as the RSS URI that you would use to subscribe to the channel’s RSS feed to use with your RSS reader. You will also need to replace [user name] in the URI with the YouTube user name for the channel you want to pull videos from.

The Standard RSS Subscription URI looks like this:
http://gdata.youtube.com/feeds/base/users/[user name]/uploads

While the URI used by the API to grab the RSS looks like this:
http://gdata.youtube.com/feeds/api/users/[user name]/uploads

Notice the difference indicated in bold text (“base” vs “api”). You will need to be sure you use “API” version of the URI. You can get this by copying the public RSS URI and simply changing “base” to “api”.

At the next line we have:

$feed->handle_content_type();

This just makes sure the content is being served out to the browser properly.

The next three lines contain three variables I’ve added: $YT_PlayerPage, $YT_VideoNumber and $ShowMax

$YT_PlayerPage = “http://www.youtube.com/user/[user name]#play/uploads/”;

This is the first part of the key to getting YouTube links to point directly to the Channel page. This variable holds the base Channel player URI and is used to construct a complete video link. The completed URI link also includes a counter reference and the unique 11 character video ID. To get the URI for the channel player page, visit the YouTube Channel you’re grabing the video feed from and click on a video link. The complete URI for that video will appear in the browser’s address bar. Simply copy that URI and eliminate everything following the backslash “/” after “uploads” (indicated in red)

http://www.youtube.com/user/[user name]#play/uploads/#/xxxxxxxxxxx

$YT_VideoNumber = 0;

The links on the YouTube Channel page contain a counter in the URI and increases by +1 with each link. This is the second part of the key in constructing the direct Channel links. This counter was a portion of the link that was removed in $YT_PlayerPage. I’m not completely clear on what the purpose of the counter is and in my experimenting with this, it did not seem to make a difference what the counter value was as long as the video ID followed it. But since it is the format that is used on YouTube’s Channel pages, I’ve figured it would be best to recreate the same thing here. Besides, we are going to use that value later in the code. I’ve set the initial value of the variable to 0 (zero) because the counter is zero based. (0, 1, 2 … )

$ShowMax = 4;

The next line contains the $ShowMax variable. This is used to set a limit to the number video links I wanted to display on the page. BUT, there is a trick you need to be aware of here. We are using the $YT_VideoNumber to get the counter number for the current video in the Loop (the loop will be described in the next section). But because $YT_VideoNumber is zero based, we need to compensate for that in the $ShowMax Variable and offset the limit by -1. In other words, to limit the display to 5 items, we need to set $ShowMax to 4 because we are including 0 as the first item (0 1 2 3 4) for a total of 5 items. Got it?… good!

foreach ($feed->get_items() as $item)
{

These lines start/open the Loop getting each item in the feed. This is where the code will “loop” through each item (video) in the feed and extract the information I wanted for each video.

if ($enclosure = $item->get_enclosure())
{

This line sets a conditional variable ($enclosure) to check if the current item in the loop contains enclosure data provided by MRSS (Multimedia RSS) that might be provided with the feed. YouTube feeds do support and provide MRSS enclosure data and we need to be able to pull it from the feed. The get_enclosure() method is part of the SimplePie Library and makes getting access to this data pretty easy.

$YT_VidID = substr(strstr($item->get_permalink(), ‘v=’), 2, 11);

This line is the final [and probably most important] part of the key to constructing the Channel video link.  It’s also the most confusing part at first sight. I mentioned earlier that a video link is provided with the feed that will direct the viewer to a the standard public YouTube page for viewing. This link contains the video ID that we need. The bad news is that the API as far as I could see does not allow a direct or easy way to get the ID for each video [please correct me if I’m wrong here]. The good news is that the ID can be extracted from the link provided with the feed, and that’s exactly what this line does.

$item->get_permalink() returns the URI / video  that would direct a visitor to the standard YouTube page. The URI is similar to:
http://www.youtube.com/watch?v=xxxxxxxxxxx

v=xxxxxxxxxxx of the URI contains the video ID and needs to be extracted.

substr(strstr($item->get_permalink(), ‘v=’), 2, 11) isolates and extracts the video ID and then stores the ID in the $YT_VidID variable.

Lets have a closer look.
We need to find the position in the URI string where the video ID starts and then extract it.

The video ID is passed in the URI as in query string paramater “v”.  I used the PHP strstr() method to match and find the position of “v=”. This will create a new string eliminating everything in front “v=” so we are left with “v=xxxxxxxxxxx”.

If you look close, you’ll notice that strstr($item->get_permalink(), ‘v=’) and therefore the resulting string, is actually used as the string argument in the substr() method used to isolate the video ID.

The second argument, “2” tells the substr method to offset the beginning of the string by two characters. This is to eliminate the “v” and “=” characters and moves the substring start position to the character after the “=” which is the first character of the Video ID.

The third argument, 11, tells the substr method to isolate the next eleven characters from the start position, leaving us with the full video ID “xxxxxxxxxxx”.

In experimenting and playing with this, I found that all YouTube video IDs are 11 characters long. I limited the substring to 11 instead of allowing it to extend to the end of the URI because, if for some reason additional string data was passed with the URI after the video ID, it would be included as part of  the extracted string and the result would be an invalid ID.

After all that, I had the golden nugget of an isolated video ID which is now stored in the $YT_VidID variable. The hard part is DONE!! (really, it wasn’t that hard).

echo ‘<a href=”‘ . $YT_PlayerPage . $YT_VideoNumber . “/” . $YT_VidID . ‘”title=”‘ . $item->get_title() . ‘”> <img src=”‘ . $enclosure->get_thumbnail() . ‘”/></a>’;

The three key pieces needed to construct the direct Channel URIs are now available and the links can be put together. This line, still contained in our loop, constructs the link for each video item in the feed and outputs the HTML markup that will be included in the rendered page. To construct the link, join the three key pieces (the variables) like so:

$YT_PlayerPage . $YT_VideoNumber . “/” . $YT_VidID

$YT_PlayerPage = The base URI.
$YT_VideoNumber = The video counter
include a “/” character
$YT_VidID = The video ID

The output should look like:
http://www.youtube.com/user/[user name]#play/uploads/#/xxxxxxxxxxx

Include this string as the value of the href of an HTML <a> tag.
‘<a href=”‘ . $YT_PlayerPage . $YT_VideoNumber . “/” . $YT_VidID . ‘
Next add a “title” attribute to the <a> tag and set the value to $item->get_title().
“title=”‘ . $item->get_title() . ‘”>
This will create a hover text that shows the title of the video when the cursor hovers over the link.

Next, include the link content (text or image to act as the visible link). In my sample, I’ve used a thumbnail of each video.
<img src=”‘ . $enclosure->get_thumbnail() . ‘”/>
Note that again I’m extracting the enclosure data included with MRSS as part of the RSS feed to get the thumbnail image for each video.

Finally add the closing </a> tag to complete.

But wait … There’s more!!

}

The next line is nothing more than a closing bracket that closes and completes the conditional statement that checks for the enclosure data.

if($YT_VideoNumber == $ShowMax) break;

Remember the $ShowMax variable? This is where it comes into play. We are using the $YT_VideoNumber variable that was added to hold the counter for the current video and comparing it to the $ShowMax variable used to limit the number of videos the page will display. With each iteration of the loop, the code extracts the information for each video item and increments the counter by +1. The counter actually serves two purposes in the code. First,  to be used in constructing the video URI and second, to control the point at which the loop is to be exited. Why?.. If our video feed has 100 items and we only want to display 5 of them, then it does not make any sense to continue stepping through the loop to read the remaining items. So after we get what we want, we exit the loop to save resources.

What’s happening here is this:
If the current $YT_VideoNumber variable value for the current iteration of the loop matches the value of the $ShowMax variable, then “break” (exit) out of the loop and we’re done.

$YT_VideoNumber++;

BUT, if the values of these variables does not match, then the next line increments the $YT_VideoNumber by +1 and continues to the next iteration of the loop.

}

And Finally, there is the closing bracket of the loop which also brings us to the end of the code block.

So that’s it. This code will render a set of YouTube video thumbnails in a web page that will link directly back to the video on the YouTube member’s channel page where ever it is included. But don’t stop there. Have a look at the other methods available in the YouTube API and SimplePie Library for additional information and data you can extract and use, add your own CSS and markup to the the output to change the layout, appearance, function … whatever you want.

I hope you found this useful. If you have any thoughts, improvements or comments to share, please post in the comments section here.

And if you do use this in your own projects, I’d really appreciate a comment in your code, a shoutout or link back to this post.

Happy coding!!!

5 Tips for better Wiki pages.

Wikis are great for sharing, documenting and archiving information. We Recently launched one for our company’s intranet to improve communication and allow better collaboration. Because wikis are intended to be an open platform to promote communication and collaboration equally across the organization, we try to encourage everyone to contribute. Unfortunately, I quickly learned that people can have different ideas regarding good page format, or may not know how to properly format a page at all. This can quidkly lead to mess of unruly pages that are difficult to read and navigate. So, I put together a list of five tips that I thought would help make formating wiki page content a little easier and make the pages less challanging to read and navigate.

When creating a new page, or editing an existing one, keep these tips in mind.

  1. Say No To Word: Unless the wiki has a built-in feature to deal gracefully with Microsoft Word syntax, Please Please Please…avoid copy-and-paste from word documents. Word documents create ugly HTML syntax that is difficult to edit and manage within the wiki (or any wysiwyg or web editor for that matter). It also creates pages that are structurally difficult to read and navigate without additional formatting and editing. As an alternative, save word documents as Rich Text Files, or plain text files then copy-and-paste into the wiki from there, then edit and format the content in the wiki using the wiki editing tools.
  2. Use Headers and sub-headers: Add headers and sub-headers when appropriate to organize your content on the wiki page. Using headers will not only help to visually separate each important section of your page, but they will also auto-create a page index or TOC (Table of contents) making it easy for users to find and navigate page content.
  3. Making The list: Use Ordered (numbered) lists and Unordered (bulleted) lists when creating lists of items. This makes each item in a list easy to identify and improves readability.
  4. Use An Opening Introduction: If your creating a new wiki page, always try include some information in a small paragraph at the top of each page describing what the content is about, and how it can be used. It is also helpful to include a small description below each heading and sub-heading as well. This helps readers to quickly identify the content and how it can be used.
  5. Can I Quote You On That? : Provide citations and supporting links to references when possible. Besides giving credit where credit is due, citations allows readers to confirm the validity of your input and lead them to additional sources of reference.

Do you have any other tips? Please leave a comment and share them here.