Introduction

Ever since the advent of myHTPC in early 2003, PC and home theater enthusiasts have been searching for ways to integrate emerging technologies with their entertainment systems. Early HTPC (Home Theater PC) communities grew up around the idea of extending HTPC software with “plugin” applications. Unfortunately, most HTPC applications were never designed with a true plugin architecture in mind, and so the few plugins that were developed were usually little more than separate programs that could be launched from the main front-end application. When the development of Meedio started towards the end of 2003, one of the main design principles that the HTPC community requested was an architecture that supports native plugins which truly integrate with the host platform. Meedio met this challenge with a solution that is not just a digital media center application, but an entire platform for creating new applications. In fact, it is so easy to create powerful new applications with Meedio that in the eight months since Meedio Essentials was released, over 180 plugins have been published in the Meedio Add-Ins Directory.

This tutorial will walk you through the whole process of creating a Meedio plugin. We will be using Windows Script Components and VBScript, so all you will need is Meedio and Notepad. We will cover the creation of the plugin description file, the code for the plugin, a new screen and finally the creation of a Meedio Plugin Package to distribute the plugin.

Note: You may need to install Windows Script 5.6 (http://msdn.microsoft.com/library/default.asp?url=/downloads/list/webdev.asp), especially if you are not running Windows XP.
Describing the plugin

In order for Meedio to recognize and understand your plugin, you must first create a plugin description file. These files have the .plugin extension and are simple XML files; they contain basic information about your plugin such as its name, type, documentation, the name of the author and such. You can easily create them using Notepad but, fortunately, Meedio provides a tool to help us create .plugin files. This tool is called PluginEditor.exe and it is located in the Meedio installation directory.

So, our first step will be to use the plugin editor to create our .plugin file. Double click on PluginEditor.exe.

First of all, we set the name of the plugin; it is the name by which the plugin will be known to everyone. Secondly, each plugin must have a unique identifier, also known as the plugin ID. Meedio dictates that this must be a GUID (Globally Unique IDentifier). It is not important for us to understand this completely; just know that it is a way to identify your plugin from all others. You can click the “Generate ID” button to create a new ID for your plugin. Note that this only has to be done once, when you first create the plugin. After that, its ID will remain the same forever.

Then, we enter the version and the status. The type of our plugin will be “Module”, which means that users will be able to add it to their Meedio menu structure and it will be launched by Meedio only when the user clicks on it. We also set the module type to “Module” to signify that it is a simple module; most plugins are. Finally we enter a short description.

Now, we move on to the details tab. Here, we must specify the name of the folder where the plugin will be installed. We do not need to enter a full path, as Meedio will figure that out automatically, but we should pick a fairly unique name that describes our plugin. We must also tell Meedio what the main file of our plugin will be. This is the file that contains the code for our plugin. Since we are using Windows Scripting, we will be creating a .wsc file that will contain the code for the plugin in the next section.

The plugin description file also lets you include some documentation about the plugin. You can either type it into the box or include it in a separate file (such as an HTML page) that will be packaged with your plugin later. Our plugin is so simple that we won’t need to include extensive documentation.

In the author tab we put some information about ourselves (me, in this case). The download url is optional and should only be used if you do not want to publish your plugin on MAID, but would rather have users download it directly from your site.

Finally, in the license tab, we choose the license type and put in a copyright message. Note that MAID does not enforce the license types; they are in place merely for documentation purposes.

We are now finished entering all the required information…whew! It is time to save the .plugin file. To do this, simply click on the “File” menu and select “Save as…”. To make things easier for us, we will intentionally save the file to the folder where Meedio is expecting it. In this case, it should be:

pluginsmoduleTicTacToeTicTacToe.plugin

This path is a combination of the base directory for plugins (plugins), the plugin type (module) and the destination folder (TicTacToe) we specified for the plugin. The actual file name is not important, as long as it has the .plugin extension, but it is good practice to use the name of the plugin as the file name.

If we open the file with Internet Explorer, we see its contents. All the information we entered is there.

This concludes the first section. We have created the .plugin file which serves two main purposes: 1) it lets Meedio find and understand your plugins and 2) it lets MAID list the plugins with a fair amount of information. You can also use the Plugin Editor to update your plugin files. For example, when you make a new release, you need to increase the version number of your plugin, which you can easily do with the Plugin Editor.
Creating the skeleton code

