WidgetFactory

Overview

Widget Types

WidgetFactory implements two types of widgets:

• Many Listings

  Shows multiple listings, and has a variety of options for listing ordering and filtering.

• One Listing

  Shows a single listing, and can include a simple photo gallery and user reviews.

Below you can see a live example of a one listing widget embedded on this page, and below it the exact code used to embed the widget. This code is automatically generated and publishers just copy it and paste it on their sites.

You can also play with the widget generator functionality on our demo site.

Menus

The add-on has just one WidgetFactory List Menu that is used to show the list of available widgets. From this page users can choose a widget and use the generator options to customize it, after which they can copy the widget code.

Modules & Widgets

The add-on includes a widgets Joomla module and WordPress widget. Yes, this is a bit confusing for WordPress. It's a "Widgetfactory widget" WordPress widget!

This is for use only in listing detail pages to provide users with a quick way to access the widget generator page for the current listing. When configuring the module/widget you only need to enter the one listing widget ID.

Getting Started

You can get started using the add-on with just a few steps:

1. Create the WidgetFactory Widget List menu

   Need a refresher on Creating Menus?

2. Create Pre-defined Widgets

   To allow end-users to use the widget generator to configure their widgets and get the embed code, it's necessary to create and pre-configure the widgets you want to offer on the site. This is coverered in more detail in the next section.

3. Review configuration settings

   The configuration allows you to toggle tracking of impressions and clicks, block specific sites from displaying widgets, and fine-tuning the widget loading options if widgets don't load with the default settings.

Creating Widgets

Use the Widget Manager to create your first widget. First select the Widget Type, then click New.

Below we'll go over some of the most relevant settings and widget functionality.

Title and Description

These fields are used in the Widgets List page in the front-end to give users more information about what the widget can do. For example, you could create a couple of different widgets to display top-rated listings:

• Top rated restaurants in New York
• Top rated hotels in New York

Server Side vs. Site Settings

You'll notice many widget settings have a gear icon with a checkbox to the left. This means the setting can be setup as server side with the pre-defined value you use in the administration. The setting will not be available in the widget generator nor in the resulting widget code. Instead, it will be read directly from the server when displaying the widget on publisher sites.

Dimensions

The widgets can be set to responsive so the iframe used to show the widgets automatically adjusts to the available space. Even when using the responsive setting, you should also set initial dimensions to minimize the amount of change needed in the layout from the moment the page loads until the widget is fully rendered.

Widget Layout

This is a simple layout that wraps the widget output. You can use this to add your site logo and a heading:

<div class="jrWidgetLayout">
  <div><img alt="Your Site" src="https://yourdomain.com/path/to/logo.png" /></div>	
  <h2>Top Rated Restaurants in New York</h2>
  {widget}
</div>

Static Layout

This is static text is shown on the publisher site before the widget loads and replaces it. Since end-users will be copying the code that includes this static text, you can also optionally include a link to your site which will be seen by search engines. The add-on has logic that prevents end-users from adding links to point to sites different than your own. If it detects a different domain, the widget will not load.

The Refresh Button

A couple of settings Filter Categories by Listing Type and Custom Fields comma list have a Refresh button to the right of the setting. Whenever you make a change for these settings, you need to click the refresh button to load the dependencies. For example, when you select a listing type for filtering, the button will load the categories for the selected listing type. When you add a list of custom fields, the button will load the fields so you can use them for further filtering.

When creating a widget, you can preview on the right-hand side the widget output, static and rendered, as well as the widget code that you can copy and add to a page on your site or another site to test the widget.

Statistics

The add-on can track widget impressions and clicks when these are enabled in the configuration. When you access the add-on you can see historical graphs with these numbers.

In the statistics page you will also find detailed statistics for widgets, source sites, referrer and target pages.

CSS Customizations

To have faster loading times for the widgets, the add-on uses its own CSS file with a minimum of CSS classes. This means that overriding the CSS for widgets requires using a separate CSS file widget_custom_styles.css, which is different from the one used by JReviews on your site.

Like with JReviews CSS customizations you create this empty file inside your custom theme's theme_css folder.

Joomla

templates/
`-- jreviews_overrides/
	`-- views/
		`-- themes/
			`-- mysite/
				`-- theme_css/
					`-- widget_custom_styles.css

WordPress

In WordPress create the folder in the root of the site

jreviews_overrides/
`-- views/
    `-- themes/
        `-- mysite/
            `-- theme_css/
               `-- widget_custom_styles.css

For example, if you wanted to add a background and border to the widget layout, you can do something like this:

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

Template Customizations

Template overrides for WidgetFactory works in the same way as it does for JReviews and other add-ons. You identify the template you need to change, then create a copy in overrides.

To override the actual output for the widgets one listing and many listings you'll be overriding the many.thtml and one.thtml in the add-on's widget_listings theme folder and copying them to your custom theme in overrides.

Joomla

templates/
`-- jreviews_overrides/
    `-- views/
        `-- themes/
            `-- mysite/
                `-- widget_listings/
                    |-- many.thtml
                    `-- one.thtml

WordPress

jreviews_overrides/
`-- views/
    `-- themes/
        `-- mysite/
            `-- widget_listings/
                |-- many.thtml
                `-- one.thtml

The add-on already includes a suffixed version of the one listing template named one_badge.thtml and you can use the _badge theme suffix in the widget settings to use it. It displays a compact output with just the listing title and rating.

Troubleshooting

To show the widgets on external sites, a request needs to be made from the external site to the host site. This is known as a Cross-origin resource sharing (CORS) request. For these types of requests to work, the server to which the request is made (your site) need to grant permission to the originating site.

The add-on will set these headers autmatically so the widgets work without any further action. However, if you find widgets are not displaying on external sites, you can use Firebug or the Google Chrome Inspector tool to check the console. Typically you will find an error that looks like this:

XMLHttpRequest cannot load http://www.yoursite.com/index.php?option=com_jreviews&format=ajax&url=widget_…ll&count=5&userrating=1&id=99&task=listings%2Fone&wid=abcd. The 'Access-Control-Allow-Origin' header contains multiple values '*, *', but only one is allowed. Origin 'http://www.externaldomain.com' is therefore not allowed access.

If this is the case, then you need to manually enable CORS requests to your site. Edit the .htaccess file on the root of your website, and add this line:

Header add Access-Control-Allow-Origin "*"

On Nginx servers without Apache, you would add the code below to your server's .conf file:

add_header Access-Control-Allow-Origin *;
proxy_set_header Access-Control-Allow-Origin $http_origin;

In some cases, when you already have the headers set on the server, you need to use the configuration setting in the add-on to disable the CORS headers because sending the headers twice can also prevent the widgets from loading.