(As of June 1st, 2011, the viral installer feature is no longer available)

Getting Started

The Viral Installer consists of code that allows users to customize and grab your widget from any website.

The code contains two key sections:

1. A hidden form that includes all of the configurable widget settings you define when registering your widget on Widgetbox.
2. JavaScript that displays a Get Widget button. When a user clicks Get Widget, the same JavaScript opens the Viral Installer Menu 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 with a widget setting.

1. Create a simple page on your 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".
2. On Widgetbox.com, click the Make a widget button to get started. Next, create a new HTML/JS widget and give it a name.
3. Next, add a new setting named My Setting. You can use that for its label as well. Give it a default value of MyValue so that the widget has something to display. Then click the Apply Changes button. We'll just keep it simple for now.
   
4. In order to show how widget settings work, let's add some code to display the value of the setting you just added. Simply add MySetting: ${config.MySetting} to the code editor and click the Apply Changes button. This is how easy it is to use the settings you add within your widget's code!
   
5. Accept the Terms and Conditions and click Save Widget to continue.
6. The next page is your Widget's Dashboard. Here you can manage your widget, view stats, and important to the task at hand, distribute your widget. To do this, click the Distribute Your Widget button.
   
7. Before you grab the Viral Installer code, we're going to set up our widget to send users to the webpage that we set up earlier for configuring their widget instead of allowing them to configure the widget on Widgetbox. Click the Use remote configuration checkbox and enter in the URL from Step 1. Then click Save.
   
8. Next, let's take a look at what we just did. The gallery page for your widget has updated to reflect the change. Notice the Get Widget button is now in purple? This page will now instead display a message telling users to visit your site to get the widget.
   
9. Back on the Distribute Your Widget page, let's go ahead and continue with the Viral Installer code. Select the code from the text field and copy it to your clipboard.
   

   10. The code will look similar to 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="MySetting" value=""/>

    </form>

    <script src='http://pub.widgetbox.com/GetWidgetButton/sourceId/<Unique ID Value>/ns/viral_installer_example'></script>

 11. 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.

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

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

  12. Put the Viral Installer code onto the page you identified in Step 1.

 13. 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="Hello World Widget"/>

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

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

    <input type="hidden" name="MySetting" value="Hello World!"/>

    </form>

    <script src='http://pub.widgetbox.com/GetWidgetButton/sourceId/<Unique ID Value>/ns/viral_installer_example'></script>

 14. Save your page and load it in your favorite browser.

 15. Click the Get Widget button. The same Get Widget Menu that you see on Widgetbox.com will appear over the page, configured with your new settings. Pick a site to install your new widget or just grab the widget code.

16. Take a look at your installed widget. The text MySetting: Hello World! should appear within.

17. 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.

18. Don't forget to come back to Widgetbox and submit your widget for consideration in our Gallery.