---- dataentry snippet ----
type          : snippet #do not change this line
category      : shipping #mention the category like 'shipping', 'checkout' etc
name          : Live Rate Shipping Modification #the name of the snippet
description   :  #description about snippet
versions_tags : 0.6.0, 0.7.0, 0.7.1, 0.7.2, 1.0, 1.1 #compatible versions
reference_url : http://forum.foxycart.com/comments.php?DiscussionID=3132&page=1 #Item_0            # External link
tags_tags     : snippets, shipping, advance #tags, separated by commas.
date_dt       : 2011-05-25 #the date in YYYY-MM-DD format
----
====== Live Rate Shipping Modification  ======

<WRAP center round important 80%>
**Versions 0.7.1 and older**: Note that applying javascript shipping modifications using either live or flat rates where you are setting custom values has been found to not work as expected for subscription based products where you need the shipping to apply to each subscription renewal. A fix is in place for versions 0.7.2 and newer.
</WRAP>

<WRAP center round important 80%>
**Using version 2.0?** There is a new snippet available for our latest version, [[v:2.0:snippets:live_rate_shipping_modification|available from here]].
</WRAP>
<WRAP center round important 80%>
**Using Multiship?** Unfortunately this snippet is only designed to work with single ship stores.
</WRAP>


The following functionality allows you to add, update and remove any number of live rate shipping options based on any criteria (eg: what categories are products in, total cost of the cart, shipping destination country). <wrap hi>This script is limited to live rate shipping only.</wrap>

