Adding custom commands, global commands and new command groups to the LightSwitch button ribbon.

<<Warning.  Creating commands the LightSwitch way takes a lot of time.  Why don’t you read this post instead? >>

 

I don’t know about you guys, but when I saw my first LightSwitch demo, it was love at first sight.  The thing I found most impressive, except for the sheer amount of time required to actually create an application, was how thick the generated client was.  A collapsible menu bar, with screens nicely grouped into categories, runtime editing of your screen, flipping a combo box to display a string with the Bing Map Control instead, a button ribbon filled with different commands in all kinds of groups, …

Ay there’s the rub, as a certain dude once said.

The "actions" category.... Woot!

Adding new commands from the IDE is easy, but they always appear in the same “Actions” category.  (Note: Unless you add the <Generated /> tag to the command in the ApplicationDefinition.lsml file… Then they appear in the “Data” category.)  There’s really no obvious support to assign your command to a certain category.

Another issue, is that command are defined on a screen level.  But what if I want a command that has nothing to do with the current screen?  A “global command”, sort of speak.  For example, what if I have some kind of messaging module, and I want a command that’s always visible to alert the user if he/she has new or urgent messages?

And apparently, I’m not the only one dreaming of custom command groups, or “global commands”…

The bad news: I have flipped LightSwitch on and off, turned the IDE inside and out, tried all kind of weird attributing in the ApplicationDefinition.lsml file, and there’s no easy way to implement this from the IDE (or at least not one that I could find).

The good news, for the ” pre-LightSwitch generation, old-school developers, not afraid of writing a couple of lines of code”, is that the LightSwitch framework itself does support it, and here’s how you do it…

Prep work:

Create a new LightSwitch project, or open an existing one.   Select your project in the Solution Explorer, and flip it to File View.

Creating the command group:

The first thing we want to do, is create a new command group.  Add a new class to your client project, called MyCustomCommandGroup.  The magic interface to implment here is Microsoft.LightSwitch.Runtime.Shell.ViewModels.Commands.IShellCommandGroup.  Your client project already has the required reference to the Microsoft.LightSwitch.Client.dll.  When you implement it, the important properties and methods are:

• Name : the unique id of your command group
• DisplayName : the “title” that is shown on your command group, preferably localized
• Commands : the commands in this command group

Creating the command:

Next step, creating a command to put in our command group.  Add a new class to your client project, called MyCustomCommand.  The interfaces we’ll implement are: Microsoft.LightSwitch.Runtime.Shell.ViewModels.Commands.IShellCommand (required), Microsoft.LightSwitch.IExecutable (optional, but advised) and System.ComponentModel.INotifyProperyChanged (optional, but advised).

Once again: an overview of the important properties and methods:

• Description: used in the tooltip, preferably localized
• DisplayName: the “name” of your command, think I18N again
• ExecutableObject: the “executable object” that contains the properties and methods to actually do something.  LightSwitch makes a separation between the Command (the viewmodel for the command you see in the button ribbon, and the actual ExecutableObject: the model, that actually does your stuff).  Because we implemented both interfaces in our MyCustomCommand class, you can simply implement it as: “return this;“
• Group: the unique id of the command group where this command should be placed
• Image: the URI to the image to display, wrapped inside a System.Windows.Media.Imaging.BitmapImage for convenience
• ExecuteAsync: the method that the default shell implementation calls when your command is clicked.  Here, you can implement the actual code that gets executed, for example: show a modal dialog window.

Showing your command group in the shell:

Finally, just because you created the command and the command group, doesn’t mean that the shell will actually display it.  The shell doesn’t even look for your custom command groups, but instead tries to find CommandGroupProviders, that are responsible for… Take a guess…

Add another class to your solution: MyCommandGroupProvider.  Two things of interest here: firstly, your class has to implement Microsoft.LightSwitch.Runtime.Shell.ViewModels.Commands.IShellCommandGroupProvider, with only method to implement:

• IEnumerable<IShellCommandGroup> GetShellCommandGroups(IScreenObject currentScreen) : this method is called whenever a new screenobject becomes the “active screen”. The point here of course, is that the provider provides the custom commands to the shell. Feel absolutely free to ignore the active screen argument and always return your MyCustomCommandGroup instance.  This way, we have achieved one of our two goals: creating a “global command”.

Second thing to note, is that we should expose this MyCommandGroupProvider to the shell implementation.  For this, we will use the Managed ExtensibilityFramework, by adding an export attribute:  [Export(typeof(IShellCommandGroupProvider))].

Finally, hit F5 and with a but of luck, you will see the new command group with your new command in the shell…

New command & command group

And when you click it:

Modal popup pops up

Phew, not really all that hard now was it?  (Although I can assure you, without any documentation on the subject at hand, it was quite a challenge finding the right interfaces…)  This post, even without code, is already quite lengthy, that’s why this time I opted to simply describe the required process/interfaces, and not post any code.  However, if you want to see my implementation:

1. Download this little quick&dirty sample* and unzip it.  – The project is called MessagesExtension.client. Hint… Hint…
2. Create a new LightSwitch project, or open an existing project.
3. Right-click the solution > “add existing…” > select the MessagesExtension.client you downloaded to include it in your solution.  (It might complain about some references, in which case you need to remove and add the required references again… Sorry about that, but ran out of time to investigate this.)
4. Select your LightSwitch project, flip it to Logical view, and select your client project.
5. Add a reference > project > MessagesExtension.client
6. Also, add a new class to your client project: public class CommandProvider : MessagesExtension.Client.MessageCommandGroupProvider{}  — Yes, this really is all of the required code, I used an InheritedExportAttribute instead of the normal ExportAttribute one…
7. Hit F5, debug and change to your likings.

All done for tonight, and I hope you enjoyed reading my seventh post on as I did writing it.  If you want to get in touch with me for any (non-obscene) reason, feel free to drop me a tweet (@janvanderhaegen) or a comment in the comment section below.

* Disclaimer: the sample code is not free, but payed for with 1  little tweet.  That should help me get in touch with you, my dear readers, all 12 of you! 😉  I promise I won’t pull this advertising trick each time.