The Skicow API lets you embed ski searches in your own web pages. The API is designed to be very simple to use and customizable so that it integrates with your web site seamlessly.

The Skicow API is a free service for selected participants only. Using the API requires a key to be issued by Skicow. Prospective users of the Skicow API should contact Skicow to apply for a an API key.

Audience

This guide is designed for web masters who wish to embed a ski search facility on their web site.

The Skicow API uses Javascript to dynamically present a search form and search results. AJAX is used to retrieve data from skicow.com without the need for entire page changes. This provides the user with a more responsive experience.

Although the Skicow API utilizes the technologies identified above, as a user of the API, you do not need to be proficient in them since the Skicow API intentionally hides the complexity. Users of the Skicow API should simply need to adapt the examples provided by copying the code into the appropriate location on a web site and making any adjustments necessary for styling and layout requirements.

Using the Skicow API

This section explains how to use the Skicow API. The documentation is not exhaustive, but should be sufficient to explain what you need to do.

There are two strategies for embedding Skicow searches in you web pages. Each strategy has advantages and disadvantages identified in their respective sections below.

Embedding Skicow Searches using an IFRAME

Advantages	Disadvantages
Simple to implement.	Limited integration: • The styles may be different to the styles on your site. • There is no way to alter layout of Skicow search form and results.

The simplest way to embed a Skicow search is to use an <IFRAME> <HTML> tag. The <IFRAME> src attribute identifies a Skicow API URL which allows the AJAX interactions with the Skicow servers. Here is some example code showing you how to embed a Skicow search using an <IFRAME>:

  <iframe id="SkicowIframe" name="SkicowIframe" style="width: 100%; height: 100%;
          border: none; overflow-y: auto; scrolling: auto; hidefocus: true; frameborder: no"
          src="http://www.skicow.com/api/SkicowAPI.php?api_version=1.3&iframe=true&key=your_key">
  </iframe>

Note in the above example that the parameter iframe=true is necessary to ensure the frame is rendered properly.

Refer to SkicowAPIExampleSimple.htm for a complete example of this approach.

Embedding Skicow Searches without an IFRAME

Advantages	Disadvantages
Overcomes the integration problems of the `<IFRAME>` approach.	Slightly more complex to set up (requires copying a PHP file to a location on your web site to help communicate with the Skicow servers).

This approach requires you to first copy SkicowAPIProxy.php to a location on your web site. This PHP file acts as a proxy in the communications link between your web page and the Skicow servers This is a standard technique which is necessary to overcome the browser enforced security restriction of only letting Javascript make calls to the same server that the page was downloaded from. Refer to http://developer.yahoo.com/javascript/howto-proxy.html for further information.

Once the proxy PHP file has been uploaded to your web site, the Skicow API can be integrated into you web page by following these steps:

Add a Javascript tag to include the appropriate Skicow API Javascript.
Add a Javascript statement to identify the location where you uploaded the SkicowAPIProxy.php file to.
(Optional) Add Javascript statements to specify the styling of various aspects of the rendered Skicow search elements.
(Optional) Add Javascript statements to specify how to layout the Skicow search results.
(Optional) Add Javascript statements to localize the Skicow search.
Add a Javascript statement to create the Skicow search.

