Overview
The purpose of this document is to provide a widget that allows retrieval of Review Survey Response data from Rollick that can be displayed on brand sites without extensive brand site programming.
Review Survey data can be retrieved using a widget placed within a web page that calls an API that returns review data. This widget can be customized using a list of configuration properties listed in the Configuration Options Properties section below.
Steps
First step, copy & paste the Javascript below into the <head> tag of the desired page to reference the widget call.
Below is the line of code to copy & paste into the <head> tag:
<script type="text/javascript" src="https://<clientInstall>.aimbase.com/scripts/reviewwidget.js" id="AimbaseReviews"></script>
*Note: Replace <clientinstall> with the aimbase 3.0 installation the client has.
Next, copy & paste the below HTML <div> tags on to your page anywhere in the <body> tag where you would like the Ratings & Reviews to appear on your page. These can also be added to an "HTML Code" view of a Rich Text Editor in some CMS tools. The HTML <div> tags act as placeholders which display your reviews. After the page has been loaded, the widget will be initialized and will display all available review data within the below HTML elements placed on your page.
Begin by copying & pasting the HTML below into your page:
<div id="listItemContainer"></div>
<div id="pagingContainerFooter"></div>
*Note: The <div> elements ids can be renamed at a later date, as well as target other elements with the widget’s configuration properties. See the Configuration Object Properties section.
After the HTML <div> elements have been pasted onto your page, copy and paste the Javascript below in the <body> tag, but below the <div> elements created in the previous step.
Below is a sample of some Javascript that can be added to the HTML page which is required for the widget.
<script type="text/javascript"> var reviewWidget = aimbase.reviews.createReviewWidget({ targetListElementId: 'listItemContainer', targetPagingElementId: ['pagingContainerFooter'], manufacturerCode: '<MfgCode>' }); </script>
*Note: Replace <MFGCode> with the Aimbase manufacturer code that is provided by the Rollick representative. This is a required field. See list of Configuration Properties that can be called below.
Here is a full working HTML example of the widget code placed in an HTML page.
<!doctype html> <html> <head> <title>Ratings & Review</title> <meta charset="UTF-8" /> <script type="text/javascript" src="https://<clientInstall>.aimbase.com/scripts/reviewwidget.js" id="AimbaseReviews"></script> </head> <body> <h1>Ratings & Review</h1> <div id="listItemContainer"></div> <div id="pagingContainerFooter"></div> <script type="text/javascript"> var reviewWidget = aimbase.reviews.createReviewWidget({ //Configuration Options targetListElementId: 'listItemContainer', targetPagingElementId: ['pagingContainerFooter'], manufacturerCode: '<MfgCode>', reviewWidthPercent: 50, starColor: 'gold' }); </script> </body> </html>
Configuration Options
Below is a list of Configuration Options that can be included in your Javascript to change how data is displayed and the appearance of the data.
| Property | Type | Description |
|---|---|---|
manufacturerCode |
string |
Required – the manufacturer code as found in Aimbase. |
|
disclaimer |
string |
Default - '* The reviews below are from certified owners.' Disclaimer can be edited as desired. |
|
itemTemplate |
HTML as a string |
HTML markup can be used to customize the HTML contents that make up each "Non-Featured" review item displayed injected into the list item’s HTML markup.
'<div class="arw-header right">' + '<div class="arw-rating arw-rating-$$Rating$$"></div>' + '<div class="arw-create-date">$$CreateDate$$</div>' + '</div>' + '<div class="arw-header left">' + '<div class="arw-title">' + '<h4>$$Title$$<h4>' + '</div>' + '<div class="arw-author">' + '<h6><span class="arw-authorName">$$Name$$</span></h6>' + '</div>' + '<div class="arw-city-state">' + '<h6><span class="arw-city">$$OwnerCity$$</span>, <span class="arw-state">$$OwnerState$$</span></h6>' + '</div>' + '</div>' + '<div class="arw-message">' + '<p>$$Review$$</p>' + '</div>'
A placeholder markup has been created to inject review data within the HTML template markup provided. An example placeholder markup is $$Title$$. In this example, it will replace $$Title$$ with the text found in the Title property of the review result object returned from the API call.
See the Default Review Result Item Properties section for a list of property names you can use when working with the placeholder markup.
|
featuredItemTemplate |
HTML as a string |
HTML markup can be used to customize the HTML contents that make up each "Featured" review item displayed injected into the list item’s HTML markup.
'<div class="arw-header">' + '<div class="arw-rating arw-rating-$$Rating$$"></div>' + '<div class="arw-create-date">$$CreateDate$$</div>' + '<div class="arw-author">' + '<h6><span class="arw-authorName">$$Name$$</span></h6>' + '</div>' + '<div class="arw-city-state">' + '<h6><span class="arw-city">$$OwnerCity$$</span>, <span class="arw-state">$$OwnerState$$</span></h6>' + '</div>' + '</div>' + '<div class="arw-message">' + '<div class="arw-title">' + '<h4>$$Title$$<h4>' + '</div>' + '<p>$$Review$$</p>' + '</div>' + '</div>'
A placeholder markup has been created to inject review data within the HTML template markup provided. An example placeholder markup is $$Title$$. In this example, it will replace $$Title$$ with the text found in the Title property of the review result object returned from the API call.
See the Default Review Result Item Properties section for a list of property names you can use when working with the placeholder markup.
|
itemFormatter |
string |
A Javascript function that accepts 1 parameter and be used to customize contents of items. This is called just prior to the data being passed into the item template generation process. A good example of where you may use this is to customize date strings to display in a different format than what was provided via the API.
|
brandCode |
string |
Optional parameter used to filter the results further to specific brand codes.
|
productTypeCode |
number |
Optional parameter used to filter the results further to specific product type codes.
|
productCode |
string |
Optional parameter used to filter the results further to a specific product based on the product code. |
productModelYear |
number |
Optional parameter used to filter the results further to specific product model years.
|
dealerNumber |
number |
Optional parameter used to filter the results further to specific dealer.
|
dealerLocation |
string |
Optional parameter used to filter the results further to specific dealer location.
|
currentPageNumber |
number |
Default value of 1. Used to set what current page number should be loaded within the paged results retrieved from the API.
|
reviewWidthPercent |
number |
Default value is 50. Used to set the CSS 'width' in a percentage of the "Non-Featured" reviews in respect to the widgets parent HTML container. Example: 50 will set the "Non-Featured" review to be '50%' width of its parent containers width. Both "Non-Featured" & "Featured" reviews will float left and responsively change to '100%' width on mobile.
|
reviewPixelPadding |
number |
Default value is 50. Used to set the CSS 'padding' between the edges of the HTML parent container and each "Non-Featured" review in respect to one another. Example: 50 will wrap a padding of '50px' between the reviews widget within its parent container, and all "Non-Featured" reviews.
|
starColor |
string |
Default is Gold. The CSS 'color' property which defines the color of the review "Stars". CSS Hexadecimal Colors (#000000), RGB Colors (rgb(255, 0, 0)), RGBA Colors (rgba(255, 0, 0, 0.5)) and Natural Language Colors ('yellow', 'gold', 'red', etc...) are all accepted.
|
starPixelSize |
number |
Default value is 25. Used to set the pixel size of the review "Stars". "Featured" review stars will be 1.5 times the size of the stated value. Example: 30 will set the font-size of all stars to be '30px' and all "Featured" item stars to be '45px'.
|
pageSize |
number |
Default value of 10. Used to determine how many reviews should be returned per page.
|
pageFirstText |
string |
Default value “First.” Text to display whenever the user is beyond page 1.
|
pageLastText |
string |
Default value “Last.” Text to display whenever there is more than 1 page and the user is currently not on the last page.
|
noResultsTemplate |
HTML as a string |
Default “no reviews found.” Displays whenever no results are found. Supports HTML markup.
|
onLoad |
function() |
Method, called before making the API call to retrieve data. Accepts 1 parameter which is the current config state.
|
onLoadComplete |
function() |
Method. Called after an API call completes. Does not have any parameters.
|
onHttpError |
function() |
Method Called whenever the API call when loading data fails. Has 1 argument which contains the statusText of the failed request.
|
numberOfPagesToDisplay |
number |
Default value of 3. Used to display how many pages before or after the current page before.
|
orderBy |
string |
Default value “Featured.” Available options are: Featured, CreateDate, PurchaseDate, Rating. |
| IsOrderByDescending | boolean | Default value is true. Determines the sort order. |
targetListElementId |
string |
Default value: “ReviewList”. Used to identify which element on the page to inject list result HTML markup into.
|
targetPagingElementId |
string |
Default Value “ReviewPagingElement.” Similar to targetListElementId, this is used to identify which element on the page to inject paging data on. This value can either be a string, or an array of strings to target multiple elements in the case of the web developer wanting to have paging display on the top and bottom of the review results.
|
tags |
array (string) | Default value [] (no tag filtering). Reviews can be given multiple tags by editing the review in the Aimbase user interface. The review widget can then be configured to only return results where the review has the tags specified. Some common usage examples for tags are tagging reviews with the brand website name, dealer website, or ecommerce site. If tags were assigned in that way, then the widgets on those websites could be configured to only show reviews for their own website. If multiple tags are submitted in the search, then only reviews that have ALL submitted tags are returned in the search results. |
Default Review Result Item Properties
Below is a list of review item properties that are provided by default in the review API results. These properties may be used in the itemTemplate & featuredItemTemplate as $$PropertyName$$ configuration property as well as used in the itemFormatter config property method.
Property Name |
Description |
BrandName |
Brand Name |
CreateDate |
Date review was created. Example Format: 2016-03-08T13:24:41.617 |
IsFeatured |
Is the review featured? (true/false) |
ManufacturerName |
Manufacturer Name |
Name |
Owner Name. |
OwnerCity |
Owner City |
OwnerState |
Owner State |
ProductModelYear |
Product Model Year (Example, 2015) |
ProductName |
Product Name |
ProductTypeName |
Product Type Name |
Rating |
Rating number. Values can range from 1-5. |
Review |
Review text |
SurveyFormName |
Survey form name |
SurveyTypeCode |
Survey type code |
SurveyTypeName |
Survey type name |
Title |
Title text of the review |
Review Widget Method and Properties
Name |
Type |
Description |
refresh |
Method |
Refreshes the widget control |
Config |
Property |
Returns the current state of the configuration object. Can be useful to get/set config values after the widget has been initialized. |
Destroy |
Method |
Purges the current instance from the widget library’s memory |
Example how to use the refresh method:
<script type="text/javascript"> var reviewWidget = aimbase.reviews.createReviewWidget({ targetListElementId: 'listItemContainer', targetPagingElementId: ['pagingContainerFooter'], manufacturerCode: '<MfgCode>' }); reviewwidget.refresh(); </script>