isambard » interface design

Sharing a Calendar in Sharepoint 2007 – Part II

steven — Thu, 19 May 2011 04:45:25 +0000

Earlier I wrote about how you can use XML+XSL to get around the limitation in Sharepoint 2007 of sharing calendars across multiple sites. This technique stores your events as XML and allows you to publish entries wherever and however you wish.

This article expands that earlier introduction with some tips and tricks we collating when implementing this for one client:

working outside Sharepoint
presenting a URL
sorting items
grouping items
showing a message if a filter set is empty

Note: You can download sample XML and XSL here. These files show all the techniques described in this article.


the original XML	filtered view	grouped view

Working outside SharePoint

It can be painful to develop your XML/XSL solution in Sharepoint because of the need to upload new versions (or edit webparts), then refresh to see the results, or lack thereof. Easier to work outside and just upload when done.

To link your XML and XSL outside SharePoint edit your XML file to include a link to your XSL file:



....

Now when you open your XML file in a browser it will use your XSL to present.

Save your XLS as a file with a name to match the XML link and you’re nearly there. The only other change you may need to make is to extend your XSL so it generates a full webpage, not just a fragment.

For example our standard calendar presentation XSL generates a paragraph:

...

To work outside SharePoint it needs to generate a proper page; make it do so by simply adding HTML and BODY tags:

...

Just remember to remove these bonus lines when re-inserting into your SharePoint site.

Presenting a URL

If one element you’re recorded in your XML is a URL then chances are you’ll want to use XSL to convert that into a link. And the obvious approach you’d think would be the simplest:

link text

Other than the issue over nested quotes, all looks pretty straightforward. Except it doesn’t work.

The solution is to use a different format for the URL selection:

link text

Now it works fine.

Sorting items

One feature we wanted to implement was the automatic sorting of results. This meant anyone maintaining the master XML list did not need to worry about where to add individual items to preserve their order. They could just add anywhere in the file and be confident they’d appear in the correct sequence when displayed.

To sort results, add the command as the first element within your loop. For example to sort by a date element:

...

Check W3Schools if wanting to do something more complicated than an ascending text order.

As you can see from this example, what we were wanting to search on were dates. And early on we’d decided that users would enter dates in “human” format (ie ’23 May 2011″, not 20110523). One issue we had on sorting dates was the chestnut of how to sort “2 May 2011″ to appear before “15 May 2011″. Our solution was to require all dates in the XML to be two characters (“02 May 2011″ not “2 May 2011″) and then use XSL to remove the ugly leading zero when displayed. The code to remove that zero is straightforward:

You have to use the construct because while XSL does have an IF statement (not surprisingly ), it does not have an equivalent ELSE.

Note: The alternative would be to define the date in a nice sortable format (I vote for YYYYMMDD). And then use similar XSL transformations to present in a more readable format. Either way you’re putting some overhead on the user. We stuck with this simple approach because it was (a) less user effort and (b) allowed a wider range of dates to be acceptable. For example we had some programs that only specified a month. Sorting this way meant we could accept “May 2011″ as a valid date.

Grouping items

Now this I thought would be easy. Since we’re working on a calendar, let’s group entries according to the month. ie:

April 2011
- This course (12 April, London)
- That course (19 April, Helsinki)
May 2011
- That course (2 May, Romford)
- The other course (30 May, Malaka)

After several false starts, all roads do eventually lead to a fabled Meunchian method. Trouble is, even after building it, I’ve no idea how it works. Of all the articles uncovered to try and explain it, this one came closest. Cut&paste their approach (or our example using it) and you should be able to get it to work.

Showing a message if the filter set is empty

In the first article we covered how simple it is to present a subset of your entries. However once implemented we discovered we needed to address the situation where a subset was empty. Rather than just showing a blank list we wanted to show a messsage directing the visitor to other sources.

Simplest way to implement this is to repeat the same filter query used to generate the subset. Just place within a COUNT() and use as a test:


     

          
          ...
          

     
     
          No events recorded for this program.

Only potential issue may be around your formatting. Be mindful of where your layout tags appear depending on which data is presented.

Conclusion

With just these techniques you can present and manipulate your content in quite ingenious ways. Just good luck trying to understand the Muench.

UI Rule #47 – Don’t Make Up Words

steven — Fri, 21 Jan 2011 03:04:17 +0000

Found the following beauty when on Youtube:

You shouldn’t have to invent your own language (“Favorited?”) to make your UI work.

Sharing a calendar in Sharepoint 2007

