Custom Gallery Integration Guide
Overview: Building and Integrating Your Custom Gallery
Step 1. Define the widget categories you want to include in your Custom Gallery and select the widgets that will be included in each category using the Edit Content page in your Custom Gallery Dashboard.
Step 2. Select one of the following options to integrate your Custom Gallery and present widgets on your website.
- Option 1 (easiest): Use Widgetbox’s Pre-Built, Customizable Interface.
- Option 2 (more advanced): Create your own interface using Widgetbox’s XML, RSS, ATOM, or JSON feeds.
Step 3. (Optional) Create a technical integration that allows users to install widgets to your site. You will need to create a page that can accept data sent via an HTTP(S) POST operation.
Detail: Building and Integrating Your Custom Gallery
Step 1. Define the widget categories you want to include in your Custom Gallery and select the widgets that will be included in each category using the Edit Content page in your Custom Gallery Dashboard.
Steps to do this are outlined in the Custom Gallery Content Guide.
Step 2. Select one of the following options to integrate your Custom Gallery and present widgets on your website.
- Option 1 (easiest): Use Widgetbox’s pre-built, customizable interface
The pre-built interface can be embed as an IFrame directly on your site or placed in a pop-up window invoked by your site. You can customize the HTML used in the header and footer as well as its related CSS to ensure it matches the look and feel of your site.
To embed the Custom Gallery into your site, simply create an IFrame with the “SRC” property set to:
- http://www.widgetbox.com/cgallery/[Gallery-code]/home
Where, [Gallery-code] is an identifier we use to represent your custom galleries in our system. This will load the home page of your Custom Gallery in the IFrame.
To load the IFrame with a specific category already pre-selected, you can use:
- /cgallery/[Gallery-code]/category/[category-code]
You can customize the appearance of Widgetbox’s pre-built interface by adding your own header and footer HTML and CSS on the Edit Appearance page in your Gallery Dashboard. Access your Gallery Dashboard by logging into Widgetbox, clicking the My Widgetbox tab, and then clicking My Gallery.
Example of a Custom Gallery home page
Option 2 (more advanced): Create your own interface using Widgetbox’s XML, RSS, ATOM, or JSON feeds.
Widgetbox’s XML, RSS, ATOM, and JSON feeds allow you to create your own user interface. Use this option if you want to retain complete control over your UI or integrate Widgetbox widgets onto your site’s existing pages.
Below is a list of the available feeds. These feeds display the widget metadata based on the categories you created (in Step 1) and provide an endpoint that allows you to search across all the widgets in your gallery. (Note: XML feeds are given by default.)
* /cgalleryfeed/[Gallery-code] —> Metadata about your Gallery
* /cgalleryfeed/[Gallery-code]/categories —> All categories in your gallery
* /cgalleryfeed/[Gallery-code]/category/[category-code] —> Widgets in [category-code]
* /cgalleryfeed/[Gallery-code]/search/[search-term]—> Widgets matching [search-term]
You can view all available feeds and make changes to them by visiting the Integration Details page in your Gallery Dashboard.
Since the number of results can be large, the feeds are intrinsically paginated. In order to page through the results, you can change the value of certain parameters via the query string. These parameters are:
* p = current page, if not present, default = first page
* s = sort by (enum), default = TOP_RATED
* m = page size (or Max page size), default = 50
This metadata is added such that one can see the current “state” of the feed. pageSize is the current number of items shown in a given feed, by default this is 15. page, means the current page you are viewing in the feed. pages is how many total pages there are given the total number of records divided by the pageSize. sortBy is the current sorting of the items. sortBy is an enumeration whose valid values are: SUBSCRIPTIONS (Most Popular), HOTNESS_QUOTIENT (Hot Right Now), PUBLISHED_ON (Newest), TOP_RATED (Top Rated).
Thus a paginated URL could look like,
http://www.widgetbox.com/cgalleryfeed/[Gallery-code]/category/media?m=10&p=3&s=PUBLISHED_ON
This would make a page size of 10 items, page 3 of N, sorted by the newest in descending order. To paginate, you would change the value of p, keeping all other parameters the same.
The UI should link to the details page of the widget in either a popup or an IFrame. The widget details page allows the user to customize a widget and for us to capture the unique subscription ID.
Here’s an example of the link to the details page for a widget:
http://www.widgetbox.com/cgallery/{gallery-code}/widget/{widget-id}
where {widget-id} is the value “id” provided for each widget in the feeds.
To customize the appearance of the details page, click on the Edit Appearance button in your Gallery Dashboard. Access your Gallery Dashboard by logging into Widgetbox, clicking the My Widgetbox tab, and then clicking My Gallery. Here you will be able to add custom html header and footer and custom css to your details page. For more information on editing the appearance of your gallery, please read Custom Gallery Content Guide.
Step 3. (Optional) Create a technical integration that allows users to install widgets to your site. You will need to create a page that can accept data sent via an HTTP(S) POST operation.
For your site to receive a user’s widget installation request, you must have an PHP/JSP/ASP page, servlet, or similar service that does the following:
- 1. Ensures the request is being made by an authenticated user of your site. This is how you know whose page to install it on.
2. Generates/inserts the Widgetbox JavaScript tag into the user’s page. (More on this in a second)
3. (Optional) Some way to move or delete widgets from the user’s page. This is normally accomplished by your system treating the Widgetbox JavaScript tag as a standard component of your site (such as a sidebar element, profile item or blog post). Note that if you allow users to install Widgetbox panels, Widgetbox can manage the arrangement of widgets from inside Widgetbox without re-installing any snippets on your site.
Enter the target URL for that page on the Integration Details page in your Gallery Dashboard. To get to this page, log in to Widgetbox, click on the My Widgetbox tab, then click on the My Gallery link on the left of the page.
There are two (2) options for how you receive the widget installation request from Widgetbox:
- 1. Widgetbox sends the widget ID to your target URL.
Most Widgetbox Custom Gallery partners prefer this option because it is lighter weight and more secure. To implement, keep a template of the widget snippet (it’s the same snippet for every widget in the gallery) and insert into it the ID sent by Widgetbox when the user requests the widget. The snippet templates are shown below with ${} around where the id should be swapped in.
The snippet for a standalone widget:
<script type="text/javascript" src="http://cdn.widgetserver.com/syndication/subscriber/InsertWidget.js"></script><script>if (WIDGETBOX) WIDGETBOX.renderWidget('{widget-id-from-request}');</script>
2. Widgetbox sends the entire widget code snippet to your target URL.
This option is easier to implement, however, if you don’t already accept unrestricted JavaScript, you may prefer option 1 due to security.
We are in the process of making this step self-service, but in the meantime, a friendly Widgetbox employee will assist you with this step.
