WidgetFactory Add-on Manual

Last update: January 9th, 2014

Copyright © 2010-2014 ClickFWD LLC

Chapter 1 WidgetFactory Overview & Installation

The WidgetFactory add-on for JReviews allows you to create remote widgets with listing information that publishers will place on their websites and drive traffic to your site. The add-on can also track widget impressions and clicks on links in the widget.

1.1 Widget Types

There are two types of widgets:

Many listings - displays multiple listings in a widget (i.e. List of top rated listing, listings in a specific category, etc.). Example:

One listing - displays a single listing (i.e. listing information with reviews and photo gallery). Example:

Both types of widgets have many parameters to choose to control the information shown and its layout. Some of the parameters can be customized by publishers as well. Widgets can be further customized by modifying their theme files.

1.2 Widget Statistics

The add-on is capable of tracking widget impressions and clicks (if enabled in the configuration) and on the add-on Summary page you can see impressions and clicks charts:

On the add-on Statistics page you can find detailed statistics of widgets, source sites, referrer page and target pages:

1.3 WidgetFactory Installation

The add-on can be installed via the Install & Update menu in the JReviews administration.

To install or update the addon you must have previously purchased it, your JReviews version needs to match or be greater than the one specified for the addon and you must have a valid "Upgrades & Support" package for your JReviews license.

If you purchased the addon, but it still says "addon not active for this license", go to the JReviews admin license screen, clear the local key text area and re-submit the license number. This will fetch a new local key that includes the addon information.

On the Install & Update page, check the Updates checkbox, and click on the Install button next to the WidgetFactory Add-on like on this image:

Reload the page to see the WidgetFactory link appear under the Add-ons header on the left sidebar:

Chapter 2 Creating Widgets

To create a widget, click the Widget Manager link in the WidgetFactory add-on.

Choose the type of the widget and click New:

2.1 Creating a "Many Listings" widget

Create this type of widget if you want the widget to show multiple listings, for example: top rated listings, most popular listings, listings from a specific category, listings that have a specific field value, etc.

Title – widget title that will be displayed on the widget list page.

Description – enter more info about the widget.

State:

Published – widget will be available for publishing.

Unpublished – widget will not be available for publishing, but it will still work if already published on some site.

Disabled – widget will no longer work on any site.

Some of the widget settings have a checkbox next to the gears icon. When checked, the setting becomes a server-side-only setting and it is excluded from the widget markup code. Publishers won't be able to override it.

Theme Suffix – here you can define a custom theme file suffix in case you want a different theme file for each widget. More info about this is available in the Customizing Widget Themes chapter.

Responsive Layout – if enabled, the widget will automatically adjust its dimension to fit the available space on the publisher's site.

Width – if you want the widget to have fixed dimensions, enter the width in pixels. If you specify the width and leave Responsive Layout enabled, this width will be used to set the initial widget width.

Height – if you want the widget to have fixed dimensions, enter the height in pixels. If you specify the height and leave Responsive Layout enabled, this height will be used to set the initial widget height.

Widget Layout – here you can enter html code that will wrap the widget. This is useful to add branding logo and widget title.

Static HTML – this is the placeholder text that will be displayed on the publisher site until the widget loads. If you want a link back to your site that can be indexed by search engines for SEO, you will add it here.

Number of Listings – choose how many listings will be shown in the widget.

User Specific – if you select „My Listings“ or „My Favorites“, when logged in users get the widget code, the widget will show their listings or their favorite listings.

Order – choose how the listings will be ordered.

Filter Categories by Listing Type – if you select a listing type, the next parameter will show only those categories that use the selected listing type. Click Refresh to update the categories.

Categories – if a category is chosen, the widget will show listings only from the selected category.

Custom Fields comma list – here you can enter a list of custom fields (i.e. „jr_state,jr_city“). Click Refresh and then you'll be able to select specific values from those custom fields for the widget to show only listings that have those values.

Summary Words – choose how many summary text words the widget will show for each listing.

Show Category – if enabled, the listing category will be displayed below the listing title.