In this section, we will create the basic skeleton for the plugin code. This includes the methods necessary for Meedio to execute the plugin. When we are finished with this section, the plugin will not actually do anything, but we will be able to test that Meedio can load it to ensure we have done everything correctly.

This step will vary greatly depending on the programming language you are using to create your plugin, but we provide downloadable skeleton code for the most popular languages in the Plugin Documentation page.

Since we will be using Windows Script Components to create the Tic Tac Toe plugin, we will need to create a .wsc file with the skeleton code. Simply run Notepad and type the following into it. (Or, just copy and paste it).


Windows Script Components are written inside an XML file with a .wsc extension. This file contains some basic information about the component and then the actual code for it.

There are a few important things to note here. First of all, for the clsid attribute inside the registration element, it is very important that you use the same value that was used for the plugin ID in the first section of this document. You can simply copy the value from the Plugin Editor and paste it there. This means that our plugin will be registered using the same identifier. If it is not, Meedio will not be able to execute it.

The contents of the implements element must be as they are shown above. This element describes the “methods” or “functions” that are exported by this component. Every Meedio plugin, regardless of programming language used must have the 4 functions: OnMessage, EditCustomProperty, GetProperty and SetProperties.

In the script element, we tell Windows Scripting that we will be using VBScript as the language for this component. It is possible to use other languages, including JavaScript, Python or even Perl, but that is beyond the scope of this tutorial and we will be using VBScript for the sake of simplicity.

That strange CDATA thing is there to allow us to write the code freely without having to worry about special characters in XML, it is highly recommended. Remember that even though this is a Meedio plugin, it is also a Windows Script Component and, as such, an XML document.

Finally, inside the script element, we write the basic code for the 4 required functions. For each one, we list the parameters and return the appropriate result.

We save the resulting file as

pluginsmoduleTicTacToeTicTacToe.wsc

which is what we specified in the Plugin Editor for the main file in the previous section.

The biggest problem with Windows Script Components is that it is not easy to check if we have made any typos in the file. The simplest way to do this is to register the component. To register it, use Windows Explorer and go to the folder where the file is saved. Once there right click on the file and choose Register. Try this now with our component.

If there are no problems with the file, you will see the message above.

If there is a mistake in the file, you will see a message similar to one shown above. The important thing to notice here is that the numbers in between square brackets are the line and column where the error is located; in this case, line 34, column 14. If you see this, you will need to go back to the file and look for any syntax errors at that location and then try to register again.

Once our component is free of mistakes, we are ready to do the first Meedio test; to ensure that the plugin can be found and loaded. This can be easily accomplished using another tool provided by Meedio called PluginTester.exe. It is located in the Meedio installation folder. Simply double click on it to execute it:

The Plugin Tester simulates what Meedio itself would do when it is looking for plugins. It scans the plugins directory and reads all the .plugin files it finds there. It performs some checks to make sure the contents of the .plugin files are valid and then shows you a list of all the plugins that it has found. The bottom part of the tool shows some interesting “behind the scenes” information that can come in handy when you are troubleshooting problems with your plugins.

If everything is in tip-top shape up to this point, the Plugin Tester should be listing our Tic Tac Toe plugin with the correct plugin ID as shown above. If the plugin is not listed, we can usually blame problems in the .plugin file. First, check the log messages shown by the Plugin Tester to look for any validation problems. If there are none, verify that the TicTacToe.plugin file is saved in the correct location and then run the Plugin Tester again.

If the plugin is listed, we can simply double click on the plugin’s name to try and load it. In this case, the Plugin Tester is doing the same thing that Meedio or the Configuration application would do when trying to load a plugin; if it works here, it will work there.

Assuming that everything went well, the Plugin Tester should look something like the picture above. The Plugin Tester has loaded the plugin, retrieved its properties and displayed the list of properties. In our case, we have not yet specified any properties for the plugin, so the list says “This plug-in has no properties”. But, we should be happy that everything is working as expected.

At this stage, we have a valid plugin that Meedio can find and load. It doesn’t do anything yet, but we will get to that in the next section.
Creating the screen file

Now that we know the basics are in order, it is time to start thinking about what our plugin will actually do.

Our Tic Tac Toe plugin will be very simple; it will just present the user with a screen where he/she can play Tic Tac Toe against the computer. The user will be able to exit, play or start a new game.

