Appendix B: Advanced Architecture and DMB Customizations
First Published: August 20, 2012
This module is intended for administrators and provides more in-depth information about the Dynamic Menu Board (DMB) architecture and how to deploy customizations to the default gadget file to support new or modified menu layouts from the default layouts and themes provided by Cisco StadiumVision Director.
It includes the following topics:
•Advanced DMB Application Architecture
•Workflow Summary
•How to Deploy Customized Gadgets
•What to Do Next
Advanced DMB Application Architecture
Figure 1 shows the three primary architectural components of the DMB application:
•Custom App GAR
•Gadget
•Portlet
Figure 1 DMB Application Components
Custom App GAR
The DMB installation supports a single Gadget Archive (GAR) file named "dynamenu.gar."
The GAR file is a simple Java jar archive file that contains the XML, gadget (SWF), and image files, as well as other information that Cisco StadiumVision Director server needs to deploy the menu board and make it available on the Digital Media Player (DMP).
The GAR file can be exported and imported into Cisco StadiumVision Director to install updates for customizations to the default menu boards. The dyanmenu.gar files consists of the following files and folders:
•GADGET-INF—Folder contains the gadget.xml file.
•delithumb.jpg
•dynamicmenu_1920x1080_2.jpg
•dynamicmenu_1920x1080_2.swf
•puzzle.jpg
Note The META-INF folder contains the manifest.mf file which is an internal Java file used by the Jar utility. This folder and file can be ignored.
XML File
The gadget.xml file is an important required file, and defines the rest of what also needs to be in the GAR file. For example, the files delithumb.jpg, puzzle.jpg, and the corresponding gadgets with their icons depend on what is specified in the gadget.xml file.
The XML file must be called gadget.xml and must be in the GADGET-INF folder. There can be multiple elements of <gadget> representing multiple gadgets in the file.
The following example shows the XML elements for the DMB application in the gadget.xml file in Cisco StadiumVision Director Release 3.0:
?xml version="1.0" encoding="UTF-8"?>
<custom-app name="DynamicMenu" description="Menu Boards" thumbnail="puzzle.jpg" >
<portletUrl>http://${sne_registry.portletUrl}/sv_menu/data/dynamicMenu</portletUrl>
<mcastChannel>com.cisco.sv.gadget.DynamicMenu</mcastChannel>
<gadget name="dynamicmenu_1920x1080_2.swf" filename="dynamicmenu_1920x1080_2.swf"
thumbnail="dynamicmenu_1920x1080_2.jpg"/>
Gadget
The gadget is an Adobe Shockwave Flash (SWF) file that runs in the DMP, and an event script in Cisco StadiumVision Director controls the gadget and defines what areas of the display that it uses. The gadget listens for updates from Cisco StadiumVision Director that is defined in the XML file, and it makes calls to the portlet to retrieve data.
The DMB application in the portlet uses the gadget file to process the menu object, which determines the formatting characteristics of the graphic for a particular menu layout and how the different areas of the theme are processed and displayed by the DMP. For example, the default SWF file determines the overall size of the menu (1920x1080), as well as the fonts, sizes, and position of headers and items. This level of formatting is not configurable within the DMB application itself, so you cannot modify those characteristics directly—they are predefined by the SWF file. For more information about the default themes, see the "Appendix A: DMB Default Menu Theme Reference".
If you want to change the default menu theme definitions in Cisco StadiumVision Director, you can create a customized gadget (SWF) and reinstall it in Cisco StadiumVision Director. In Cisco StadiumVision Director Release 2.4, only a single SWF file is supported.
Note Customizing the gadget requires expertise in Flash coding, which is not described in this module. For help in customizing a gadget, contact your Cisco Systems representative.
Portlet
The portlet includes the DMB application, and it supports requests from the gadget. The portlet can look up data from a database in Cisco StadiumVision Director.
Workflow Summary
To create and deploy customized gadgets to support new menu themes, complete the following tasks:
1. Design the new menu attributes with your site team.
Tip Refer to the "Appendix A: DMB Default Menu Theme Reference" as a starting point to modify the look and feel of the menus for your venue.
2. Export the GAR file from Cisco StadiumVision Director.
3. Create a new gadget SWF that defines the layout, menu size, fonts, sizes, and position of headers and items.
Caution
Be sure to save the modified gadget with a new file name. Do
not use the "dynamicmenu_1920x1080_2.swf" to prevent overwriting during upgrades.
4. Modify the gadget.xml file to add the information about the new gadget element and modify the thumbnail file to be associated with the gadget as desired.
Tip You can use different JPG icons for each gadget. This will help you quickly differentiate menu custom_app_instances asssociated with different gadgets in the Control Panel.
5. Re-package the GAR file using a JAR or ZIP utility to add the new gadget file, any new thumbnails, and the modified gadget.xml file.
Each time you upload a GAR file, it defines the full set of gadgets available in Cisco StadiumVision Director. If you want the original SWF gadget and your new customized gadget, put both of them in your new dynamenu.gar file.
6. Import the modified GAR file in Control Panel > Setup > Dynamic Menu Boards.
How to Deploy Customized Gadgets
This section includes the following tasks:
•Exporting the GAR File (required)
•Modifying the Gadget XML File (required)
•Repackaging and Importing the GAR File (required)
•What to Do Next (required)
Exporting the GAR File
To export the GAR file, complete the following steps:
Step 1 Log into Cisco StadiumVision Director as an administrator.
Step 2 From your browser, go to the following URL, where ip-address is the IP address of your Cisco StadiumVision Director server:
http://ip-address:9090/download/dynamenu.gar
Step 3 In the Opening dynamenu.gar dialog box, choose the Open with or Save File options specifying your application information as applicable. Figure 2 shows how to specify opening the dynamenu.gar using the 7-Zip application.
Figure 2 Opening dynamenu.gar Dialog Box
Step 4 Click Ok.
Step 5 After you have opened or saved the dynamenu.gar file, extract its contents to your local drive.
Modifying the Gadget XML File
This section describes the guidelines and how to modify the gadget XML file to support customizations in Cisco StadiumVision Director.
Guidelines
Before you modify the gadget XML file, consider the following requirements and guidelines:
•Do not modify the following areas of the "custom-app" element:
–name= attribute
–portletURL
–mcastChannel
•You can increment the "version" element to help confirm that the customized GAR version has been uploaded to Cisco StadiumVision Director.
From the Control Panel, you can go to Setup > Dynamic Menu Boards. The custom application instances have an "i" button to display information about the application (Figure 3). If you click that button, the metadata associated with the custom application instance, including the version mumber is displayed.
Figure 3 Custom Application Instance Information Button
Procedure
To modify the gadget XML file, complete the following steps:
Step 1 Go to the GADGET-INF folder.
Tip To protect the original version of the gadget.xml file, make a copy of it and save it to another location in case you want to back out any changes.
Step 2 Open the gadget .xml file and locate the default "gadget" element.
The following example shows the XML elements for the DMB application in the gadget.xml file in Cisco StadiumVision Director Release 3.0:
?xml version="1.0" encoding="UTF-8"?>
<custom-app name="DynamicMenu" description="Menu Boards" thumbnail="puzzle.jpg" >
<portletUrl>http://${sne_registry.portletUrl}/sv_menu/data/dynamicMenu</portletUrl>
<mcastChannel>com.cisco.sv.gadget.DynamicMenu</mcastChannel>
<gadget name="dynamicmenu_1920x1080_2.swf" filename="dynamicmenu_1920x1080_2.swf"
thumbnail="dynamicmenu_1920x1080_2.jpg"/>
Step 3 Copy the <gadget /> line and paste it below the current line:
?xml version="1.0" encoding="UTF-8"?>
<custom-app name="DynamicMenu" description="Menu Boards" thumbnail="puzzle.jpg" >
<portletUrl>http://${sne_registry.portletUrl}/sv_menu/data/dynamicMenu</portletUrl>
<mcastChannel>com.cisco.sv.gadget.DynamicMenu</mcastChannel>
<gadget name="dynamicmenu_1920x1080_2.swf" filename="dynamicmenu_1920x1080_2.swf"
thumbnail="dynamicmenu_1920x1080_2.jpg"/
<gadget name="MY_NEW_GADGET.swf" filename="MY_NEW_GADGET.swf"
thumbnail="dynamicmenu_1920x1080_2.jpg"/>
Step 4 Modify the name= and filename= attributes with the name of the new gadget.
Note The thumbnail= attribute specifies the picture that appears in the Control Panel for the DMB custom application instance for a menu theme published with this gadget.
Step 5 Save the gadget.xml file.
Repackaging and Importing the GAR File
To repackage and import the GAR file, complete the following steps:
Step 1 Open the dynamenu.gar file and replace and import the following files to it:
•gadget.xml in the GADGET-INF folder.
•New .swf gadget file.
Step 2 Log into Cisco StadiumVision Director as an administrator.
Step 3 From the main menu, click Control Panel.
Step 4 Go to Setup > Dynamic Menu Boards.
Step 5 Click Import Application (Figure 4).
Figure 4 Dynamic Menu Boards Import Application
Step 6 In the Select file to upload dialog box, locate the modified dyanmenu.gar file on your local system and click Open.
What to Do Next
1. After you have installed a new gadget, the newly defined layouts in the gadget also must be defined in the DMB application by an administrator or concessionaire. You will need to go to the Layouts screen to specify the layout names and numbers of columns, headers, and items, and this information must match what is defined in the gadget file as shown in Figure 5.
Figure 5 New Layout Creation Workflow
2. If new graphics are going to be used for the background, headers, or items for new menu layouts defined in the new gadget, be sure to upload them into the Image Gallery. For more information, see the "Working with Images in the DMB Application" module.
3. Create new menu themes and publish them in Cisco StadiumVision Director. For more information, see the "Creating and Updating Menu Boards" module.