Creating a Custom Renderer (Media)

Updated Jan. 22, 2008: This tutorial is not yet compatible with the Flex Builder 3 Public Beta 3. If you’ve been working with Flex Builder 3 through its public beta releases, these instructions should still be pretty applicable.

Before Starting

Before attempting to create your own performable content, make sure that you download the source code for visp. You’ll need it in order to compile your custom content.

Overview

Individual pieces of content or media in visp are called renderers.

Creating your own renderer for visp is very straight forward once you get the basic setup down. The general idea is that you’ll create a Flex Component — specifically one that extends a visp class called AbstractRendererModule which lives in visp’s com.visp.render.module package. This class extends Flex’s core Module class, which means you’re actually creating a Module.

You’ll also want to create an 80px by 80px image (JPG, PNG, GIF) to represent your custom renderer in the Media Panel within visp since this iconic representation is used to activate your renderer.

Creating Your Project in Flex Builder

  1. Create a new Flex Project (Application Type should be Web Application).
  2. Name it whatever you like. Create it wherever you like. For the sake of this demo, we’ll say that the project is called SampleRenderer.
  3. Click Next until you reach the Additional source folders… dialog screen.
  4. In the area that says Additional folders outside the main source folder:, click Add Folder… and locate the flex_src folder within the main visp project folder on your hard drive. Note: you don’t have to have visp set up as a project in Flex Builder. Simply having downloaded the source code zip file and extracting it somewhere on your hard drive is enough.
  5. In the field labeled Main application file, change the value from SampleRenderer.mxml to SampleRendererModule.mxml. At a glance, this will help clarify that this is actually a Module.
  6. Click Finish.
  7. Create a folder called assets in the root of your project’s folder and dump that JPG/PNG/GIF icon file inside. For the sake of this tutorial, we’ll say it’s called icon.jpg.

Extending AbstractRendererModule

Flex Builder will have created your project’s folder and created a SampleRendererModule.mxml file in your src folder. This MXML component is extending Application which is not what we want. We actually need to extend visp’s AbstractRendererModule.

For everyone’s convenience, I have created a template that you can actually copy and paste. You’ll find it in this folder in the visp project’s root:

/support/templates/RendererModuleTemplate.mxml

You can literally copy its contents and paste it into your SampleRenderer.mxml source (overwriting the original code that Flex Builder generated). The template file is commented so that you can fill it in with four steps. For now, however, we need create the base for the actual class that will act as your renderer’s source code — the piece that handles the visual output.

Creating Your Renderer

  1. Create a new class in your project and call it SimpleRenderer. It should extend the core flash.display.Sprite class (in the Superclass field). In the Interfaces area, you’ll want to add the IRenderable interface in the com.visp.render package. Lastly, make sure you check the Generate constructor from superclass option.
  2. Click Finish

You’ll see that your class has been created with quite a few visp-specific functions. I go over the renderer flow in another tutorial (see: Order of Code Execution in the Render Flow).

Completing your Renderer’s Module

Now we need to head back to the SampleRendererModule.mxml file and finish up the required source code to make your renderer loadable and compilable. Now it’s time to follow the four steps outlined in the comments of that file. Once you’ve done that, you’re actually ready to compile. Whew.

Compiling your Renderer

Before doing anything, we’ll want to get rid of the unnecessary files that Flex Builder creates by default in your project.

  1. Right-click / Ctrl-click on your project’s root folder and choose Properties
  2. Choose the Flex Compiler option in the list on the left.
  3. Uncheck the Generate HTML wrapper file option.
  4. Click OK to close the Properties window.
  5. Flex Builder will warn you that it will delete all HTML template files. Just click OK.
  6. You’ll still have some residual HTML, Javascript, and SWF files in your bin folder. The best thing to do is just delete everything in that folder.

Now we need to force Flex Builder to compile your module. Do something that alters your SampleRendererModule.mxml file (like add some spaces somewhere and delete them) and then save your file. This will force a compile of the SWF which is your new custom renderer Module.

This version of your renderer Module is actually a debug version, which is very useful when trying to pinpoint errors during your development. Even more helpful is having visp set up as an actual project in Flex Builder so that you can just copy your renderer Module SWF into this “dev” version of visp and run the whole system in debug mode.

When it’s time for you to compile a “production” version (or one that you’ll use during actual performances), you’ll need to follow these steps:

  1. Right-click / Ctrl-click on your project and choose Export….
  2. Choose Flex > Export Release Version. Click Next.
  3. On the next screen, you should be able to just leave everything as is, making sure that your renderer’s project and SampleRendererModule.mxml file are chosen. Click Finish.

Flex Builder will have created a bin-release folder which contains the non-debug version of your renderer Module SWF. It may have also copied visp’s GlobalPanelStyles.css file; you can ignore / delete that file.

Where Your Renderer Goes

Your compiled SWF needs to be placed in the visp application folder’s media folder. It is recommended that you read more about this topic in the Folder Hierarchy tutorial.

Demo Renderers

Visp doesn’t ship with any default renderers in its media folder at this point in time. However, there are two demonstration renderers to play with, and you can find them on the Download page.