Hey! We just wrote a Use Case for our plugin: we defined what it will do. Now, we can set out to make it happen.

The first thing we said is that it will “present the user with a screen”. This is a basic requirement and Meedio provides a way for us to accomplish it, so we need to start thinking about creating this “screen”.

Meedio has a built-in language for creating screens that is based on XML and is also similar to HTML. In short, it allows us to divide the screen into areas and place widgets or controls into these areas. Once the screen is defined in what meedio appropriately calls a screen file, our plugin code can create the screen inside Meedio and manipulate these widgets.

So, where do we start? We can start with Notepad and type the whole screen from scratch or we can base ours on the .screen files of existing plugins. Alternatively we could use the Meedio Theme Designer to create the screen visually. In our case, we will do it from scratch so that you can see the whole process and we can discuss the various steps.

When you are ready, run Notepad again and type in the following (or copy and paste it):





Save this file as

pluginsmoduleTicTacToeTicTacToe.screen

This is a simple screen that has no real contents, but already includes some of the features we described in our Tic Tac Toe Use Case.

In the screen element, which is always the first one in a screen file, we specified that it should use the “main” template. The “main” template is one that is provided by most Meedio themes; it is a special kind of screen that has holes for us to include our own widgets. The idea behind using a template is that it makes it easier to create a bunch of screens that have a consistent look. The first_focus attribute tells Meedio which widget to focus when the screen is first shown. In our case, we have set it to “the-toolbar”, which is the name of a widget provided by the main template. In the default theme, “the-toolbar” refers to the menu you see on the left hand side of almost every screen.
Actions

Next, we have an actions element that includes two action sub-elements. Simply put, actions are the basic things that the user will be able to do. In our Use Case, we said that the user will be able to “play, exit or start a new game”. Aside from being able to “play”, this translates well into the actions we have listed in the screen file.

Every action has a name, which is an arbitrary way to refer to the action internally. The user of our plugin never sees this name. In addition to this, an action can have a command that triggers it. Commands are all the things listed in the “Input” tab of the configuration application; they are names that are mapped to keys or remote control buttons. In the default configuration, the BACK command is mapped to the backspace key, for example. By listing the names of these in the command attribute of an action, we are saying that the action will be executed when the user invokes the command (by pressing a key or a remote control button, for example). So, we have assigned the BACK command to the action that will close our Tic Tac Toe module and the PLAY command to the action that will start a new game; pretty logical so far.

Inside each action are one or more state elements. States help us further define what the action will do and how it will be displayed. In some cases, a single action can have multiple states, such as “Shuffle On” and “Shuffle Off”, but more often than not, each action has a single state. The state, again, has an arbitrary name. This name can be the same name as the action name. What follows the name of the state can vary greatly, but it is very common to include a caption for the state. This caption is what the user will see and will usually be translated if the user is using a different language file. So, we gave our two states some obvious captions.

In the case of our close state, we added a strange “standard” attribute. This is a simple shortcut that means our plugin will have to do less work. There are a number of “standard” things a state can do and one of them is to close the current module. We have specified the standard state “module.close”. It just means that when this action executes, Meedio will close the module, effectively exiting our Tic Tac Toe plugin. There is no standard state for a new Tic Tac Toe game, so we will need to implement that one ourseleves inside the plugin code.

Next in line is an action-list element. This element lets us create a named, ordered list of the actions we have specified in the screen file. It just so happens that the main template we are using takes the action list called menu-actions and automatically places them in the left hand menu. It all serves to create less work for us.

An action list has a name and a comma-separated list of action names to include in the list. Typically, widgets that display action lists, display them in the same order they are listed here; which means that the left hand menu will have a “button” with the caption “Close” and another with the caption “New game” below the first. This is pretty much what we want.

Let’s ignore the rest of the screen file and test the screen.
Testing the screen

Once the skeleton for the screen file has been saved, we can actually test it to make sure it is working properly. It won’t be a very exciting test because our screen does not yet have any real content, but we can at least see that it works. It also serves to show you another tool we provide (and use ourselves) to make things easier.

To test the screen file, run the Meedio Configuration Application which is also located in the installation directory.

