Viral Installer How-To at Widgetbox

Getting Started

The Viral Installer consists of code that allows users to customize and grab your widget from a non-Widgetbox site.

The code contains two key sections:

A hidden form that includes all of the configurable widget values you defined when registering your widget on Widgetbox.
Javascript that displays a Get Widget link. When a user clicks Get Widget, the same Javascript starts the widget installation process using any values you may have provided to the hidden form.

A Step-by-Step Example

How do you get the Viral Installer code for your widget? Let’s walk through a simple example.

Create a page on a non-Widgetbox website that will allow users to customize and grab your widget. Note the page’s URL. For our example, let’s assume the URL is "http://www.your-site.com/viral-installer-example.html".
On Widgetbox.com, create a new hosted widget with a single configuration parameter called RemoteParam1. Of course, you can have multiple config parameters (i.e. RemoteParam2 … RemoteParamN) as necessary. We’ll just keep it simple for now.

On the Parameters screen:

a) Ensure the Display Name and Name for your parameter are called RemoteParam1. Change the parameter type to "Hidden".
b) Click the wrench icon associated with RemoteParam1. Provide a Default Value of "Text to Support Widget Preview". This value will be used to support the widget preview users see in the Widgetbox Gallery.
c) Check the "Use remote configuration" checkbox and enter the URL to the page you identified in step 1.

Note: You could click the Get the Viral Installer link to get the Viral Installer at this point. But don’t for now - we’ll come back to it later.

Accept the default settings on the Preview screen.
Finish registering your widget on the Gallery Entry screen and make sure you assign a Permalink ID. For now, don’t submit the widget for consideration to the Widgetbox Gallery. We’ve got a little more work to do

Viral Installer Example - Gallery Entry. Click to Enlarge.

Visit My Widgets > Developed Widgets and click your widgets name. You’ll notice your widget’s home page is a little different.

a) Instead of seeing the Widget Settings panel, users are instructed to visit your site to customize and get your widget.
b) The Get Widget button is purple instead of green. This lets users that the process of customizing and grabbing the widget will occur on your site.

Go back to My Widgets > Developed Widgets. Click the link called Get Installer associated with your widget.

Copy the Viral Installer code that appears. It’ll look something like this:

<!-- Developer:  you can configure your widget's values via Javascript.
 
    Learn more at http://docs.widgetbox.com/developers/viral-installer/ –>

    <form id="viral_installer_example_GetWidgetForm" style="display:none;">

    <input type="hidden" name="appInstance.instanceName" value=""/>

    <input type="hidden" name="appInstance.width" value=""/>

    <input type="hidden" name="appInstance.height" value=""/>

    <input type="hidden" name="RemoteParam1" value=""/>

    </form>

    <script src=’http://www.widgetbox.com/get_widget_btn.jsp?sourceId=<Unique ID Value>&ns=viral_installer_example’></script>

Let’s explain the values the hidden field values.

appInstance.instanceName - The "friendly name" a user can assign to a widget.

appInstance.width - The width of the widget.

appInstance.height - The height of the widget.

Note: If no values are provided for these three fields, the widget will be created using values associated with the widget’s preview settings.

RemoteParam1 - The value that maps to ${config.RemoteParam1}

Note: If no value is provided for this field, the default value (if it exists) will be used.

Put the Viral Installer code onto the page you identified in steps 1 and 3c.
Test the Viral Installer. We’ll do this by temporarily adding values to each of the hidden form fields.

<!-- Developer:  you can configure your widget's values via Javascript. Learn more at http://docs.widgetbox.com/developers/viral-installer/ -->

    <form id="viral_installer_example_GetWidgetForm" style="display:none;">

    <input type="hidden" name="appInstance.instanceName" value="My Customized Viral Installer Widget"/>

    <input type="hidden" name="appInstance.width" value="200"/>

    <input type="hidden" name="appInstance.height" value="200"/>

    <input type="hidden" name="RemoteParam1" value="Viral Installer Test"/>

    </form>

    <script src=’http://www.widgetbox.com/get_widget_btn.jsp?sourceId=<Unique ID Value>&ns=viral_installer_example’></script>

Save your page. Load it in your browser.
Click the Get Widget link. The same menu that appears on the Widgetbox.com site when a user clicks Get Widget will appear. Pick a site to install your widget or just grab the widget code.
Take a look at your installed widget. The text "Viral Installer Test" should appear within.
Remove the temporary changes to the widget code made in step 10. Save the changes. Reload the page in your browser.
What’s next? Build an interface to feed values into the hidden form. What does does the interface need to look like? That’s up to you! If you want a quick solution, you can un-hide the Viral Installer form and each of the form input fields.
Don’t forget to come back to Widgetbox and submit your widget for consideration in our Gallery.