Here is some example code showing you how to embed a Skicow search without using an IFRAME:

    // Step 1: Include Skicow API Javascript.
    <script src="http://www.skicow.com/api/SkicowAPI.php?api_version=1.3&iframe=false&key=your_key"
            type="text/javascript">
    </script>

    <script type="text/javascript">
    function initializeSkicowMashup() {
      if (skicowBrowserIsCompatible()) {
        // Step 2: Identify location of proxy.
        skicow_api_proxy_url = "http://your_domain/optional_path/SkicowAPIProxy.php";

        // Step 3: Specify the how to layout the Skicow search results.
        ski_area_and_resort_results_side_by_side = true;

        // Step 4: Localize the search.
        setRegionSearchButtonLabels("Search");

        // Step 5: Create the search (note the references to the <div> elements below).
        createSearchForm(
          "skicowSearchFormContainerId",
          "skicowSkiAreaResultsContainerId",
          "skicowResortResultsContainerId");

        // Step 6: Style the Skicow search (note that this must be done after the form is created).
        setSearchFormStyle("textAlign", "left");
        setSearchFormStyle("background", "MintCream");
        setSearchFormLabelsStyle("color", "#1B57B1");
        setRegionSearchButtonLabels("Search");
        setSearchFormHeadersStyle("color", "#1B57B1");
        setSearchFormHeadersStyle("fontWeight", "bold");
        setSearchFormTextFieldStyle("background", "MintCream");
        setSearchFormSelectStyle("background", "MintCream");
        setSearchFormCheckboxStyle("background", "MintCream");
        setSkiAreaResultsContainerStyle("background", "GhostWhite");
        setAccommodationResultsContainerStyle("background", "GhostWhite");
        setSkiAreaLinkStyle("color", "#1B57B1");
      }
    }
    </script>
  </head>
  <body onload="initializeSkicowMashup()">
    <div id="skicowSearchFormContainerId" style="width: 100%"></div>
    <div style="height: 20px" style="clear: both"></div>
    <table border="1px" bordercolor="black" cellpadding="0px" cellspacing="0px">
      <tr valign="top">
        <td>
          <div id="skicowSkiAreaResultsContainerId">
          </div>
        </td>
        <td>
          <div id="skicowResortResultsContainerId">
          </div>
        </td>
      </tr>
    </table>

Note in the above example that the parameter iframe=false is necessary to ensure the Javascript code downloaded to the web browser in the correct form.

Note also that you do not need to explicitly identify elements to contain the ski area and resort search results. In such cases, the code at step 6 above would be replaced by the following code and the corresponding <div> elements would not be required in your page:

  // Step 6: Create the search (note the references to the <div> elements below).
  createSkicowSearch("skicowSearchFormContainerId");

Refer to SkicowAPIExampleSimple.htm and SkicowAPIExampleMultiColumn.htm for complete examples of this approach.

Styling

The Skicow search can be styled when using the Skicow API proxy only (refer to Embedding Skicow Searches without an IFRAME). This is because styling involves making a series a Javascript calls to specify style classes and apply the styles.

Various Javascript functions are provided by the Skicow API to help customize the styling of the Skicow search. The functions provided have the following form:

  setSearchFormStyle(styleName, styleValue);
  setSearchFormHeadersStyle(styleName, styleValue);
  setSearchFormTextFieldStyle(styleName, styleValue);
  setSearchFormSelectStyle(styleName, styleValue);
  setSearchFormCheckboxStyle(styleName, styleValue);
  setSearchFormButtonStyle(styleName, styleValue);
  setSkiAreaResultsContainerStyle(styleName, styleValue);
  setAccommodationResultsContainerStyle(styleName, styleValue);
  setSkiAreaLinkStyle(styleName, styleValue);
  setAccommodationLinkStyle(styleName, styleValue);

Calls to these functions must be made after the search form is created. For example, here is an example of a typical call sequence:

  createSearchForm(
    "skicowSearchFormContainerId",
    "skicowSkiAreaResultsContainerId",
    "skicowResortResultsContainerId");
  setSearchFormStyle("textAlign", "center");
  setSearchFormSelectStyle("background", "red");

Note: When setting style attributes, please make sure you use the CamelCase form for style attribute names. Referring to the above example, the text alignment property is specified as textAlign (as opposed to text-align for style sheet syntax). For further information on style attributes, refer to CSS2 Properties at www.w3.org.

Refer to SkicowAPIExampleStyling.htm for an example of customizing the styles of your Skicow searches.

Link Targets

Link targets refers to the target attributes of hyperlinks in search results. Alternate link targets can be specified when using the Skicow API proxy only (refer to Embedding Skicow Searches without an IFRAME). This is because the provision of link alternate targets requires Javascript calls to the Skicow API.

By default, link tagets are not set for hyperlinks. This means the default behavior of hyperlinks is to load the links page in the same window containing the hyperlink. To change this behaviour, simply specify an alternate link target as follows:

  result_link_target = xxx;

where xxx is one of the following string values:

"_blank"
"_parent"
"_self"
"_top"

