• API Home
• Custom Button Tutorial
• WaterWorld API Example

FreeCause Custom Button Tutorial

This document describes how clients and organizations can create custom, dynamic, buttons

Table of Contents

Introduction What is a Custom Button? I want to make buttons, what do I need? How can I quickly test a Custom Button? Hello FreeCause! Hello World! Hello Menu! Hello Attributes! Hello Commands! Hello INCLUDE! Code Examples Multiple layer dropdown RSS Feeds API Popup Simple

XML Tags toolbaritem toolbarbutton menupopup menu menuitem menuseparator Common Topics Escaping Special Characters Toolbar Images

Introduction

What is a Custom Button?

A custom button is a snippet of xml that when read by a FreeCause Toolbar transforms into a normal toolbar button. Custom Buttons can be dynamic, static, and can even call Javascript commands that interact with native functions of the toolbar. Custom Buttons can be defined either separately, or as a group, it all depends on how you want the buttons to be displayed.

I want to make buttons, what do I need?

1	Not much time
2	A text editor. At FreeCause we enjoy supporting open source technologies such as emacs, and for the Windows goonies, Notepad++
3	A browser, preferably Firefox

How can I quickly test a Custom Button?

You're in luck [if you are using firefox!], the site at the bottom of this section allows you to test your new component within your own toolbar. Copy and paste the new button code into the text area on this page. Before clicking add to to toolbar, be sure that you have some gray space to work with (no chevron), so that you can see your new feature quickly. You can do this by minimizing the search, radio, and ticker all the way. A simpler solution is to go into the layout manager under the logo and delete some components. Once you have some gray space, hit add to toolbar, and you should see your new button at the right most point of your toolbar. If you're button is not formatted correctly, then nothing will appear.

There is a disclaimer though, by inputting invalid xml into your toolbar, you are assuming a small amount of risk. If you have a thousand bookmarks, I would suggest opening firefox with a new profile (cmd firefox -p). If somehow you manage to really destroy your toolbar, don't worry, just uninstall and reinstall.

You can see how the sandbox works by copying and pasting the above RSS example into the sandbox [in firefox] to see how it should work.

Sandbox Location: http://www.freecause.com/tools/sandbox.html (FIREFOX ONLY)

Hello FreeCause!

Hello World!

Lets make our first button. Open up your handy dandy text editor, and open a new file. If you don't know anything about XML, don't worry, it's pretty simple. Each component in the toolbar is wrapped in a base tag called a toolbaritem. This toolbaritem can take several parameters but for the time being, we really don't care about any of them. So type the following.

<toolbaritem>

</toolbaritem>
		

Toolbaritem is nothing more than a shell, next comes what you see in the toolbar, the toolbarbutton tag. The toolbarbutton tag also takes several attributes, but for now, all you care about is how do I make this display Hello World! in the toolbar. The text label in the toolbar is defined by no other than the "label" attribute. So in between the toolbaritem tags, write the following.

<toolbaritem>
	<toolbarbutton label="Hello World!" ></toolbarbutton>
</toolbaritem>
		

Now open firefox, navigate to the sandbox url, copy and paste the xml snippet into the sandbox and you will see Hello World on the farthest right. Now lets add a menu.

Hello Menu!

Using the bare bones for our attributes, lets start making a menu. Using the Hello World snippet, we need to now tell the toolbar that it is a menu. So add the type attribute.

<toolbaritem>
	<toolbarbutton label="Hello World!" type="menu" ></toolbarbutton>

</toolbaritem>
		

With that, we now need to define our menu. The format for menus starts with a menupopup tag, which basically does exactly what it is named. When you click on the button a menu pops up. Inside of the menupopup, are menuitems, which allow you to define different rows in a menupopup.

<toolbaritem>
	<toolbarbutton label="Hello World!" type="menu">
		<menupopup>
			<menuitem label="Hello" />

			<menuitem label="Menu!" />
			<menuitem label="Thanks" />
		</menupopup>
	</toolbarbutton>
