I'm known as an advocate for users and speak about it extensively in all the Umbraco Level 1 courses I teach as well as online.

In my experience it's easy to build Umbraco websites in a way that content editors will love! And.. without sacrificing any of the freedom and fun we enjoy when developing umbraco sites.

So when Jan Skovgaard invited me to be the special guest speaker at the Umbraco DK Festival in Aarhus, Denmark by saying, "it would be nice with some focus on how to be a super hero to your users, since that's also our mantra in the solutions we build. We focus a lot on making the job of the editor as easy as possible." I couldn't resist!

Content editors need a superhero.
UmbracoMan is that hero!

How to Become a Superhero?

See my presentation with full transcript notes below:

Download the PDF

Thank you, Kraftvaerk!

I'd like to thank the team at Kraftvaerk for inviting me to #umbDkFest!

The venue, presentations, food, t-shirts, swag, everything even down to the smallest detail about the day was perfect! And with 150 Umbracians to talk to I enjoyed every minute. It was an awesome day! Thank you!

Photos

As an added bonus, I got to shoot alongside my friend and fellow photographer Niels Steinmeier.

Check out our photos of #umbDkFest at:

• http://www.flickr.com/photos/steinmeier/sets/72157633248476958/
• http://www.flickr.com/photos/percipientstudios/sets/72157633262945505/

 
cheers,
doug.

Courier 2.7 was current at the time of this writing

There are two parts to Courier: packaging and extracting. Both parts are available from the Courier section of the Umbraco backoffice interface as well as by right-clicking on items within the various trees of the backoffice.

There is also a command-line extraction tool. Its primary purpose is to allow automation of Courier activity as part of your Visual Studio project's build events, or from your build server. You develop locally and upon building your project your changes to datatypes, macros, templates, content, etc. can be loaded into a staging or QA site and automated unit tests run. Very slick.

You can find out more about this in the Umbraco Codegarden 11 Keynote video (at about 43 minutes in) and the Team Development using Courier session by Per. Both are highly recommended viewing.

Installing

The extraction console application (and source) is available from https://github.com/umbraco/Courier/tree/master/Samples/Umbraco.Courier.ExtractionConsole.

1. Copy the executable and associated dlls to some location. Personally, I copy into the site's ~/bin folder but that may not be required. You'll also end up with a ~/bin/plugins folder containing associated dlls. Additional information at http://our.umbraco.org/forum/umbraco-pro/courier/21756-Has-anyone-managed-to-get-Courier-working-with-the-command-line-tool.
2. Copy the ~/config/courier.config file to the extraction console's folder (~/bin in this example). Also copy it to the ~/bin/plugins folder. I'm not sure which folder contains the config file that is used but it definitely uses a local copy of the config file rather than the site's copy used by the Umbraco backoffice, thus allowing multiple config files to be used with the command line extraction console.
3. If not already done, create 'revisions' for each of the parts of the original site (datatypes, doctypes, macros, templates, media, document, etc. as noted elsewhere) using the backoffice. These revisions will be stored in the ~\App_Data\courier\revisions\revision_name folders.

Run from the Command Prompt

1. Once the packaging of the revisions is complete, open a command prompt. I don't know if it matters, but to be on the safe side I always run it from a command prompt that has 'run as Administrator' enabled.
2. Change directory to the desired revision and launch the extraction console:
   
   Command prompt:
   

   ..\..\..\..\bin\Umbraco.Courier.ExtractionConsole.exe
   

3. You should see a dependency graph being created with more than zero items (if it is zero items you may not have a valid revision or be in the correct revision folder)
4. Press the 'Y' key to continue
5. When prompted for the 'Website to connect to?' enter the 'alias' of the site as noted in the local courier.config file.

Identifying Errors

Be sure to turn on all logging in the config file. This will not slow down Courier appreciably, even for very large runs.

Log files will be saved in the ~\App_Data\courier\revisions\revision_name\app_data\courier\logs folder. Always review them as important issues may appear there that may not appear in the console window itself.

