What on earth is Umbraco ServerVariables Parsing?!

Hello all this is another ‘What on Earth‘ blog post detailing a specific feature or functionality of Umbraco that may be hidden away a little & this blog post is here to help describe & detail it.

What is Umbraco ServerVariables Parsing?

Umbraco ServerVariables Parsing is an event that we can hook into as developers, normally in the Application Startup event of Umbraco that allows us to easily add items to a dictionary of items available to us via Javascript.

To quote from the documentation page on our.umbraco.org:

In v7 once a user is authenticated a request is made to retreive the Server Variables collection from the server which creates a global dictionary object that is accessible in JavaScript. This dictionary contains information based on the current Umbraco environment for which the JavaScript and client side needs to know about. Information such as whether the application is running in debug mode, the service API URLs, or other non-sensitive global server side variables.

Why would I use Umbraco ServerVariables Parsing?

So know we what it is, why would we want to use this? Well there can be many use cases for this, as you can store any string or JSON object in this collection that can then be accessed globally in JavaScript. So you may have settings or configuration values you may want to store, but the most common use case is storing WebAPI URL endpoints, that your AngularJS property editors or any other component can retrieve the WebAPI URL and post directly to it.

You may wonder why you would want to store the URL to a WebAPI. A good example is that in Umbraco introduced a breaking change based on how certain WebAPI URL endpoints are structured. So depending on what version of Umbraco you are using you can on Application Startup of Umbraco detect what version and use the correct URL format for the WebAPI, as opposed to traditionally putting the URL into your AJAX JS calls and it breaking between specific versions of Umbraco.

How do we go about using ServerVariables Parsing?

Now we know What & Why we would use ServerVariables Parsing, we can go on to know how to use this with a simple example & then followed by a more complete or real world example.

Firstly start up a latest Umbraco 7 site and login to the Umbraco back office, from here open your browser developer tools and in the console type the following: Umbraco.Sys.ServerVariables you will see something similar in your browser developer tools.

umbraco.sys.servervariables

If we expand some of the objects in the JSON then we can see further information about our Umbraco installation, with ServerVariables Parsing event, we can add item/s to this JSON object that we can then use in our JavaScript code where needed.

umbraco.sys.servervariables_extended

So let’s learn how to add to this JSON object. Create a C# class called something like UmbracoStartup.cs or similar in there we can add this code:

public class UmbracoStartup : ApplicationEventHandler
{        
    protected override void ApplicationStarted(UmbracoApplicationBase umbracoApplication, ApplicationContext applicationContext)
    {
       
        //When Umbraco has started up - wire up the ServerVariablesParser event
        ServerVariablesParser.Parsing += ServerVariablesParser_Parsing;
    }

    void ServerVariablesParser_Parsing(object sender, Dictionary<string, object> e)
    {
        e.Add("warrensExample", new Dictionary<string, object>
        {
            { "Name", "Bob" },
            { "Age", 28 },
            { "LikesUmbraco", true },
            { "UseYourImagination", "Will Do" }
        });
    }
}

If we restart our Umbraco application this code should fire & add our items into the JSON object like so:

umbraco.sys.servervariables_customised

 

However the example I gave is not overly useful and a more real world example is to add WebAPI Url endpoints. This snippet below is taken from Shannon Deminick’s Umbraco Blog Package Articulate which uses a URLHelper to figure out what the WebAPI Route URL will be.

static void ServerVariablesParser_Parsing(object sender, Dictionary<string, object> e)
{
    if (HttpContext.Current == null) throw new InvalidOperationException("HttpContext is null");
    var urlHelper = new UrlHelper(new RequestContext(new HttpContextWrapper(HttpContext.Current), new RouteData()));
    e.Add("articulate", new Dictionary<string, object>
    {
        {"articulateImportBaseUrl", urlHelper.GetUmbracoApiServiceBaseUrl<ArticulateBlogImportController>(controller => controller.PostImportBlogMl(null))},
        {"articulatePropertyEditorsBaseUrl", urlHelper.GetUmbracoApiServiceBaseUrl<ArticulatePropertyEditorsController>(controller => controller.GetThemes())}
    });
}

Then Shannon uses it in a JavaScript Angular Property Editor like so:

angular.module('umbraco').controller("Articulate.PropertyEditors.ThemePicker", function ($scope, umbRequestHelper, $http) {

    var url = Umbraco.Sys.ServerVariables["articulate"]["articulatePropertyEditorsBaseUrl"] + "GetThemes";

    umbRequestHelper.resourcePromise(
            $http.get(url),
            'Failed to retrieve themes for Articulate')
        .then(function (data) {
            $scope.themes = data;
        });

});

Hopefully now you have a better understanding of Umbraco ServerVariables Parsing along with how & why you would want to use it.

So go forth & code and make your Umbraco sites better :)

About these ads

2 responses to “What on earth is Umbraco ServerVariables Parsing?!

  1. I’ve used something similar on other sites (not via this method though). If you want a real world example I started sending the server date down the wire so my client side validation to make sure dates were not in the past used a datetime I knew to be right as sometimes clients machines have duff dates set on them. This would be a great way to get that server datetime down the wire.

    Good read and find :)

    • Glad you found this a good read Pete. Always nice to hear & get feedback.

      So for me to understand your example fully, you was sending the server’s datetime into the JSON object so that you can use it to help invalidate the client’s browser cache of resources such as JS & CSS files, yes?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s