For an explanation of these values, refer to the section on links at www.w3.org.

Restricting Searches to Specific Regions

There are many cases where you may wish to restrict the Skicow search to specific regions. This is done by calling the Javascript method addTopLevelRegion, passing the ID of the region to add. These calls must be made prior to the call to create the Skicow search (using either createSkicowSearch or createSearchForm).

The following is a list of various Javascript constants declared by the Skicow API identifying the various region IDs:

AFRICA_REGION_ID
ASIA_EXCLUDING_JAPAN_REGION_ID
AUSTRALIA_REGION_ID
CANADA_REGION_ID
EUROPE_REGION_ID
JAPAN_REGION_ID
NEW_ZEALAND_REGION_ID
SOUTH_AMERICA_REGION_ID
UNITED_STATES_REGION_ID
AUSTRIA_REGION_ID
FRENCH_ALPS_REGION_ID
SWITZERLAND_REGION_ID

Refer to SkicowAPIExampleMultiRegion.htm for an example of restricting your Skicow searches to specific regions.

Localization

The Skicow search can be localized when using the Skicow API proxy only (refer to Embedding Skicow Searches without an IFRAME). This is because localization involves making a series a Javascript calls to provide alternative values to various Javascript variables used by the Skicow API.

To localize the Skicow search, assign alternate text to any of the following variables prior to the call to create the search form:

criteria_header_text (default is "Criteria")
search_ski_areas_label_text (default is "Search ski areas")
alpine_skiing_label_text (default is "Alpine skiing")
snowboarding_label_text (default is "Snowboarding")
search_accommodation_label_text (default is "Search ski accommodation")
childcare_label_text (default is "Childcare")
search_button_label_text (default is "Search")
dont_care_option_text (default is "Don't Care")
yes_option_text (default is "Yes")
no_option_text (default is "No")

Browser Compatibility

The Skicow API has been tested on various browsers including, Internet Explorer, Firefox, Opera and Safari.

The Javascript function skicowBrowserIsCompatible() is provided to help identify incompatible browsers, however, there is no automated alternate behavior provided when incompatible browsers are detected.

Callbacks

The Skicow API provides the ability for you to specify a function (written by you) to be called back following the completion of each search. Refer to the following example:

  function initializeSkicowMashup() {
    if (skicowBrowserIsCompatible()) {
      // all initialisation code not shown here
      handle_results_callback_function_name = "handleSearchResults";
      createSearchForm(
        "skicowSearchFormContainerId",
        "skicowSkiAreaResultsContainerId",
        "skicowResortResultsContainerId");
    }
  }
  function handleSearchResults(numAccommodationItemsFound, numSkiAreasFound) {
    // Ensure the results table is displayed...
    var resultsTable = document.getElementById("resultsTable");
    resultsTable.style.display = "block";
  }

Skicow API Versions

The Skicow API is versioned to allow upgrades to be made without comprimising compatibility with existing users. Refer to the api_version parameter in the Skicow API URLs in the example code provided. The current stable version is 1.3.

Examples

The following examples show how to use the Skicow API:

Simple using an IFRAME: Shows how to use the Skicow API by declaring an IFRAME.
Simple using a proxy: Shows the equivalent of the previous example using a proxy instead of the IFRAME.
Multi column: Shows how to specify where results are placed on a page.
Region restriction: Shows how to restrict searches to specific region(s).
Styling: Shows how to specify styles.
Localization: Shows how to localization the Skicow API.

Installing the Proxy

Please refer to Proxy Installation Procedure to install the Skicow API proxy on your website.

Last Updated ( Friday, 07 November 2008 )

Comments:

Your Comments:

Have you any got anything to say about this article? Skicow would appreciate your comments.

Add a comment.

Submit a Link

Skicow.com welcomes you to submit links to relevant pages on the net.Relevant links on this page are those that specifically relate to this article (Skicow API Developer Guide). Note that you can also submit links from pages that relate to specific regions and ski resorts. To ensure only quality links are provided, you must log in first. If you don't have an account yet you will need to register for one.

Login

Skicow API Developer Guide

Table of Contents

What is the Skicow API