Go to the Menu tab and select the first group module, which is usually the second one called “Meedio” if you have a standard installation.
Click the Add button and select the Screen Tester Module from the list of possible modules. Do not select Tic Tac Toe yet.
Select the Screen Tester Module you just added and then go to the Module Properties tab on the right hand side.
For the Screen property, select the TicTacToe.screen file we saved earlier.

The settings should look like the picture above. Now, click the Launch button.

After Meedio starts, go to the Screen Tester Module we created and select it. If you are using the default theme, you will see a screen similar to the picture above. Coincidentally, it is recommended that you use the default theme when you are developing screens to ensure that they run well in a default configuration.

In the screen we see our two actions manifested in the left hand menu. We also see that pressing the Close button actually closes the module. The right hand side of the screen is painfully empty, but we’ll get to that next.

When you are creating screens, it is always a good idea to use the screen tester module to see how they will look.
Creating some resources

Before we continue on with the screen, we are going to create a couple of things that we’ll need later on. If we’re going to play Tic Tac Toe, we will need some images to represent the X’s and O’s. You can use your favorite tool to do this, and Meedio works with a variety of image formats, but we will be using PNG’s because they offer a transparent layer.

Because I have no artistic talent whatsoever, I decided to use two shapes that my photo editor has in its clip art library for the X’s and O’s. I saved these in a new directory called images under the plugin’s directory. I used the file names ttt-o.png and ttt-x.png for them. The “ttt” stands for Tic Tac Toe. I made the images square at 175 x 175 pixels, which means they should scale well. Although Meedio will scale the images automatically, we need to make sure they are not so small that they will look awful at higher resolutions.

Now, we need a way to refer to these images. Remember that when your plugin is installed on another user’s computer, you won’t know where it has been installed and therefore you will not be able to refer to them by using file names. Meedio provides this ability in what it calls resource files.

Resource files are, again, XML files that allow you to assign names and properties to resources that will be used in screen files, such as images, colors, fonts and various other things. The format of a resource file is very simple and the files have the .resources extension.

Fire up Notepad again and enter this into it:

Save this file as

pluginsmoduleTicTacToeTicTacToe.resources

This file is fairly simple, it always begins with the resources element. Inside, there can be a variety of other elements that define different reource types, one of which is images. Inside the images element, we have created two images. Here, the name of the element, such as “ttt-x-image” is the name we will use to refer to the image from within our screen file and our plugin code. The source attribute tells Meedio where the actual file is, relative to the location of the resource file. This solves the problem of not knowing where the plugin is installed, because wherever it is installed, our images will be in a folder called “images” which will always be located where the resource file is.

Now that we have our images, we are ready to proceed.
Creating the Tic Tac Toe board

We are ready to go back to our screen file and add the playing area. But, before we do that, we will make one additional change to it to include the resource file we created in the previous step.

We simply edit the screen element of the screen file and include a reference to the resources file as shown above. We just add the resources attribute and the name of the resource file; we don’t need the path to it or the extension as Meedio will make the correct assumptions about them.




When we first talked about the screen file, we mentioned that it is using a template file which provides “holes” for us to put our widgets. In the snippet above, you see the placeholder element. This element is used to tell Meedio to put whatever is inside it into the “hole”, or “place holder” called “CONTENT”. The main template we are using defines a place holder with the name “CONTENT” which is the right hand side of the screen. This allows us to create screens that don’t have much position information; they simply put their content into the areas defined by the template. So far, this area has been empty, but that is where our playing area will be.

The playing area is nothing more than a 3×3 grid where the X’s and O’s will go. Fortunately, Meedio includes a widget that can approximate this concept very closely. The menu widget does basically that. The only problem is that the menu widget also does a lot of other things, so we have to tweak it to do exactly what we want.

So, we will modify our screen file as follows:








Above, I am only showing the relevant snippet of the screen file; you will be able to see the whole file later on. If you want, you can save the file again and run the screen tester module again; you will see that things are starting to take shape (aside from my horrible choice of images).

If you do, you will see that our screen looks something like the picture above. The “tic tac toe” title is not magic, I went in and edited the caption for the Screen Tester Module to make it look a bit more like the real thing.

But wait!!! It looks like someone has already played a game and we haven’t written a single line of code yet. This is a little trick I used in the screen file above to see what it would look like. It corresponds to the 9 item elements I added.

Before we get too far ahead of ourselves, let’s look at the new things in the screen file.