steven — Mon, 10 Jan 2011 05:40:47 +0000

One of the most annoying omissions in Sharepoint 2007 is the inability to share calendars between sites and subsites:

maintain a master calendar and view it (or part of it) in a subsite, or
maintain a calendar in the subsite and “roll it up” with other subsite calendars to a master view in the main site.

Apparently this is rectified in Sharepoint 2010 but if you’re unable to upgrade, and aren’t allowed to build your own webparts, you’ve to look elsewhere for a solution:

use a 3rd party webpart (can recommend the Bamboo Solutions offering having used it elsewhere), or
hacking together via the page viewer webpart (I never got this to work but your mileage may vary)

However this article describes a 3rd option we implemented which met the requirement by not using calendars at all. Instead we used XML.

An XML solution in three parts

The XML solution allows a single, master, calendar to be published in multiple subsites, optionally filtering entries to particular subsets. To implement you need three elements:

source calendar (in XML, not a SharePoint calendar)
presentation/design code (XSL), and
webpart that links the above two together on your site.

Without advanced CSS skills this won’t get you much more than an event list on any site. But if that’s all you want, and more important is the ability to reproduce that one list on multiple sites, then this approach might work for you.

Source calendar (XML)

In XML a calendar is simply a series of events, with varying parameters that include a date and a name, collected in a parent element. For our basic implementation we ended up with just that:


 
  12 August 2011
  Integration testing starts
 
 
  23 November 2011
  Integration testing ends
 
 ...

To make it valid just add a definition on the first line:

From this basis you can obviously add whatever other values you want to note for each event. For example if you want to present or filter by project, or responsibility, just add appropriate values to the XML.

presentation/design code (XSL)

The XSL code is what converts your XML into HTML that can be presented on your Sharepoint page. With the simple calendar schema adopted here this is only a few lines.

First set the scene:

...

Then add the XSL proper inside the above framework. The following code will first match our calendar parent element using template-match, before traversing each of our events by using a for-each loop.

This code puts each event (the “EVENT” elements) into a separate row in a table, with two event values “title” and “date” presented in separate columns.

This code gives you the basic framework for manipulating your XML. However XSL, and HTML/CSS are must more powerful than this example demonstrates. Feel free to research further on how to leverage this approach to really fine-tune the delivery of your calendar data.

For now, however, I will describe one of the most common XSL functions you’ll want in this solution: the ability to present a subset of your calendar entries based on a parameter recorded with each event.

Filtering records

In XSL you filter records by adding a comparison operator to your for-each statement. For example, if we add a “project” attribute to our events, the code to filter to a specific project is a simple change to the for-each command:

This will now only list events that are for “Project A”. And how do you get entries to be categorised as “Project A” – just add to the XML:


 
  Project A
  12 August 2011
  Integration testing starts
 
 
  Project B
  23 November 2011
  Integration testing ends
 
 ...

Linking webpart

To pull the XML and XSL together on your Sharepoint page, add an XML Webpart.

In this webpart you simply specify the XML and XSL you need to use. You can enter your details directly into the webpart (which negates the whole sharing theme for the XML, and can cause consistency issues with the XSL). Or you can link to external files. With the advantage that those files can exist anywhere in your site architecture.

Conclusion

Using XML to share a single calendar is not for everybody. It's harder to maintain the entries, and the presentation is never going to be sexy. But as a quick way to stop yourself repeating yourself, it's worth considering.

Rounding error

steven — Sat, 27 Nov 2010 05:15:39 +0000

Check out my average score from some elearning I had to complete recently for surf lifesaving:

Just one more correct answer and I may have got my average up to 94.52631578947369%!!

To be fair, at least they did not need 14 decimal places to tell me how long the course took.

Stop this UI Madness: Confirming visible fields

steven — Fri, 22 Oct 2010 22:52:30 +0000

Enough people. Please stop building forms where I’m asked to confirm a field I can see quite clearly. Like this example:

Or here’s another example. Which shows right and wrong use of duplicated fields and (horror or horrors) disables cut&paste.

The only requirement for a confirmation field is when entering a value that is not visible, i.e. a password. For anything else I can see the value I’ve typed and “confirm” it’s correct without retyping. Don’t make me repeat myself.

If worried about validity, beef up your error-checking. Don’t delay me with pointless re-typing (or more usually, cut&pasting).

And another thing. While making me repeat myself is bad enough, making me repeat myself and then disabling cut&paste in the repeated field gets you your own special corner of hell.