</toolbaritem>
		

Once again, open up firefox and check out your new feature in the toolbar. Cool, easy, but still not too useful. Lets say Hello Attributes!

Hello Attributes!

Attributes in the xml add the finishing touches to the component. First, we need to add what type of component it is, so in the toolbaritem tag, add the component attribute with dropdown as the value. To make the toolbar show up in the layout manager we need to add the preview_text attribute to toolbarbutton. Also, to make it look good, we really should add an image. The only caveat for the image is that it has to be a PNG (read the Toolbar Images in Common Topics for more information), and it should be about 16x16. Transparency is supported, so try to use transparent images, they always look much better. So lets add these attributes.

<toolbaritem>
	<toolbarbutton label="Hello World!" preview_text="Hello World" image="http://images.freecause.com/default/home.png" type="menu">
		<menupopup>
			<menuitem label="Hello" />

			<menuitem label="Menu!" />
			<menuitem label="Thanks" />
		</menupopup>
	</toolbarbutton>
</toolbaritem>
		

Once again, add it in the sandbox, you'll see it with your image and if you go to the layout manager you'll be able to move it up and down there. Now...Hello Commands!

Hello Commands!

Attributes and tags can only go so far, the real power of the toolbar is reserved for the commands that it can issue. Starting off, lets make the toolbar useful, by binding links to the menuitems.

<toolbaritem>
	<toolbarbutton label="Hello World!" preview_text="Hello World" image="http://images.freecause.com/default/home.png" type="menu">
		<menupopup>
			<menuitem label="Hello" cmd="redirect" url="http://www.freecause.com" />

			<menuitem label="Menu!" cmd="redirect" url="http://www.freecause.com" />
			<menuitem label="Thanks" cmd="redirect" url="http://www.freecause.com" />
		</menupopup>
	</toolbarbutton>
</toolbaritem>
		

So the oncommand function is calling the redirect function to redirect the current page to that specificed in the url parameter.

Hello INCLUDE!

Leaving the menus behind, the INCLUDE component allows for your toolbar component to be completely dynamic, allowing it to pull it's schema from a remote location. The tag below pulls the xml from the url and then renders like a normal button

<toolbaritem component="include" url="http://www.freecause.com/test/ffapi/api.php?username=Newbie&amp;session_key=1"/>

Common problems with INCLUDES remote URL integration

• NO XML namespace
• Incorrect Content-Type returned from the remote file
• Unescaped special characters

The following shows an example of what the above url returns

<toolbar xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
	<toolbaritem component="button">
		<toolbarbutton label="Welcome Newbie"  cmd="redirect" url="{$login}?toolid=%toolid&amp;userid=%userid&amp;key=%userkey"/>
	</toolbaritem>
</toolbar>
	

Copy and paste this into the sandbox (note to convert the & to a
&). You should see something that says Welcome Newbie. Also,
feel free to copy and paste the url into the browser to see the output.

Code Examples

Multiple layer dropdown

<toolbaritem component="dropdown">
	<toolbarbutton type="menu" label="Shop for Your Cause" image="http://MY_IMAGE_URL.png" preview_text="Shop Button">
		<menupopup>
			<menu class="menu-iconic" label="Apparel and Accessories">
				<menupopup>
					<menu class="menu-iconic" label="Clothing">
						<menupopup>
						<menuitem label="Amazon" cmd="redirect" url="http://www.amazon.com" /> 
						<menuitem label="Boden" cmd="redirect" url="http://www.boden.com" /> 
						<menuitem label="Buckle"cmd="redirect" url="http://www.buckle.com" />
						<menuitem label="Champion" cmd="redirect" url="http://www.champion.com" /> 
						<menuitem label="Cutter and Buck" cmd="redirect" url="http://www.cutterandbuck.com" /> 
						<menuitem label="Forzieri" cmd="redirect" url="http://www.forzieri.com" />
						</menupopup>
					</menu>
					<menu class="menu-iconic" label="Shoes and Accessories">
						<menupopup>
							<menuitem label="Florsheim.com" cmd="redirect" url="http://www.florsheim.com" />
							<menuitem label="ROOTS Direct" cmd="redirect" url="http://www.rootsdirect.com" /> 
						</menupopup>
					</menu>
				</menupopup>
			</menu>
		</menupopup>  
	</toolbarbutton>
