The Helper Page

From Car and Driving
Jump to: navigation, search

The helper page can be called simply by embedding it as an iframe in your page as you would embedding a youtube video; using this method, the client site does not need to call the webservice at all.

Use this approach if your site is built in using content management software that is not able to call a webservice directly.


Contents

How To Use The Helper Page

To use the helper page, simply place the following lines on your webpage. We can customise what we see by altering the 'src=' argument of the iframe.


  • Example 1: A narrow 400px wide area with a 'video of the week' video at the top, and editorial content beneath, reached with a vertical scrollbar

<iframe id="cdvideo" src="http://www.caranddriving.com/ws/a041/helper/helper.aspx?user_id=demo&topreview=y&video_width=383" frameborder="0" marginwidth="0" marginheight="0" scrolling="vertical" seamless="seamless" align="middle" width="400" height="100%" allowfullscreen></iframe>

(IMPORTANT: Change 'demo' to your user_id, or the video will play as a sample, showing only the first 30 seconds of each chapter).


  • Example 2: A 800px x 500px window showing the 'video of the week' only (including chapter buttons), but with no text, header or scrollbars:

<iframe id="cdvideo" src="http://www.caranddriving.com/ws/a041/helper/helper.aspx?user_id=demo&topreview=y&what=video&video_width=800" frameborder="0" marginwidth="0" marginheight="0" scrolling="no" seamless="seamless" align="middle" width="800" height="500" allowfullscreen></iframe>


  • Example 3: If your content management system (e.g. GForces NetDirector Auto V10) does not allow you to embed HTML code in a webpage, you will need to set up a link to an external website instead. Simply include an image of the car you want to link to, or of a 'play video review' icon, and link it to the 'raw' helper page address - i.e.

http://www.caranddriving.com/ws/a041/helper/helper.aspx?user_id=demo&topreview=y&what=video&video_width=800

You should ensure the link is set to open a new window, rather than display in the current window. Note that the helper page has many options to allow you to set your own CSS to allow the helper page and video player to appear with the same styling as the rest of your site.

Arguments

The following querystring arguments are supported for this page:

  • user_id - always give this; it's your user id for the webservice. If you are a development house with your own user id, please contact us to set up a specific account for your end customer when you go live so we can track video views for each customer properly.
  • topreview - set to y to get the 'video of the week'. This can be simply the latest video filmed, or we can agree which video to highlight for you each week according to your requirements - we then control that from our office, so you do not have to maintain or change the video yourself every week. We recommend each client put a 'topreview' video player on the home page of the video reviews section of their website.
  • capid - a numeric (typically 5 digit) cap id, e.g. 43543
  • make - the manufacturer, e.g. Audi
  • model - the car model, e.g. A3, A4
  • year - the year of manufacture; e.g. 2012 will pickup a car in production from 2010 to 2013. Note that using this implies that you want a used car review only.
  • type - either new/used/womans - the type of review. Defaults to all reviews of not given. You should, unless you have a specific reason not to, leave this blank. Note that our definition of 'used' is not necessarily what you would expect - it means we have a specific used car editorial for that review (which has a different set of paragraphs to what we call a 'new' car review). If you search for a used car, you may get back either 'new' or 'used' reviews; this deliberate since a used car may still be in production and hence me amongst our list of new car videos. If you genuinely want a used car review only, set the 'year' argument to the year the car was made.
  • r - if you know the specific Car and Driving review id, use it here (e.g. 803 will show an Audi A3)
  • video_width - how wide in pixels you want the video (assuming there is one). If this is set to 'responsive', the video will be set to the maximum width possible for the space available, and the height adjusted automatically. The video will automatically resize as the screen is resized (during a tablet rotation, for example). For more information on responsive videos, see Responsive Videos.
  • howmany - limit the number of matches returned (if, for example, you simply specify make=bmw, you will get a lot of hits back, presented as a list). Defaults to 100 if not given.
  • range - set to y to return range reviews only, and not the derivative reviews. Default is to return all reviews.
  • cs - set to y is to switch the make/model search to use CAP compatible manufacturer/model names; default is standard (non CAP string) search. For example a search with make=Mercedes-Benz&model=C Class&cs=y returns more reliable matches than just make=Mercedes-Benz&model=C Class . Note that setting this also implies ordering with range first, but non-range articles are still returned in the list of results.
  • what - controls what the review page shows; defaults to all. A semi-colon seperated list of one or more of title;video;photo;data;text;scores;stdphoto;bigphoto;largephoto;xtitle. Stdphoto/bigphoto/largephoto return progressively larger images than would otherwise be returned. Xtitle gives a slightly differently arranged title, with no subtitle, and a 'Click here to read the editorial review on this car' link (this is intended to be used when only a video is shown, but a title is wanted too).
  • ordering - sets the order of the results; use one of title/date/revtitle/revdate/rangetitle/rangedate/rangerevdate/rangerevtitle/typetitle/typedate/typerevtitle/typerevdate/typerangetitle/typerangedate/typerangerevdate/typerangerevtitle (range on the front indicates put 'range articles' first in the results list; type on the front indicates 'sort by type first'), defaulting to title
  • css - specify an alternative css file to change formatting of the helper page (there is a separate argument to change the formatting of any video).
  • makelist - set to y to get a list of available makes, with clickthroughs to the corresponding list of models per make.
  • makemodeldropdown - set to true to get a make and model set of dropdowns, where the model list is populated when the make list is set. When the model list is set, the review is displayed. For formatting reasons, it is best to use this with the 'window' option so that the resulting video or editorial appears in a popup window. When using this option, please ensure that custom css is given (with the css option) to ensure that the basic grey dropdowns are replaced with dropdowns that match the look and feel of your site, and that the pop up window is suitably formatted to match your site. We recommend that you also set 'type' to either new or used; otherwise different types of videos will be mixed together - in general, we believe it is less confusing for users if you have separate make/model drop downs for new cars and used cars. If you set makemodeldropdown=Ford, the dropdown will be prepopulated for Ford (or other brands) - in this way you can make a tool that does a single brand easily. If you set makemodeldropdown=xFord (i.e. put an x before the brand name), or simply use 'x', you will get a slightly different layout of dropdown, with a New Car/Used Car review type selection box.
  • window - used with makemodeldropdown. Provides a set of formatting instructions for a popup window in which to display a selected review. If this is not given, the review will appear in the current window which will almost certainly look poor. The window argument is passed into a javascript window.open call as the third argument, specs, as defined here: http://www.w3schools.com/jsref/met_win_open.asp