UI Design (and the World Cup)

steven — Wed, 09 Jun 2010 04:43:04 +0000

In a shameless attempt to link work with the greatest sporting event in the world, the following site has one of the most impressive World Cup Calendars seen in a long time.

http://www.marca.com/deporte/futbol/mundial/sudafrica-2010/calendario-english.html

Takes a certain streak of creativity to build a calendar outside the usually rectangular.

Managing timezones with PHP and Javascript

steven — Thu, 10 Dec 2009 06:45:37 +0000

In a current project we need to keep a log of all activities and present that log to the users. And once we start needing to tell users about times we raise the whole spectre of timezones.

After some heated design discussions we narrowed our requirements to needing to provide a choice of two possible display formats for users.

show all activities in (my) local time eg if I’m in Melbourne, show all activities in Melbourne time, even if not completed in Melbourne
show all activities in (their) local time – what we called “original” time eg if I’m in Melbourne, show all activities completed in Sydney in their original Sydney time, show all activities completed in Perth in their original Perth time.

For the latter format to make sense we agreed to add a timezone code to indicate where we were at the time. For convenience these were all given as time +/- UTC. Eg 4:23PM (UTC +11).

implementation – capturing activity times

To allow us to manipulate activity times after recording them we need to record two bits of information:

time completed
timezone completed in

Our decision for those two was to record the time in UTC and then for the timezone simply record the difference from UTC for the timezone where the activity was completed. That way we knew that whatever we did on display we had a consistent and understandable set of times in the database.

For example, I’m in Sydney (current timezone is UTC+11). An activity I complete at 4pm is recorded in the database as:

completion time: 5am that morning (4pm converted to UTC)
completion timezone: UTC+11

getting the timezone the activity was completed in

Getting the timezone is easy, and requires a few lines of Javascript added to the client where the activity is completed. So we can get the value to the server to manipulate and record in the database we pass it back to the server as a hidden form variable on our login page.

The magic function we need is getTimezoneOffset. This returns the number of minutes ahead/behind of GMT for the current user. For reasons that become clear when we start looking at presenting dates we convert it to seconds. And for reasons that are lost to us we need to negate the value because it returns the offset the wrong way around. Eg if the client is currently one hour ahead of UTC, getTimezoneOffset returns -60.

Putting all that together adds the following to our login page:

We added that code to the login form. That way we can capture it once and store as a session variable to use when recording all subsequent activities for that user in the same session.

getting the UTC time the activity was completed at

In getting the time an action was completed we can either take the client time or server time. Doesn’t really matter (if both are confidently accurate) since we’ll convert either to UTC.

For simplicity we chose to work from the server time. In PHP we can get the UTC of the current server time in 2 lines:

$timestamp = time();   
$timestampUTC = $timestamp - date("Z", $timestamp);

The “Z” option for Date returns the offset to UTC in seconds based on the server’s current timezone. And since timestamps simply count seconds it’s simple to add/remove our conversion factor.

You’ll have noticed there are a few config requirements if this approach is going to work. We were able to rely on these being true in our case but you’ll need to check for your own implementation:

Javascript enabled on the client

correct time (and timezone) set on the client

correct time (and timezone) set on the server

If you cannot rely on any of these then you’ve a few changes to make!

displaying times

With our activity recorded in the database as UTC it is a simple task to convert to the display times we require. To provide a different display format, we simply need to choose which offset we apply to the UTC time recorded in the database.

local time

This is the easiest to generate. Simply update the recorded UTC time with the current UTC offset of the client that we captured when they logged in. Since we converted that value to seconds when uploading we simply add it to the UTC timestamp from the server:

$timeLocal = $timeUTC + $_SESSION['offsetClient']; 
$timeLocalDisplay = date("D d M Y H:i:s", $timeLocal);

original time

For original time we just need to apply the offset originally recorded in the database, and then tweak the presentation of the timezone to something legible.

$timeOriginal = $timeUTC + $offsetActivity  //both from the DB
$timeOriginalDisplay = date("D d M Y H:i:s", $timeOriginal);
if ($offsetActivity == 0) { 
   $timeOriginalDisplay .= " (UTC)"; 
} else { 
   if ($offsetActivity > 0) {   
      $timeOriginalDisplay .= " (UTC +" . ($offsetActivity/3600) . ")"; 
   } else {   
      $timeOriginalDisplay .= " (UTC -" . ($offsetActivity/3600) . ")"; 
   } 
}

That code gives us a date like “Mon 23 Jun 2006 12:23:45 (UTC +7)”.