</toolbaritem>	
		

RSS feeds

<toolbaritem component="rss" collapsed="false">
	<toolbarbutton image="http://images.freecause.com/default/feed.png" label="News " type="menu" collapsed="false">
		<menupopup id="RSS_List[object ChromeWindow]">
			<menu class="menu-iconic"
			image="http://images.freecause.com/default/feed.png"
			label="CNN.com - World"
			value="http://rss.cnn.com/rss/cnn_world.rss">
				<menupopup/>
			</menu>
			<menu class="menu-iconic"
			image="http://images.freecause.com/default/feed.png"
			label="USATODAY.com News - Top Stories"
			value="http://rssfeeds.usatoday.com/usatoday-NewsTopStories">
				<menupopup/>

			</menu>
			<menu class="menu-iconic" 
			image="http://images.freecause.com/default/feed.png"
			label="NPR Topics: Health And Science"
			value="http://www.npr.org/rss/rss.php?id=1007">
				<menupopup/>
			</menu>
			<menu class="menu-iconic" 
			image="http://images.freecause.com/default/feed.png"
			label="Yahoo! Sports - Tampa Bay Bucs"
			value="http://sports.yahoo.com/nfl/teams/tam/rss.xml">
				<menupopup/>

			</menu>
		</menupopup>
	</toolbarbutton>
</toolbaritem>

API Popup Simple (Great for Flash Games)

<toolbaritem component="button">
	<toolbarbutton label="DTD"  cmd="show-popup' url="http://www.kongregate.com/games/preecep/desktop-tower-defense-1-5/flashframe?channel_id=1190106850.44339" h="500" w="700" position="top-right"/>
</toolbaritem>

XML Tags

toolbaritem

Base Toolbar Envelope. All buttons are contained within this tag.

• cid: [string] Locally unique identifier
• component: [button | dropdown | rss] Defines the toolbaritem type
• preview_text: [string] Text label in the Layout Manager
• expire: [int (minutes)] Minutes till component refreshes (optional)
• url: [string] Url for includes components (optional)

toolbarbutton

Actual rendered button in the toolbar

• type:
  [menu|menu-button] Determines whether the button simply fires a
  dropdown menu, or if the button can be clicked, and the dropdown is
  activated only if the mouse is over the menu arrow
• label: [string] Button text label
• image: [PNG url] Url for remote PNG image
• cmd: [string] calls toolbar methods
• imageheight: [int px] sets height of icon image
• imagewidth: [int px] sets width of icon image
• static: [true|false] Button can not be moved

menupopup

Envelope for menu dropdowns

menu

Menu defines a menu within a dropdown menu.

• class: [menuitem-iconic] if set, allows for images in the menu items
• label: [string] Button text label
• image: [PNG url] Url for remote PNG image
• cmd: [string] calls toolbar methods
• imageheight: [int px] sets height of icon image
• imagewidth: [int px] sets width of icon image

menuitem

Menuitem is a row within a dropdown menu. All the same attributes as menu

menuseparator

Defines a horizontal separator within a dropdown menu

Common Topics

Escaping Special Characters

The most common problem with XML will be if you have improper xml format. Check if you have any unescaped special characters in your xml. such
as &. <, >

Toolbar Images

In order to be compatibile with both IE and Firefox toolbars, all linked images should be in the PNG format. Our toolbar converts the PNGs alpha tranpsarency and creates a 32Bit bmp from the image for IE, making a crisp, transparent image in IE.