As powerful as Examine is (it's built on top of Lucene.Net), it isn't always convenient to get up and running quickly. Garrett Fisher asked how to use XSLTsearch instead. Let me show you how to do it.

How to do it

I'll assume that you have CWS installed already, and have also installed the XSLTsearch package. Because CWS already has almost everything we need we really only need to modify the original template to use the XSLTsearch macro

• In the Settings section, open the XSLTsearch template. Copy the <umbraco:Macro ...></umbraco:Macro> lines to the clipboard.
• Now open the Search (only called with template alias) template and delete the existing <umbraco:Macro runat="server" Alias="CWS_ExamineSearch" /> line.
• Paste in the XSLTsearch macro from the clipboard in its place.
• Save the template.

The updated template should now look like this:

<%@ Master Language="C#" MasterPageFile="~/masterpages/CWS_Master.master" AutoEventWireup="true" %>

<asp:content ContentPlaceHolderId="headerLinksContent" runat="server">  
</asp:content>

<asp:content ContentPlaceHolderId="SideBarContent" runat="server">  
</asp:content>

<asp:content ContentPlaceHolderId="ChildContent" runat="server">
    <div id="main" class="content oneCol left clearfix" role="main">
      <umbraco:Macro runat="server" Alias="XSLTsearch"
        macroAlias="XSLTsearch"
        source="-1"
        searchFields="@nodeName,metaKeywords,metaDescription,bodyText"
        previewFields="bodyText,metaDescription"
        previewType="beginning"
        searchBoxLocation="none"
        resultsPerPage="5"
        previewChars="255"
        showPageRange="0"
        showOrdinals="0"
        showScores="0"
        showStats="1">
      </umbraco:Macro>
  </div>
</asp:content>

Making it even better

By default, XSLTsearch will automatically look within the common document type properties. CWS has additional properties we should also search within. We can also stop displaying the search box on the results page since the site's banner has a search box already in it. Thus, we will make the following changes to the XSLTsearch macro parameters found on the Search template we edited a moment ago.

The XSLTsearch documentation (PDF) explains all the parameters in detail so I'll just show you the finished result. Every XSLTsearch user should look over the documentation to get the most out it and customize it to their needs.

searchFields="@nodeName,metaKeywords,metaDescription,headerText,bodyText,bodyTextColOne,bodyTextColTwo,photoText,formText"

previewFields="formText,photoText,bodyTextColTwo,bodyTextColOne,bodyText,headerText,metaDescription"

searchBoxLocation="none"

The fully updated macro should now contain the following parameters:

<umbraco:Macro runat="server" Alias="XSLTsearch"
    macroAlias="XSLTsearch"
    source="-1"
    searchFields="@nodeName,metaKeywords,metaDescription,headerText,bodyText,bodyTextColOne,bodyTextColTwo,photoText,formText"
    previewFields="formText,photoText,bodyTextColTwo,bodyTextColOne,bodyText,headerText,metaDescription"
    previewType="beginning"
    searchBoxLocation="none"
    resultsPerPage="5"
    previewChars="255"
    showPageRange="0"
    showOrdinals="0"
    showScores="0"
    showStats="1">
</umbraco:Macro>

Tidying up

Because we are using everything except the XSLTsearch macro we can delete the unused bits.

• Delete the Search page from the Content section
• Delete the XSLTsearch template from the Settings section
• Delete the XSLTsearch document type from the Settings section

And that's all there is to it!

For people who learned v5 only

This is an overview of what's different in version 4, from a v5 perspective.

The core concepts of document types, templates and razor logic are the same in both versions but there are differences you'll want to know about, along with what is better in each version (in my opinion).

Having taught the Umbraco Level 1 Certification Course in the USA and UK with v2, 3, 4, and 5 my view is that Umbraco 4 is currently the version that best meets real-world needs.

On with the show

Master the similarities and differences between v4 and v5, pick up best practices and hidden gems (and even some umbraco folklore too). Ideal for anyone who hasn't used v4.

Watch the video

Or download it here: When Less is More(mp4)

Or download it here: When Less is More(pdf)

So... does that mean I can you use the same ImageGen that I've enjoyed using with my Umbraco 4 sites with the all new, mvc-based Umbraco 5?
YES!

Disclaimer: these steps are a workaround until I get an updated version of ImageGen released that properly supports Umbraco 5's plugin architecture. When that's released you'll be able to install the package directly and not worry about this blog post. Okay? Okay.

Manual Installation

1. Download the ImageGen .zip package created for Umbraco v4
   http://our.umbraco.org/projects/website-utilities/imagegen
2. Extract the .zip file to a temporary folder
3. View the expanded files and copy the following files to your Umbraco v5.0 website
   
   • ImageGen.ashx goes in the root of your site
   • ImageGen.config goes in the root of your site
   • ImageGen.dll goes in the 'bin' folder of your site
4. Update the Web.config file in the root of your site to add the lines that have ImageGen in them:
   

    <configuration>
      <configSections>
         <section name="ImageGenConfiguration" type="ImageGen.ImageGenConfigurationHandler,ImageGen" />
      </configSections>
   
      <ImageGenConfiguration configSource="ImageGen.config" />
   </configuration>
   

5. Verify the installation by viewing http://localhost/imagegen.ashx?version
   (replacing localhost with your site's domain and/or port number)
   
   You should see a result like the following:
   
   ImageGen Professional version 2.5.7.27945
   Professional features are available for localhost
   Professional features are available for *.local
   

Razor Code for using ImageGen

You can use this same Razor code in a macro or directly in your template.

For these examples I've created two document type properties. One is an Uploader field and the other is a Media Picker. Since they behave slightly differently it's worth seeing both.

Using ImageGen with an Uploader property called uploadImage

 <p>Original image:<br />
   <img src="@Umbraco.GetMediaUrl(Model.Id, "uploadImage")" width="200" />
</p>

<p>Resized image:<br />
   <img src="/imagegen.ashx?width=200&image=@Umbraco.GetMediaUrl(Model.Id, "uploadImage")" />
</p>

Using ImageGen with a MediaPicker property called mediaImage

 <p>Original image:<br />
   <img src="@Umbraco.GetMediaUrl(DynamicModel.MediaImage, "uploadedFile")" width="200" />
</p>

<p>Resized image:<br />
   <img src="/imagegen.ashx?width=200&image=@Umbraco.GetMediaUrl(DynamicModel.MediaImage, "uploadedFile")" />
</p>

Tip: for more elaborate Razor macro inspriation, check out Warren Buckley's GitHub collection of snippets at https://gist.github.com/warrenbuckley

Remote, Cloud, and Non-Local Images

The above works perfectly for images stored locally. If your images aren't stored locally on the web server it won't work.

But... ImageGen Professional's "Remote Images" saves the day!

You just need to include the full url to the image in your call to ImageGen.ashx, and update the ImageGen.config file to whitelist your domain(s) to make it work. The ImageGen Reference Manaul explains whitelisting and remote urls.

As an added benefit, with ImageGen Professional you can turn on client-side image caching, which can greatly improve the performance of your site, especially with remote images that might have some latency in fetching.

ImageGen Professional's remote image capability works for images served from a remote website (flickr, twitter, etc.), those stored in the cloud (EC2, Amazon, etc.), saved as blobs in a database, and with all future Hive providers. With ImageGen Professional you can rock them all.

...and that's all there is to it!

In order to travel to the annual CodeGarden conference I need my visa application approved and passport returned from the UK Home Office Border Agency within the next week.

Yes, you can help!

We now have an answer

I am requesting an expedited decision of my case, now two months old.

Applicant: Douglas James Robar
Case Ref: 014264466

The long of it

I'm an American living in Cambridge UK for 2.5 years. My wife is a PhD student at Cambridge University and has a student visa. I have a student dependant visa that allows me to work in the UK.

I own and run Percipient Studios. Not only do I offer website design and implementations using the Umbraco CMS, I am also the only official Umbraco Level 1 Trainer in the UK and have taught hundreds of UK software developers, webmasters, and IT staff attain the valuable Umbraco Certified Developer certification and tens of organisations become Umbraco Solution Providers.

I like being in the UK. My family and I would like to stay for some time even after my wife finishes her PhD. And I want to continue my business here.

For this I need a new visa and have applied for a Tier 1 General visa. I fully qualify according to that points-based system, provided all needed documentation and biometric evidence, and even used the excellent Global Visas to ensure a flawless application. My application was delivered before the deadline of 4-April (two months ago).

In mid-June I am to give a presentation at the annual Umbraco conference, CodeGarden, and will also be moderating a panel discussion. CodeGarden (twitter: #CG11) is the single most important event of the year for my business; I get work as a direct result of attending in addition to its being a key source for my own professional development in the field.

Though the Home Office suggests that 75% of cases are decided within four weeks, my case is still outstanding after 8 weeks.

I need a miracle. The Home Office won't discuss my case with me until 14 weeks have passed. I've called. Multiple times. It will only (only?) have been ten weeks by the time CodeGarden begins. But without my approved visa and passport returned I can't leave the country.

I had thought of getting an emergency second passport from the US Embassy in London (which they can do within 36 hours). But have found out from the Home Office that if I leave the UK before my visa has been issued, even on a valid passport, my visa application will automatically and immediately be cancelled.

Updates

25-May

At the Home Office's recommendation I have faxed a request for urgency to 0114 207 2536. I was told that no reply to my request will be given and no assurance can be made of fulfilling my request for urgency. Also at the HO's recommendation my fax included the important "do not withdraw my application" sentence. I'm not sure why this should be necessary but twice I was told it should appear on the fax.

1 June

Blog post and tweet to escalate issue in the hope that something can be done to ensure I will be able to attend the CodeGarden conference.

UPDATE: I contacted my local MP (Julian Huppert, twitter @julianhuppert) at the recommendation of many and his office was very responsive. They called me back within two hours with the news that "You will be pleased to know your application is nearing the end of the review process and you will be hearing shortly." I then asked when "shortly" might be. "If you have not heard from UKBA by Sunday 12th June please do contact Julian again."

2 June

Potentially hearing something by 12 June is not sufficient - I would then still need to wait to receive my passport by post. I am still looking for assistance to successfully complete my visa application and return my passport (in my hands) by 9 June. That's only one week away.

Others have suggested these avenues, which I will be following up on:

• "Contact the US Embassy Consular Affairs section and have them intervene on his behalf. They are the only outsiders with enough juice to make it happen."
• Continue tweeting and include @UKBorderAgency_ @UKBAinUSA and possibly others.
• Contact Jim Paice, MP for SE Cambs and somehow involved with the UK Border Agency.
• If you have other suggestions please leave them in the comments!

UPDATE: Benjamin Howarth has contacted his MP and discovered "MPs have access routes to the UK Passport Agency that are not available to the public, so Julian Huppert is your best bet. Letters of commercial support as well are also helpful apparently, so I sorted a petition for you: http://www.petitiononline.com/drobar11/petition.html"

3 June

The volume of petition signatures (currently 140 signatures!), tweets, retweets, and outpouring of concern and support is overwhelming. Thank you!

I've emailed my MP again and am awaiting a response. I'll keep you posted, and as ever please accept my deep thanks and let me know if you or someone you know can assist in expediting the approval and return of my visa application and passport.

4 June

Things seem to be moving!

I received this note from Julian Huppert's office today:
"I have been in touch with the UK Border Agency about the need for Doug to receive the determination of his visa application and passport returned. The issue has been referred to the Border Agency MP Account Managers Office. I will contact them again first thing on Monday morning and let you know the outcome."

6 June

So far there are 177 signatures on the petition, thank you!

Please help

If you know anyone at the Home Office or Border Agency I would greatly appreciate your assistance.

Please sign my petition at http://www.petitiononline.com/drobar11/petition.html.

Email a personal recommendation to my MP, Julian Huppert to give urgency to Douglas Robar's visa application.

We now have an answer.

Good and bad news

I just heard from from Julian Huppert's office, who have been tremendously helpful. There is good news and bad news:

• Good news = My passport will be dispatched today!
• Bad news = my Tier 1 General visa application was denied

This means I can attend CodeGarden! And my existing visa is still in force so I can stay and work in the UK until my wife completes here PhD sometime in the next year.

I have hugely mixed emotions right now. On the one hand I am disappointed in the visa decision (I'll find out the reason when I receive the paperwork via post in a few days). On the other hand I'm overwhelmed by all for your efforts, good wishes, and prayers! How could one man be blessed with so many great friends and colleagues?

Thank you!
doug.

Umbraco 4.7 RC has an all-new Razor macro engine, a foretaste of the coming MVC goodness of Umbraco 5.

As everyone knows, I'm an XSLT fanboy; it is lightning quick, powerful, an open standard, and I don't have to open a Visual Studio solution every time I want to make a minor change. Besides, my C# skills aren't amazing. Thankfully with Umbraco, I don't need to be a .NET guru.

I've always been a little uncomfortable with how wide the gap is between XSLT and .NET macros though. With Razor, we may have found the middle ground. Razor just might be the go-to language for most macros from now on, though I'll need more time with Razor to know for sure.

My first Razor project, RazorSearch

As a first project I'm writing RazorSearch for Umbraco. Basically, I'm recreating the functionality of XSLTsearch by implementing it with Razor.

As some of you may know, XSLTsearch was originally written in Notepad. I don't want to repeat that terrible editing and debugging experience. I'd like to use something more helpful as I learn Razor.

Visual Studio and (no) Intellisense

I fired up Visual Studio 2010 Professional, opened my local website, and was hoping for a lot of intellisense magic to give me hints along the way.

But no.

Intellisense was missing for @Model. I (and a lot of other early adopters on twitter) wanted some helps. How can I get some intellisense love with dynamic objects that are not determined until runtime?

Make Intellisense and Debugging Work

Being easier to show you how to do it than write about it, here's a short video that demonstrates how to get as much Razor Intellisense for Umbraco 4.7 (RC) macros as I've been able to come up with so far.

As an added bonus, I also show how easy it is to debug Razor macros without having to compile the source. It's really easy!

Watch on YouTube

Helpful Resources

As you begin your Razor macro journey, you may find the following resources helpful. I sure have!

• @Model's (DynamicNode and DynamicNodeLis) Properties and Methods Reference
• http://our.umbraco.org/wiki/reference/code-snippets/razor-snippets
• Razor feature walkthrough (part 8)
• Razor feature walkthrough (part 7)
• Razor feature walkthrough (part 6)
• Razor feature walkthrough (part 5)
• Razor feature walkthrough (part 4)
• Razor feature walkthrough (part 3)
• Razor feature walkthrough (part 2)
• Razor feature walkthrough (part 1)
• Razor Syntax Quick Reference
• Inline Razor Syntax Overview
• Introducing "Razor" - a new view engine for ASP.NET

If you've never used the Umbraco dictionary capability before, here's a primer and "how to" guide to quickly set up XSLTsearch in your multi-lingual website. We'll cover the basics briefly and focus on how to use XSLTsearch in an Umbraco installation with multiple language sites.

You can find a more complete discussion of how to set up multi-lingual websites in the umbraco.tv episodes about Running Multiple Sites.

Install XSLTsearch

Install XSLTsearch from the Umbraco Package Repository, or by first downloading it from http://our.umbraco.org/website-utilities/xsltsearch.

Umbraco configuration steps

Add languages for your Umbraco installation

Once XSLTsearch is installed, go to the Settings section of the Umbraco back office administration interface, and expand the Languages area. Here you'll see all the languages that your sites will be able to use.

If your sites will need a language that isn't yet listed, right-click on the Languages item and create a new language.

Let's suppose we want to add German (as spoken in Germany) as a language for one of our sites. Select "German (Germany)" from the exhaustive list of languages and cultures:

We now have two languages available for use in our site, English (United States) and German (Germany).

You can add as many languages for as many sites in Umbraco as you need following this same procedure.

Create multiple sites in Umbraco

It is best-practice to nest all your site's content beneath a homepage. The wisdom of this practice is revealed when you want to add another site to your Umbraco installation, as we will do here.

For instance, you might have your public website, intranet, and blog all in one Umbraco installation. Or perhaps you need to present one site in a lot of different languages. Or even a combination of both.

I'm going to assume you've got two sites set up similarly to that shown below, two sites with one for each language. For convenience, I have named each homepage with the two-letter culture code (EN and DE).

Assign hostname, language, culture to each site

Now that you have two sites, you need to tell Umbraco which site is associated with each language. This is a simple point-n-click operation.

Right-click the homepage for one of the sites and select the 'Manage hostnames' menu. In the window that appears, assign a domain for this site and select the appropriate language.

Repeat for all sites.

You can find lots of forum posts about using separate domains or a single domain and folders to distinguish one site from another via the URL. Depending on your preferred URL you'll end up changing either the  umbracoHideTopLevelNodeFromPath (in web.config file) or useDomainPrefixes (in /config/umbracoSettings.config). The combination of these settings will effect the URL for the pages in each site, but is beyond the scope of this article.

And now, back to XSLTsearch

If using XSLTsearch 3.0, you should modify it as noted here. This will be the default behavior for future versions of XSLTsearch. This step is only necessary for v3.0.

Create a search page for each site

Now create a search page for each site. Right-click on the home page of each site and select the Create menu. Name the page and select the XSLTsearch document type.

Your content tree will now look similar to this, with a search page in each site.

Translate the XSLTsearch dictionary keys for each language

At this point, your search will work properly in all sites but all the static text on the search page will be in English, which isn't what we want.

The last step is to translate the XSLTsearch dictionary items into the languages of your site.

You may notice that I don't speak German. I've used Microsoft Translate and Warren Buckley's handy Dictionary Translator for Umbraco. I hope you can excuse any mistakes :)

In the Settings section of Umbraco's back office, expand the Dictionary area. You will see a folder of terms used by XSLTsearch. Select each dictionary item in turn, entering the appropriate translation for each language of your site. If you leave any blank the default English term will be used in its place so at least your site will have text for everything, albeit in English..

Go forth and search!

That's all there is to it. All the setup work is now complete and you're ready to enjoy localized search pages across all the languages of your site. If you later add another language site all you'll need to do is create an XSLTsearch page in the new site and translate the dictionary keys into the new site's language. It couldn't be easier.

Here's what the finished result looks like, with example search pages in both English and German:

An English search page

A German search page 

What is the App_Code folder you ask? As Microsoft puts it, "you can store source code in the App_Code folder, and it will be automatically compiled at run time. The resulting assembly is accessible to any other code in the Web application. The App_Code folder therefore works much like the Bin folder, except that you can store source code in it instead of compiled code.

Extending XSLT's capabilities

Compiled XSLT extensions

In the past, when you wanted to add a little extra oomph to your XSLT macro you probably would have created an XSLT extension in Visual Studio, compiled it to a dll, copied it to the /bin folder of your site, and referenced it by updating the /config/XSLTextensions.config file.

Simple, no?

Well, to be honest, sometimes it does seem a bit over the top for just a few lines of .Net code. Especially if you aren't a .Net Jedi™.

What's wrong with <msxml:script> blocks?

The other option in such a case is to place your .Net code in an <msxml:script> block directly in your xslt file. I've found this to be a powerful and easy-to-implement solution. Indeed, all versions prior to XSLTsearch 3.0 used this technique as well.

There are down-sides to inline script blocks, though. For one thing, the macro will compile itself every single time the macro is run. That doesn't take long, but it adds up. Worse, you'll find a lot of tiny files from those compilations cluttering your system TEMP folder. This is especially evident if you haven't disabled debugging in the web.config file. These are small files but on a busy site they add up quickly and could potentially fill your system drive. And because the system TEMP folder is outside your website your macro won't run in medium trust.

Benjamin Howarth (@benjaminhowarth) discussed these and more in his illuminating presentation at the Umbraco 5th Birthday party in London, Medium Trust for Umbraco 4.x.

I still like the benefits of inline scripting:  all code is available for easy inspection, learning, and editing, and you never have to fire up Visual Studio ("oh, that project was created with VS 2005 and I only have VS 2099… hmmmm"). On the other hand, the downsides of not creating a proper XSLT extension are fairly significant.

Welcome to App_Code XSLT extensions in Umbraco

New to Umbraco 4.5, XSLT extensions in the /App_Code folder provides the best of both worlds! Code that is right in front of you and easy to edit, even for non-"VisualStudio junkies". And, you get strongly-defined (safer), cached-at-application-level (faster), and medium-trust-support (cheaper hosting). Wow!

And it is so easy to do! Let me show you how.

Reworking an old example

I'm going to re-work an older post entitled, Advanced XSLT with .NET Namespaces. You might want to read that article if the following code doesn't make sense to you.

In that older article I used an inline script block to determine the size of an uploaded file. This is something that can't be done from XSLT alone so I added the following C# script block. Let's remove the code from the script block and put it in an App_Code extension.

<msxml:script language="CSharp" implements-prefix="ps">
    <msxml:using namespace="System.IO" />
    <msxml:assembly name="System.Web" />
    <msxml:using namespace="System.Web" />
 
    <![CDATA[
    public String uploadFileSize(String filePath) {
 
        if ((filePath != null) && (filePath.Length != 0)) {
            String localFile = HttpContext.Current.Server.MapPath(filePath);
            if (File.Exists(localFile)) {
                FileInfo fileinfo = new FileInfo(localFile);
                return String.Format("{0:#,###,###.##}", (fileinfo.Length / 1024));
            }
        }
        return null;
    }
    ]]>
</msxml:script>

1. Create a file in the /app_code folder

All we have to do to convert this script block to a proper XSLT extension is create a file in the /app_code folder of my site. I'll call it PShelpers.cs. You can create these App_Code XSLT extensions with Notepad, Visual Studio (tip: create a 'Class Library' project), or anything in between.

Your baseline, starting file should look like this:

using System;
using System.Collections;

namespace ClassLibrary
{
    public class Class1
    {
    }
}

2. Name your class and namespace, add references

Now, change the namespace and class names for your project, add the umbraco api reference and any other namespaces you might need:

using System;
using System.Collections;
using System.IO;
using System.Web;
using umbraco;

namespace PS
{
    public class Helpers
    {

    }
}

3. Add [XsltExtension] and zero-parameter constructor

Add the [XsltExtension] line to the namespace and create a a zero-parameter constructor so that Umbraco will automatically pick this up as an XSLT extension:

using System;
using System.Collections;
using System.IO;
using System.Web;
using umbraco;

namespace PS
{
    [XsltExtension]

    public class Helpers
    {
        public Helpers() { }
    }
}

4. Paste the code from your script block

Now all you do is copy-n-paste the code from your script block.

Remember, all your functions must be public static.

Here's the final version of our re-worked example, this time as an App_Code XSLT extension:

using System;
using System.Collections;
using System.IO;
using System.Web;
using umbraco;

namespace ps
{
    [XsltExtension]

    public class Helpers
    {
        public Helpers() { }

        public static String uploadFileSize(String filePath)
        {

            if ((filePath != null) && (filePath.Length != 0))
            {
                String localFile = HttpContext.Current.Server.MapPath(filePath);
                if (File.Exists(localFile))
                {
                    FileInfo fileinfo = new FileInfo(localFile);
                    return String.Format("{0:#,###,###.##}", (fileinfo.Length / 1024));
                }
            }
            return null;
        }

    }
}

Using your XSLT extension

Now that you have a functioning XSLT extension you can remove the msxml:script from your xslt file and update the references to the new namespace and class. In our example, from 'ps' to 'PS.Helpers'. The macro will work as before, only in medium-trust and with better performance.

Additionally, when you create a new macro in Umbraco your App_Code XSLT extension will automatically be referenced. And when you click the 'Insert xsl:value-of' toolbar button in Umbraco's XSLT editor you can select your App_Code XSLT extension for point-n-click simplicity.

"Gotcha" - only one language in App_Code

An important point to mention is that all the files in App_Code must use the same .Net language. You cannot mix C# for some files and VB.net for others, for instance. However, there is a solution if you must mix languages in the /app_code folder.

"Gotcha" again - App_Code bugs give YSOD

Never edit anything in the App_Code folder on a live site. If you make a mistake the site may display a Yellow Screen of Death (YSOD). In some cases even the Umbraco back end won't respond properly, or the site's application pool may shut down after repeated errors. You've been warned and I take no responsibility. Okay? Okay. But… if you are careful with your code (as of course you will be) then app_code is no more dangerous than a dll.

XSLTsearch 3.0 uses Umbraco dictionary keys to translate the various bits of text that appear on the search page. The same search macro can be used everywhere on your site and will display in the site's language and culture.

You can either search all pages or specify the page to begin searching beneath (the 'source' parameter in the XSLTsearch macro). If you have multiple websites within one Umbraco installation you can make a small change to XSLTsearch and each site will instantly search only within its own pages.

Here's what a typical multi-site installation would look like:

We'd rather not create multiple templates for XSLTsearch for each site, nor insert the XSLTsearch macro in a richtext editor page on each site, forcing editors to decide what to enter in each of the macro properties.

Thankfully XSLTsearch is easy to modify to meet your needs. The key, as Sebastiaan says, is to use the ancestor-or-self XPATH axis to set the source used when searching. We want to use the top-most page in whatever site is currently being viewed. That is, to the page that is at the first level in the content tree.

By default, XSLTsearch will search all pages if you don't tell it otherwise.

<xsl:call-template name="search">
  <xsl:with-param name="items" select="umbraco.library:GetXmlAll()/*"/>
</xsl:call-template>

What we want to do is change the default behavior to this:

<xsl:call-template name="search">
  <xsl:with-param name="items" select="$currentPage/ancestor-or-self::*[@level = '1']"/>
</xsl:call-template>

That's all there is to it! Thanks for the tip, Sebastiaan!