Inside the placeholder element, there is a cells element and a cell element inside that. These serve to divide the screen area into manageable pieces that can contain widgets. For more information about this, see Screen Files: Layout. In our case, we are going to use the whole area on the right hand side for the board, so we don’t need to create cells. However, Meedio dictates that all widgets must be inside a cell element, and all cell elements must be inside a cells element, so we create one of each to satisfy this requirement.

Inside the cell, we have placed a menu widget. The menu widget is the most common of them all, as it can serve a lot of different purposes. Meedio does not have the concept of single buttons; since buttons are typically arranged in groups, Meedio uses menus to create groups of buttons. Menus are also used to display lists of things and grids with thumbnails. The Menu widget is very powerful.

To begin, we gave the menu widget the name “board”. This will allow our plugin code to reference the menu and manipulate it at run-time. Only controls that you want to use from within your code need to have a name, and their names must be unique in the entire screen file (and any templates referenced by the screen).

Typically, widgets include all of their properties within their main element, but the menu is a bit different. The menu widget includes all of its properties within a mode element. Each mode has a name of its own. This allows a single menu control to take on different “shapes”. For example, one mode could be a thumbnail display and another could be a list display. They both contain the same data, but they display it differently. By pre-configuring modes, the plugin can easily switch between them at run-time in response to the user. In our case, we will only be using a single 3 x 3 mode, so we created a default mode.

Since each mode in a menu control can have a large number of properties, Meedio provides a number of preset modes in the theme’s resource file. So, when we create a new mode for our menu widgets, we can base it on a preset mode and only change, or override a few properties. In our case, you see that we have used the “simple-thumbnail-mode” preset. You can find that preset in the file default.resources of the default theme.

Following the preset, we begin to set properties specific to our menu.


We begin with col_count which sets the number of columns displayed to “3”. Then, we use col_space to define a 10 pixel space between the columns. Next, we use a fraction to define the size of each row in the menu with row_size. Menu widgets have a fixed number of columns, so they cannot scroll to the right, but they can have any number of rows. So, we use “1/3” to tell the widget that each row should be 1/3 of the total height of the widget. In effect, this means that our menu will only show 3 rows at a time; if it had more than that, the user would have to scroll to see more rows. Then, we use row_space to define a 10 pixel space between each row, just like we did for columns. Since we know that our menu will have only 3 rows, we set scroll_size to 0, which serves to hide any scroll bars or arrows. Finally, we set the image_format that will be used to display images in this menu. “fit-img-format” is the name of an image format resource that is already defined in the default resource file for the theme; it basically says that images will fit their bounding box, retain their original aspect ratio, can be enlarged and will be aligned to the center both vertically and horizontally.





After the mode element, we created 9 test “items” for the menu. Every menu widget holds any number of items. The items are displayed from left to right and top to bottom according to the number of columns in the menu. Each item contains an arbitrary list of names and values. In technical terms, an item is an Associative Array. In this case, each item will contain the name “image”, and for each item, the value of “image” will be what we specified in the screen file. In the previous section we create a resource file to give the images names; those are the names that we using here, so that we don’t have know where the actual files are. So, “ttt-x-image” is the name of an image resource that is located in the file “imagesttt-x.png”.

Even though each item can have any number of names and values, there are a couple that are “magical” and are treated in a different way by the menu widget. These are mainly “image” and “caption”. By default, the menu widget will display the image referenced by each item’s “image” value and the text contained in the “caption” value. Of course, this can be changed, and there are ways to configure a menu widget to display several images and captions for each item, but that is beyond the scope of this tutorial. All we need is an image in each item. When we start writing the plugin code, you will see that we will use the “image” value to see if a cell is occupied and by what player it is occupied.

In reality, we will remove the item elements from the screen file and add them dynamically at run time.
Writing the code

Now, we are finally ready to work on the actual code for the plugin. In this section, I will only show relevant snippets of the wsc file instead of the entire file every time.
Properties

Let’s begin by talking about the 4 functions that each plugin must implement. Of the 4, 3 have to do with properties. Properties are the means by which a user configures your plugin. Meedio provides a standard user interface that allows users to configure any plugin. In cases where the standard interface is not enough, you can use custom properties and your plugin can create custom property pages for them.

The first thing that Meedio (or the configuration application)