Custom Fields comma list – choose which custom fields will be displayed for each listing.

Show Editor Rating – if enabled, editor rating stars will be displayed.

Show User Rating – if enabled, user rating stars will be displayed.

Thumbnal Type – choose Crop or Scale mode for thumbnails.

Thumbnal Dimensions (px) – enter maximum width and height for the thumbnails.

Thumbnail Position – choose where the thumbnail will be positioned in relation to the listing content.

2.2 Creating a "One Listing" widget

Create this type of widget if you want the widget to show a single listing. The widget can show all listing details (summary text, custom fields, rating, photos, reviews), but you can also create a compact rating badge. Example of creating a compact rating badge can be found in the Widget Theme Customizations chapter.

Title – widget title that will be displayed on the widget list page.

Description – enter more info about the widget.

State:

Published – widget will be available for publishing.

Unpublished – widget will not be available for publishing, but it will still work if already published on some site.

Disabled – widget will no longer work on any site.

Theme Suffix – here you can define a custom theme file suffix in case you want a different theme file for each widget. More info about this is available in the Widget Theme Customizations chapter.

Responsive Layout – if enabled, the widget will automatically adjust its dimension to fit the available space on the publisher's site.

Width – if you want the widget to have fixed dimensions, enter the width in pixels. If you specify the width and leave Responsive Layout enabled, this width will be used to set the initial widget width.

Height – if you want the widget to have fixed dimensions, enter the height in pixels. If you specify the height and leave Responsive Layout enabled, this height will be used to set the initial widget heigth.

Widget Layout – here you can enter html code that will wrap the widget. This is useful to add branding logo and widget title.

Static HTML – this is the placeholder text that will be displayed on the publisher site until the widget loads. If you want a link back to your site that can be indexed by search engines for SEO, you will add it here.

Summary Words – choose how many summary text words the widget will show for the listing.

Show Category – if enabled, the listing category will be displayed below the listing title.

Custom Fields comma list – choose which custom fields will be displayed for each listing.

Show Editor Rating – if enabled, editor rating stars will be displayed.

Show User Rating – if enabled, user rating stars will be displayed.

Number of Reviews – choose how many reviews will be shown below the listing details.

Review Type – here you can choose between All reviews, Editor reviews and User reviews.

Ordering – you can order reviews by Most Recent, Most Helpful and Best Rating.

Show Title – if enabled, the review title will be shown.

Comment Words – enter the number of review comment words to show. To hide review comments, enter 0.

Read Reviews Link – if enabled, Read Reviews link will be displayed below the reviews.

Write Review Link – if enabled, Write Review link will be displayed below the reviews.

Number of Photos – enter the number of listing photos that the widget will display.

Display Layout – there are two layouts for displaying photos: Gallery and Contact Sheet.

Gallery layout example (a single photo is displayed with arrows to view other photos):

Contact sheet example (all photos are displayed below listing details):

Thumbnail Type – choose Crop or Scale mode for thumbnails.

Thumbnal Dimensions (px) – enter maximum width and height for the thumbnails.

Thumbnail Position – choose where the thumbnail will be positioned in relation to the listing content. This setting is used for Gallery layout only.

Chapter 3 Displaying Widgets

To display a list of available widgets that visitors will be able to display on their websites, it is necessary to create a menu item. To create it, go to the Joomla Menu Manager, choose one of your menus and click the New button. On the menu selection popup, choose WidgetFactory Add-on:

Enter the menu item Title and optionaly Page Description. If you want the page to display a title, click on the Page Display Options and enter the title in Page Heading parameter (also set Show Page Heading to Yes).

When site visitors click on that menu item, they will see the list of all widgets that you created in the Widgets Manager:

If you want to add an image next to the widget description, you can do it by adding the image html code in the widget description:

When visitors click the Get Code button next to a widget, they'll be able to customize the widget parameters and grab the widget code to place it on their website. On the right side of the customizable parameters, users can see how the widget will look like (the widget output updates automatically with every parameter change):