A third option (that we did not implement) was to give the timezone as relative to our own. Eg if we’re at “UTC+4″ the previous date would be “Mon 23 Jun 2006 12:23:45 (+3)”. This format would be easy to calculate as we already have our current timezone recorded as a session variable after login. However no-one really wanted it (or could agree how to present it) so the idea was dropped.

conclusion

So far this design has handled all the requirements we’ve thrown at it. Only changes we made after implementation was to move some of the display conversion code into mySQL so our queries return the dates in the formats we require. Otherwise, all works well.

What’s missing?

There is one glaring whole in the design and that is the ugliness called daylight saving. It becomes an issue if displaying local times. Our design converts the original activity time to the local time based on the current difference between local time and UTC. But if we’ve moved in or out of daylight savings (so the relative difference now is different to what it was then) our calculation will be out.

To manage that we need to know whether we, locally, were in/out of daylight savings when the activity was completed, and whether we are in/out of daylight savings now. Achievable but a not insignificant piece of work. The client agreed and thus we decided to ignore this issue reasoning:

a max of one hour out is liveable, and
the issue is consistent (meaning a series of activities reported in local time will still present in the correct order, even if for a period of time they are all 1 hour too early/late)

Quote of the week (19 October)

steven — Sun, 18 Oct 2009 20:48:53 +0000

From Antoine de Saint-Exupéry.

A designer knows he has achieved perfection not when there is nothing left to add, but when there is nothing left to take away.

Quote of the week (5 October)

steven — Sun, 04 Oct 2009 21:59:48 +0000

From Charles E. Phillips (president of Oracle):

Whenever two or more databases get together, it’s like people… it’s only a matter of time before they start to disagree.

Application design is like recording a cover version of a song

steven — Sun, 04 Oct 2009 00:56:58 +0000

Let’s face it. 99% of our design effort is spent on developing applications that already exist in some form or another. We work continuously to build a better mousetrap, not invent some fundamentally unique and novel way to catch rodents.

This is not to belittle the difference we make but to recognise we stand on existing shoulders. Or if we don’t, that our users do and will judge our efforts (fairly or unfairly) against those pre-existing expectations about what our [insert class of application here] application should look and feel like.

This need to try and marry those conflicting needs of “identifying with the original” and “being different” led me to compare the whole application design issue with music, in particular cover versions. Here’s another area where you are developing something that has both to be distinctive (and your own) while still recognising the essence of what came before.

what makes a good cover?

So what makes a good cover version? And what can that tell us about application development? Probably two conflicting goals:

be true to the original, but
add your own individuality.

Also hidden before the above two is “choose a good song to start with”. For software development that means picking an application that people are going to want to “listen” to. Your application version of a cover of the Macarena might not get the audience you would like, no matter how hard you work.

Be true
At some level each song (and therefore each application) has an underlying essence. Any to-do list manager needs to cover fundamentals like adding/removing items from a list. Any photo library needs to be able to add tags to photos to classify them, etc. The trick is to use the concept of the cover song to uncover what is the essential for your new version. What needs to exist for your users to recognise this as one of the type? And importantly for them not to dismiss it for missing something fundamental?

In looking for original applications you can start to diverge from the whole “application = cover song” metaphor, since with applications it is possible for what is considered the original to change. In music the original version of Tainted Love will always be by Gloria Jones, nomatter how many people have (a) never heard of it or (b) prefer Soft Cell’s version anyway. With applications what is considered original can vary, with first versions disappearing from view (Visicalc anyone?). In fact it’s probably more accurate to talk less of the original application and instead talk of the definitive or archetype. And recognise that it can change. For example 5 years ago the original/definitive social website you’d need to study would have been mySpace. Now it’s Facebook. Unless you’re in Brazil where it’s Orkut (thanks Oxyweb).

In some domains, there might not be an obvious original. In such cases the essence may be determined by reviewing multiple examples and drawing out the commonalities. And in that regard you’re moving towards the same approach as per the backs of most software packages, each with their feature lists comparing themselves (favourably of course) with the competitors.

Be individual

So once you’ve determined your original, and confirmed what features/functions are needed to be true to that original, now is the time to add your own spin. To add your personal creativity. To make the cover version.

And like musicians you’ll play to your strengths. In the same way that a Metallica cover of White Christmas is likely to include a few guitars, so a cover of the to-do list manager you create will reflect your own preferences in design, usability and approach. As long as the underlying essence remains evident, go for it.