Progress bar with progress messages for long running processes.

Sitecore has made it very easy from within the sitecore client to click a button do the following:

  • Start a long running process as a background job.
  • Showing a progress bar dialog and define the title.
  • Provides the ability to update the message as the job progresses in the background.
  • Hide the progress bar once the background job completes.

It seems to be a feature that has not been used much, so I hope this blog post will draw attention to it. I will assume that you already know how to add a custom button and execute code when it is clicked, using a customer command class, if not see here and or google it.

Step 1 – Setup

In the overridden Execute function for the custom command get the details you need, in our case the item id, language and database. Then call Client page start, which calls the Run function.

public class ExportBookCommand : Command
{
        public override void Execute(CommandContext context)
        {
            Assert.ArgumentNotNull(context, "context");
            Assert.IsNotNull(context.Items, "context items are null");
            Assert.IsTrue(context.Items.Length > 0, "context items length is 0");
            var item = context.Items[0];
            var parameters = new NameValueCollection
            {
                [Constants.Parameters.Keys.Id] = item.ID.ToString(),
                [Constants.Parameters.Keys.Language] = item.Language.ToString(),
                [Constants.Parameters.Keys.Database] = item.Database.Name
            };
            Context.ClientPage.Start(this, nameof(Run), parameters);
        }
        protected void Run(ClientPipelineArgs args)

Step 2 – Show progress bar

The Run function (see code below) is responsible for the following:

  • Do any validation and show an alert if required.
  • Build any classes your background job is going to need
    • We are exporting a book to multiple word word documents.
  • Call ProgressBox.Execute which is responsisble for the following:
    • Show the progress bar
    • Defines the title for the progress bar
    • Defines the initial message for the progress bar
    • Starts the background job and calls the function StartProcess todo the work.
      • Adds the Job to the current client context, which we use later.
protected void Run(ClientPipelineArgs args)
{
	Assert.ArgumentNotNull(args, "args");
	// Validate args, show an alert if not valid
	if(notValid(args))
	{
		SheerResponse.Alert("explain what went wrong"));
		return;
	}
    // create the data, for the background job
	var book = _bookFactory.Create(args.Parameters);
	Assert.IsNotNull(book, "Could not create book model");
	var bookArray = new object[] {book};
		// show progress bar and start background job
	ProgressBox.Execute("Job name, used as the inital message shown on the prgress bar",
		Translate.Text("The title of the progress bar"), "~/Network/32x32/server_into.png",
		StartProcess, bookArray);
}

private void StartProcess(params object[] parameters)
{
	Assert.ArgumentNotNull(parameters, "parameters");
	var book = parameters[0] as Models.Book;
	Assert.IsNotNull(book, "The first element in the object array is not a book");
	var exportBookService = new ExportBookService();
	exportBookService.ExportBook(book);
}

Step 3 – Update progress message

To update the messages for the progress bar is simple as the current client context has a Job property which makes it simple to add messages, relating to the progress of the process.

Context.Job.Status.Messages.Add($"{Translate.Text("export:progress")}{folder.Name}");

In our solution we showed a new message for each top level folder (which was a letter) we exported, see the image below, which is currently processing the letter B

I hope this blog post has helps to give the user a meaningful indication of what is happing when a process takes a long time t complete.

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 )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.