After the widget is customized, users need to click the blue Get Code button to grab the code and place it on their website:

The previous example showed how the „Many Listings“ widget looks like. When users choose a „One Listing“ widget type, they will be able to select a specific listing they want to show:

Chapter 4 Configuration

The WidgetFactory add-on has several configuration settings:

Enable view cache – caches the widget output.

Load widget from site root – when users click the Get Code button, it will contain the full path to the widget loader file:

example.com/components/com_jreviews_addons/widgetfactory/views/js/widget.loader.min.js.

If you want the code to load the widget from site root, you can copy the widget.loader.min.js file to the root of your site and enable this setting. Then the path in the code will look like this: example.com/widget.loader.min.js. If you enable this setting make sure you always keep this file up to date.

Track widget clicks – if enabled, the add-on will log every click in the widget on publisher sites with useful information.

Track widget impressions – if enabled, the add-on will also log every widget impression on publisher sites. If publisher sites will have high traffic, the database table where the impressions are stored could grow very quickly. In this case you can disable tracking impressions or purge the data in _jreviews_widgets_stats_views periodically.

Blacklisted sites – if you don't want some sites to load your widgets, you can enter the domain names here (domain names should be separated by a comma).

Chapter 5 Widget Theme Customizations

5.1 Widget CSS Files

The css files that the widgets use are located here:

/com_jreviews_addons/widgetfactory/views/themes/widgetfactory/theme_css/widget.css

/com_jreviews_addons/widgetfactory/views/themes/widgetfactory/theme_css/widget_custom_styles.css

It is not recommended to customize the widget.css file. Instead add your custom override styles to the widget_custom_styles.css file.

If you already have a custom JReviews theme inside the jreviews_overrides folder, you can copy the file there. This would be the full path:

/templates/jreviews_overrides /views/themes/your_theme/theme_css/widget_custom_styles.css

By default, the widget container doesn't have any styles (borders or backgrounds):

You can add a background and a border to the .jrWidgetLayout class name in the widget_custom_styles.css file, for example:

.jrWidgetLayout {
    border: 1px solid #ddd;
    background: #f5f5f5;
    padding: 10px;
}

If you want to add your site's logo to the widget, the quickest solution is to add the logo image to the Widget Layout parameter in the Widget Manager, for example:

A widget with a logo would look like this:

Alternatively, you could add the logo as css background of the .jrWidgetLayout class or add the logo directly to the widget's theme file.

5.2 Widget Theme Files

The theme file that the „Many Listings“ widgets use is this:

/com_jreviews_addons/widgetfactory/views/themes/widgetfactory/widget_listings/many.thtml

The theme file that the „One Listing“ widgets use is this:

/com_jreviews_addons/widgetfactory/views/themes/widgetfactory/widget_listings/one.thtml.

Both of those files can be placed in your custom JReviews theme inside the jreviews_overrides folder, this would be the paths:

/templates/jreviews_overrides /views/themes/your_theme/widget_listings/many.thtml

/templates/jreviews_overrides /views/themes/your_theme/widget_listings/one.thtml

You can have multiple suffixed theme files if you want each widget to use its own theme file. In the widget's Theme Suffix paramater enter the suffix (i.e. _hotels) and then create a many_hotels.thtml theme file.

The WidgetFactory theme comes with one suffixed theme file by default:

/widget_listings/one_badge.thtml

Chapter 6 Widgets Module

The Widgets Module is installed automatically when you install the WidgetsFactory add-on.

Use the Widgets Module if you want to show one of the „One Listing“ widgets on the listing detail pages of your site. The purpose of the module is for site visitors to be able to quickly get the widget of the listing they are viewing on your site. The module will output „Get this widget“ and „View all widgets“ buttons below the widget:

The Widgets Module has a single parameter where you need to enter an ID of the widget you want to display. It must be an ID of the „One Listing“ type of widget.

IDs of widgets can be found in the Widget Manager:

The module must be published only on listing detail pages (for Menu Assignment of the module, select parent menu items of listings (Joomla Category Menu Items)).