Example of makemodeldropdown and window being used together to give a dropdown for new cars: 
http://www.caranddriving.com/ws/a041/helper/helper.aspx?user_id=demo&makemodeldropdown=any&video_width=responsive&type=new&what=video&css=helper.css&window=width=800,height=470,scrollbars=no,resizable=yes,toolbar=no
Example of makemodeldropdown and window being used together to give a dropdown for used cars: 
http://www.caranddriving.com/ws/a041/helper/helper.aspx?user_id=demo&makemodeldropdown=any&video_width=responsive&type=used&what=video&css=helper.css&window=width=800,height=470,scrollbars=no,resizable=yes,toolbar=no

Video Player Specific Settings

The following settings affect any video player displaying on the helper page.

  • autostart - Auto start parameter, true or false. If the value is not equal to true we assume its false, and the video does not autostart. If no parameter is supplied, then it defaults to true. Note that autostart doesn't work for iOS devices - iphones; ipads; ipods etc - so autostart will always be false on these devices, regardless of what you set this parameter to. This is because of a limitation built-in to iOS by Apple to conserve bandwidth.
  • films - full/short/fullshort/shortfull. Often, and usually for our latest film, we have a full 7 section film available, and also a short 5 minute long summary film that the video player can switch between if you press the full/short button on the player toolbar. The full video plays by default, and the short button (if available) allows you to switch to the short video. You can change that behaviour; setting 'films' to shortfull plays the short film by default, and gives a button to switch to the full video. Setting it to full plays the full film, but hides the short film button. Setting it to short plays the short film (assuming one is available) and disables the button to switch to the full video. If no short film is available, this option does nothing - it simply plays the full film.
  • video_css_url =- URL for a custom CSS file to chage colours/fonts etc of the chapter buttons. There's an example file here: http://www.caranddriving.com/new/css/playerstyle_custom.css. which only has a few style options, the other style parameters are inherited from our default styles. This means that you can just set the selection colour easily and leave everything else the same, or if they would prefer, change all the CSS styles.
  • logo_url = URL for an image to show as a watermark in the top left of the player, now defaults to C&D logo. These logos show for 6 seconds and then disappear to not disrupt the video. It's best to supply a PNG with transparency as done here: http://www.caranddriving.com/new/images/logo_trans.png
  • preview_url - URL for an image to show as a preview if autostart is disabled. Not used if autostart is enabled. For example:
 Show a different preview image: http://www.caranddriving.com/ws/a041/helper/helper.aspx?r=8770&user_id=caranddriving&autostart=false&preview_url=http://f8.caranddriving.com/videos/thumbs/new_volvov60_2011.jpg 
 Show the default preview image: http://www.caranddriving.com/ws/a041/helper/helper.aspx?r=8770&user_id=caranddriving&autostart=false
 Autostart (no preview images shown): http://www.caranddriving.com/ws/a041/helper/helper.aspx?r=8770
  • bitrate - force the player to display a specific bitrate and not a bitrate selected by the speed of the users connection. Accepts: 200, 700 and 2000. Again, you probably won't want to change this, but if you're building it into a mobile app for example, you'd probably set the bitrate to 200 to keep the bandwidth down to a minimum. 2000 is the HD feed.
  • manwidth - set to true if the buttons are not to be automatically resized. Defaults to false.
  • section_names - set to short to replace button text with shortened versions good for players < 375px wide.
  • sample - set to true to display a demo version of the video (shows all the first and last sections, and 30 seconds of each of the others). For C&D demo use only.
  • vanilla_css - use when providing your own css via video_css_url; if set to true this suppresses loading of the default css file; otherwise the default css file and the custom css are both loaded one after the other (so the custom css overrides the default one). We recommend leaving this off unless there is very good reason.
  • skin_zip_url [DEPRECATED] - URL for a custom player skin (zip) to change how the player itself appears (the play button, progress bars, etc), eg. http://www.longtailvideo.com/files/skins/glow/5/glow.zip - this feature is being withdrawn in readiness for an upgrade of the video player which will allow customisation via CSS. You should not use this option for new development as it will stop working soon.
  • ie_adjust [DEPRECATED] - IE users videos normally need their control buttons size different to other users; the video player automatically adjusts for that. However, in some case where the video is in an iframe, this adjustment actually breaks the button formatting; if so, set ie_adjust to n to switch off that behaviour. Generally with IE, one of ie_adjust=y (the default) or ie_adjust=n will format correctly, but which one depends on the way the video is placed on the page, and what is around it. If you see the wrong behaviour on IE, choose the other option for this switch. Other browser users (Chrome, Firefox, Safari, etc) are unaffected by this issue, and will see the right formatting regardless of what this switch is set to. This option is no longer supported or necessary.
  • videotype [DEPRECATED] - FLASH or HTML5; force the video player to paint as either a Flash or HTML5 native video player. This option is no longer supported or necessary as the video player now chooses the best option automatically according to the browser type; usually, this is the HTML5 player.