<wrap important>The functionality described on this page require advanced javascript knowledge, and are not officially supported.</wrap> They are included in our official wiki because certain shipping methods and functionality are not natively supported, and though we are working on radically improving our shipping functionality, in the meantime these methods may be great workarounds. Use with caution, test, and post in [[http://forum.foxycart.com/|our forum]] if you run into problems.

See the [[#changelog|changelog]] for details on updates to this script.
==== Step 1: Update Categories and Shipping ====

Update categories to 'Shipped using live rates' and select any relevant live rate options from the 'shipping' page.

==== Step 2: Add Javascript ====

Add the following right before the closing ''</head>'' tag in your checkout template:

<code javascript><script type="text/javascript" charset="utf-8">
  //<![CDATA[
 
  FC.customLiveShipping = {}
 
  FC.customLiveShipping.config = {
    autoSelect: false  // Set to true if you'd like the top shipping option to be automatically selected for the user
  };
 
  FC.customLiveShipping.logic = function() {
    /* BEGIN CUSTOM SHIPPING LOGIC */
 
 
 
    /* END CUSTOM SHIPPING LOGIC */
  }
 
  //]]>
</script>
 
<script type="text/javascript" charset="utf-8">
  //<![CDATA[
  /* Live Rate Shipping Modification Logic v1.3 */
 
  jQuery(document).ready(function() {
    jQuery(document).ajaxComplete(function(event, request, settings) {
      if (settings.url.indexOf('GetShippingCost') != -1) {
        FC.customLiveShipping.execute();
      }
    });
    
    if (FC.checkout.config.postedCheckout && FC.checkout.config.shippingServiceId > 0) {
      FC.customLiveShipping.execute();
    }
  });
 
 
  /**
   *  PUBLIC FUNCTIONS
   *  Use these functions to modify the returned live rates
   */
 
  FC.customLiveShipping.add = function(code, cost, carrier, service) {
    var newShippingOption = '<label for="shipping_service_' + code + '" class="fc_radio"><input type="radio" class="fc_radio fc_required" value="' + code + '|' + cost + '" id="shipping_service_' + code + '" name="shipping_service" onclick="FC.checkout.updatePrice(-1)" /><span class="fc_shipping_carrier">' + carrier + '</span><span class="fc_shipping_service">' + service + '</span><span class="fc_shipping_cost">' + FC.formatter.currency(cost, true) + '</span></label>';
    jQuery("#fc_shipping_methods_inner").append(newShippingOption);
  }
 
  FC.customLiveShipping.hide = function(selector) {
    if (typeof(selector) != "number") {
        FC.customLiveShipping.alterShippingOptions(FC.customLiveShipping.hide, selector);
    } else {
        jQuery("label[for=shipping_service_" + selector + "]").hide();
    }
  }
 
  FC.customLiveShipping.show = function(selector) {
    if (typeof(selector) != "number") {
        FC.customLiveShipping.alterShippingOptions(FC.customLiveShipping.show, selector);
    } else {
        jQuery("label[for=shipping_service_" + selector + "]").show();
    }
  }
 
  FC.customLiveShipping.update = function(selector, modifier) {
    if (typeof(selector) != "number") {
        FC.customLiveShipping.alterShippingOptions(FC.customLiveShipping.update, selector, modifier);
    } else {
        var rateAttributes = FC.customLiveShipping.getShippingAttributes(jQuery("input#shipping_service_" + selector)),
        price = FC.customLiveShipping.modifyPrice(rateAttributes.price, modifier);
        jQuery("input#shipping_service_" + selector).val(selector + '|' + price).siblings("span.fc_shipping_cost").html(FC.formatter.currency(price, true));
    }
  }
 
  FC.customLiveShipping.remove = function(selector) {
    if (typeof(selector) != "number") {
        FC.customLiveShipping.alterShippingOptions(FC.customLiveShipping.remove, selector);
    } else {
        jQuery("label[for=shipping_service_" + selector + "]").remove();
    }
  }
 
  FC.customLiveShipping.reset = function() {
    FC.checkout.updateShipping(-1);
  }
 
 
  /**
   *  PRIVATE FUNCTIONS
   *  These aren't the droids you're looking for
   */

  FC.customLiveShipping.execute = function() {
    if (!jQuery("#fc_shipping_methods_inner input[type='radio']:first").data("custom-shipping-logic-applied")) {
      FC.customLiveShipping.logic();
 
      if (FC.customLiveShipping.config.autoSelect) {
        jQuery("#fc_shipping_methods_inner input[type='radio']:first").attr("checked", "checked");
      }
 
      // Remove hidden rates - they're obviously not needed
      jQuery("#fc_shipping_methods_inner label[for^='shipping_service']:hidden").remove();
 
      FC.checkout.updatePrice(-1);
 
      // Set the inputs to be marked as updated, to prevent it being run twice.
      jQuery("#fc_shipping_methods_inner input[type='radio']").data("custom-shipping-logic-applied", true);
    }
  }
 
  FC.customLiveShipping.alterShippingOptions = function(func, selector, modifier) {
    if (typeof(selector) == "number") {
      // They've just provided a rate code, pass them on.
      func.call(null, selector, modifier);
 
    } else if (typeof(selector) == "string") {
      // It's a string, must be a combination of carrier and service or all
      var rates = [];
      if (selector.toLowerCase() == "all") {
        // This applies to all returned rates
        rates = jQuery("#fc_shipping_methods_inner label[for^='shipping_service']");
      } else {
        // Some filter has been specified
        var regex = /(fedex|usps|ups)?\s?([\w\s]+)?/i,
            provider = regex.exec(selector);
 
        if (provider == undefined) return;
 
        var carrierSelector = "span.fc_shipping_carrier";
        if (provider[1] != undefined) {
          switch(provider[1].toLowerCase()) {
            case "fedex":
              carrierSelector = "span.fc_shipping_carrier:contains('FedEx')";
              break;
            case "usps":
              carrierSelector = "span.fc_shipping_carrier:contains('USPS')";
              break;
            case "ups":
              carrierSelector = "span.fc_shipping_carrier:contains('UPS')";
              break;
          }
        }
 
        if (provider[2] != undefined) {
          rates = jQuery("#fc_shipping_methods_inner label[for^='shipping_service'] "+carrierSelector).siblings("span.fc_shipping_service").filter(function() {
            return (jQuery(this).text().toLowerCase().indexOf(provider[2].toLowerCase()) > -1);
          }).parent();
        } else {
          rates = jQuery("#fc_shipping_methods_inner label[for^='shipping_service'] "+carrierSelector).parent();
        }
      }
 
      rates.each(function() {
        var rateAttributes = FC.customLiveShipping.getShippingAttributes(jQuery(this).children("input[name='shipping_service']"));
        func.call(null, parseInt(rateAttributes.id), modifier);
      });
 
    } else if (typeof(selector) == "object") {
      // Assume it's an array of codes
      for (var i in selector) {
        func.call(null, parseInt(selector[i]), modifier);
      }
    }
  }
 
  FC.customLiveShipping.getShippingAttributes = function(item) {
    if (typeof(item) == "number") {
      // Passed the code
      item = jQuery("input#shipping_service_" + item);
    }
 
    var carrier = "",
        service = "",
        inputVal = 0,
        id = 0,
        price = 0;
 
    if (item.length) {
      carrier = item.siblings(".fc_shipping_carrier").html(),
      service = item.siblings(".fc_shipping_service").html(),
      inputVal = item.val().split("|"),
      id = parseInt(inputVal[0]),
      price = parseFloat(inputVal[1]);
    }
 
    return {"carrier": carrier, "service": service, "id": id, "price": price};
  }
 
  FC.customLiveShipping.modifyPrice = function(price, modifier) {
    var modifier = modifier.toString(),
        regex = /([\+\-\=\*\/])?(\d+(?:\.\d+)?)(\%)?/,
        parts = regex.exec(modifier),
        price = parseFloat(price),
        modifyBy = parseFloat(parts[2]);

    if (parts[3] != undefined) {
      modifyBy = price * (modifyBy / 100);
    }
 
    var operator = (parts[1] == undefined) ? "=" : parts[1];
    switch(operator) {
      case "+":
        price = (price + modifyBy);
        break;
      case "-":
        price = (price - modifyBy);
        break;
      case "/":
        price = (price / modifyBy);
        break;
      case "*":
        price = (price * modifyBy);
        break;
      default:
        price = modifyBy;
    }
 
    return (price < 0) ? 0 : price;
  }
  //]]>
</script></code>
==== Step 3: Update Configuration ====

This script currently provides a single option to alter the way the script works

<code html>FC.customLiveShipping.config = {
  autoSelect: false
};</code>

  * ''autoSelect'': If set to true, the top option for rates will be automatically selected after your custom logic has run.

==== Step 4: Customise Shipping Options ====

Now the fun part, based on whatever criteria you want, add in the different shipping options you require for your site. Add your custom code between the ''/* BEGIN CUSTOM SHIPPING LOGIC */'' and ''/* END CUSTOM SHIPPING LOGIC */'' lines in the first script block. There are six functions available to you.

=== FC.customLiveShipping.add() ===
Adds an additional shipping option to the checkout.

**Parameters:** 
  * ''code'' //<wrap lo>(Number)</wrap>// - <wrap hi>Can not be the same as another rate</wrap>
  * ''cost'' //<wrap lo>(Number)</wrap>// - A number to two decimal places
  * ''carrier'' //<wrap lo>(String)</wrap>//
  * ''service'' //<wrap lo>(String)</wrap>//

**Example:** 
  * ''FC.customLiveShipping.add(100, 4.99, 'PostBox', 'Local Delivery');''
  * ''FC.customLiveShipping.add(125, 30, ' ', 'Standard Mail');''

**Notes:** Make sure that the code you give the added rate doesn't duplicate a code for a returned rate you've selected. We suggest just giving your custom added rates a high code number. Also, you don't have to provide both the carrier and the service parameters - but at least one of them is required.

----

=== FC.customLiveShipping.hide() ===

Hides one or many existing shipping options.

**Parameters:** 
  * ''selector'' //<wrap lo>(Number, String or Array)</wrap>// - Can be the code number of a rate, a string containing the carrier and the service (or a combination of) or an array of codes.

**Example:** 
  * ''FC.customLiveShipping.hide(1);'' - Will hide rate 1
  * ''FC.customLiveShipping.hide('all');'' - Will hide all rates
  * ''FC.customLiveShipping.hide('FedEx');'' - Will hide all rates for FedEx
  * ''FC.customLiveShipping.hide('Overnight');'' - Will hide all rates with a service name that contains 'Overnight'
  * ''FC.customLiveShipping.hide('USPS Express');'' - Will hide any rates from USPS that contain the word 'Express'
  * ''FC.customLiveShipping.hide([1,2,5,7]);'' - Will hide rates with codes 1,2,5 and 7

**Notes:** Any rates that are still hidden at the end of the custom logic block will be removed to prevent them being shown when you don't want them to. They will be returned if the shipping options are refreshed by an address change by the customer.

----


=== FC.customLiveShipping.show() ===

Shows one or many existing shipping options.

**Parameters:** 
  * ''selector'' //<wrap lo>(Number, String or Array)</wrap>// - Can be the code number of a rate, a string containing the carrier and the service (or a combination of) or an array of codes.

**Example:** 
  * ''FC.customLiveShipping.show(1);'' - Will show rate 1
  * ''FC.customLiveShipping.show('all');'' - Will show all rates
  * ''FC.customLiveShipping.show('FedEx');'' - Will show all rates for FedEx
  * ''FC.customLiveShipping.show('Overnight');'' - Will show all rates with a service name that contains 'Overnight'
  * ''FC.customLiveShipping.show('USPS Express');'' - Will show any rates from USPS that contain the word 'Express'
  * ''FC.customLiveShipping.show([1,2,5,7]);'' - Will show rates with codes 1,2,5 and 7

----


=== FC.customLiveShipping.update() ===

Updates the cost of one or many existing shipping options.

**Parameters:** 
  * ''selector'' //<wrap lo>(Number, String or Array)</wrap>// - Can be the code number of a rate, a string containing the carrier and the service (or a combination of) or an array of codes.
  * ''modifier'' //<wrap lo>(String or Number)</wrap>// - Can either be a number (which sets the price to match) or a string containing the operator and a number eg '' '+20' '', '' '-10' '', '' '*2' '', '' '/2.5' '', '' '=15' ''. You can also append the string with a ''%'' sign to make the operation based on a percentage, eg '' '+20%' '' - add 20%, '' '-20%' '' - less 20%, '' '/20%' '' - divide by 20%, '' '*20%' '' - multiply by 20%.

**Examples:** 
  * ''FC.customLiveShipping.update(1, 5);'' - Will set rate 1 to be $5
  * ''FC.customLiveShipping.update('all', '*2');'' - Will set all returned rates to double their returned cost
  * ''FC.customLiveShipping.update('FedEx', '+5');'' - Will set all rates for FedEx to be $5 more than what they returned as
  * ''FC.customLiveShipping.update('Overnight', '-5');'' - Will set all rates with a service name that contains 'Overnight' to be $5 less than returned
  * ''FC.customLiveShipping.update('USPS Express', '=6');'' - Will set any rates from USPS that contain the word 'Express' to be $6
  * ''FC.customLiveShipping.update([1,2,5,7], '/2');'' - Will set rates with codes 1,2,5 and 7 to be half their returned cost
  * ''FC.customLiveShipping.update('USPS', '+20%');'' - Will add 20% of the returned rate to each of the USPS rates

----

=== FC.customLiveShipping.remove() ===

Removes one or many existing shipping options.

**Parameters:** 
  * ''selector'' //<wrap lo>(Number, String or Array)</wrap>// - Can be the code number of a rate, a string containing the carrier and the service (or a combination of) or an array of codes.

**Example:** 
  * ''FC.customLiveShipping.remove(1);'' - Will remove rate 1
  * ''FC.customLiveShipping.remove('all');'' - Will remove all rates
  * ''FC.customLiveShipping.remove('FedEx');'' - Will remove all rates for FedEx
  * ''FC.customLiveShipping.remove('Overnight');'' - Will remove all rates with a service name that contains 'Overnight'
  * ''FC.customLiveShipping.remove('USPS Express');'' - Will remove any rates from USPS that contain the word 'Express'
  * ''FC.customLiveShipping.remove([1,2,5,7]);'' - Will remove rates with codes 1,2,5 and 7

----

=== FC.customLiveShipping.reset() ===

Resets the shipping options by re-requesting them from the FoxyCart servers

**Example:** 
  * ''FC.customLiveShipping.reset();''

**Notes:** This function should not need to be called from within your custom logic. However you may want to call this function on custom fields you have added to the checkout that may affect shipping costs - for example if you have a gift wrapping service that only allows for certain shipping services and adds a premium to the shipping cost.

----

=== How the selector works ===

In the ''show()'', ''hide()'', ''update()'' and ''remove()'' functions, you can specify a selector, which can be either a number, a string or an array. See the following for details of how they work:

  ; Number
  : **Description:** A selector for a single returned rate based on its code
  : **Example:** ''1'' or ''25''
  ; String
  : **Description:** A more complex selector that searches the carrier and service for matches, allowing you to select a variable amount of returned rates. While it's not case sensitive, the spelling obviously must match what is returned in the rates.
  : **Examples:**
    * '''all' '' - By specifying this string, all returned rates will be modified
    * '''fedex' '', '''ups' '', '''usps' '' - will select all rates for the specified carrier. Note that only one carrier can be specified in a selector
    * '''overnight' '', '''priority mail' '', '''2 day' '' - if the string does not match a carrier as above, it will be assumed it is a service, and will look for the string anywhere within it's service name. So if '''overnight' '' is specified, it would match a string of ''really quick overnight'' and ''overnight service''.
    * '''fedex priority overnight' '' - if both the carrier and the service filter is specified (the carrier must always be the first word, followed by a space, followed by the service string), then it will be filtered by both. Again '''fedex' '' will match against the carrier name, and the rest of the string provided will match against the service. In this example, the service matching would be looking for ''priority overnight'' within the service name.

  ; Array
  : **Description:** An array of numbers to select multiple rates by their code
  : ** Example:** ''[1,4,6,8]''
  
==== Examples ====

=== Example 1 ===

  - If the customer is shipping to the stores location, allow for pickup option, otherwise remove it
  - If the order is more than $100 and they are shipping within the US, allow for free shipping.

<code javascript>var state = (jQuery("#use_different_addresses").is(":checked") ? $("#shipping_state").val() : $("#customer_state").val());
var country = (jQuery("#use_different_addresses").is(":checked") ? $("#shipping_country").val() : $("#customer_country").val());

if (state != "NY") FC.customLiveShipping.remove("pickup");
if ((country == "US" && fc_json.total_price <= 100) || country != "US") FC.customLiveShipping.remove("free");</code>


=== Example 2 ===

  - If the customer has ordered products from the 'food' category, only show overnight delivery options
  - If the customer has ordered 3 or more food items, update the priority overnight option to be free

<code javascript>var food = 0;
for (p in fc_json.products) {
  switch (fc_json.products[p].category) {
    case "food":
      food += fc_json.products[p].quantity;
      break;
  }
}

if (food > 0) {
  // Hide all shipping options
  FC.customLiveShipping.hide('all');
  // Show only the overnight options
  FC.customLiveShipping.show('overnight');
  // If 3 or more food items, update priority overnight to be free
  if (food >= 3) FC.customLiveShipping.update('priority overnight', 0);
}</code>

=== Example 3 ===

  - Allow free shipping only if a certain coupon code is present. In this case, a coupon that contains the words "free shipping" (case insensitive).
  - This assumes you've enabled the 'free ground shipping' custom rate in your store's "shipping" settings.

<code javascript>
FC.customLiveShipping.hide('free');
if(fc_json.hasOwnProperty('coupons')) {
	jQuery.each(fc_json.coupons, function(i, coupon){
		if(coupon.name.search(/free shipping/i) > -1) {
			FC.customLiveShipping.show('free');
		}
	});
}</code>

=== Example 4 ===

  - Only allow free shipping if a certain number of products (more than 5 in this case) are ordered.
  - This assumes you've enabled the 'free ground shipping' custom rate in your store's "shipping" settings.

<code javascript>
FC.customLiveShipping.hide('free');
if(fc_json.product_count > 5) {
	FC.customLiveShipping.show('free');
}</code>
===== Related Forum Discussions =====

===== Changelog =====

  * 2012/03/30 - v1.0 - Initial version
  * 2013/01/29 - v1.1 - Added ability to modify by a percentage
  * 2013/03/19 - v1.2 - Updated ''ajaxComplete()'' to match changes made in jQuery 1.8
  * 2013/07/30 - v1.3 - Added code to run on page load if a shipping choice is already selected (ie: due to a gateway error)