Finding Review IDs

Use the following links to find the review IDs of our videos:


Search Examples

Note: edits are returned in order of type (new, then used, then women's reviews), then range reviews (range reviews first), then alphabetical name of car.

Replace the 'src=' address in the examples at the top of the page with these lines to get different videos. Remember to replace "demo" with your webservice user_id

If you specify just the make, you will get a screen which shows you a list of matches - e.g.

Specify type to get just the new car reviews - e.g.

... and the model to break it down to just those that match (include cs=y to make the search more reliable; not really needed in this example)

... set range=y to remove the derivative reviews from the search:

... you can use 'howmany=1' to force it to pick and display one at random rather than give the list of matches:

... if you know the capid, include it and you'll get a more accurate match:

... or to get the A1 Sportback:

Note that if capid matches something, it overrides all the make/model/range search arguments. If not, it falls back on a standard make/model/range search to provide 'sensible' results, so it's useful to provide both on your search:

Control what you want to display when you reach a review page with the 'what' argument: e.g. video only (those grey lines above and below a video by the way are in removable by stylesheet if you wish):

... or title and text:

... or just the data on the car:

... get a list of all available makes:

... and finally, use a different style sheet to change the font and background colour:


Using the Helper Page to Embed Video in a Content Management System

You can use the helper page to load specific videos into your website's Content Management System, by including the correct embed code.

For more details, please see Adding Videos to Blogs and News Pages


Embedding Helper Page Content Directly with AJAX

This is a method of using the helper page without using iframes, embedding the video directly on the webpage. It requires knowledge of javascript/jquery programming. Use the following querystring arguments to pull back AJAX compliant code from the helper page.

  • body - If body=y is given, a block of code is returned, less all the header, body and start page/end page HTML tags. It is expected that the developer will take this code and insert it into the innerHTML element of a div block on the page.
  • head - If head=y is given, a block of code suitable for putting in the header part of a page - typically this will be one or more link statements that bring in CSS.

Example code:

<!DOCTYPE html>
<html>
<body>

<div id="demo">When you press the button, the review will load here. This could be done when a webpage finishes building using jquery to load a video automatically.\</div>
<button type="button" onclick="loadDoc()">Load Review</button>

<script>
function loadDoc() {
 var xhttp = new XMLHttpRequest();
 xhttp.onreadystatechange = function() {
   if (xhttp.readyState == 4 && xhttp.status == 200) {
     document.getElementById("demo").innerHTML = xhttp.responseText;
   }
 };
 xhttp.open("GET", "http://www.caranddriving.com/ws/a041/helper/helper.aspx?user_id=demo&r=1509&what=title;video;text&body=y", true);
 xhttp.send();
}
</script>

</body>
</html>
Personal tools