For utviklere
"Levert av Bring" er en løsning hvor Bring leverer et ferdig skjema for valg av fraktalternativ som HTML. HTML-koden leveres slik at den enkelt kan stilsettes (med CSS) til den enkelte nettbutikks layout. Lengre ned på siden finnes eksempel på et stilark som kan brukes til å stilsette bildet for valg av frakt.
HTML-koden fra tjenesten er levert som innholdet i en form, men uten selve <form>-taggene. Dette er gjort slik at skjemaets oppførsel kan spesifiseres for hver enkelt nettbutikk.
Av sikkerhetsmessige årsaker er ikke prisen med som en parameter i skjemaet når det sendes. Prisen må derfor hentes i etterkant. Dette gjøres enklest ved å benytte seg av XML-APIet med de samme parametrene som ble brukt til å hente HTML-koden.
Eksempel: Dersom fraktalternativet A-POST ble valgt i skjemaet fra http://fraktguide.bring.no/fraktguide/products.html?from=7600&to=1473&weightInGrams=1000&date=2009-02-26, kan prisen enkelt finnes ved å kalle XML-APIet på http://fraktguide.bring.no/fraktguide/products/A-POST/price.xml?from=7600&to=1473&weightInGrams=1000&date=2009-02-26.
Merk at parametrene til tjenesten er de samme for XML og HTML.
Å komme i gang med Levert av Bring består altså av disse enkle stegene:
- Lag <form>-tagger for bildet for valg av frakt.
- Legg inn et kall til Levert av Bring der skjemaet skal vises. Pass på at HTML-koden beholdes intakt av eventuelle rammeverk.
- Lag stilskjema for å få siden til å se ut som ønsket. Bruk gjerne eksempel-CSS fra lengre ned på denne siden.
- Ta i mot valgt produkt på siden skjemaet postes til og hent prisen.
Anbefaling til utvikler
- Legg med HTTP header "User-Agent" når du kaller tjenesten. Få med navnet på nettbutikken og gjerne også navnet på nettbutikkleverandøren dersom det er relevant.
- Vi anbefaler at du legger på feilhåndtering for å håndtere situasjonen dersom Fraktguiden ikke svarer eller svarer med feilmelding. Legg på en timeout og håndter feil på en måte som er tilfredsstillende for din nettbutikk.
Adresse og parametre til HTML koden
URL til den leverte HTML-koden finner du nede til venstre inne på menypunktet "Prøv tjenesten: Velg frakt".
Du kan bruke samme parametere til products.html som du kan til XML API ressursene. Teknisk sett er products.html en REST-ressurs på samme måte som de som er definert i XML API.
Stilsetting med CSS (obligatorisk)
CSS (Cascading Style Sheet) benyttes i HTML for å styre det visuelle uttrykket på siden. Lag gjerne din egen layout eller bruk/tilpass vårt eksempel:
/*
CSS for Levert av Bring - Velg Fraktalternativ
Denne filen kan kopieres og tilpasses til den enkelte brukers behov.
*/
#bringFrakt { width: 650px; font-family: Arial, Tahoma, sans-serif; font-size: 13px; }
#bringFrakt table { width: 100%; }
#bringFrakt th { font-weight: bold; padding: 7px; }
#bringFrakt td { padding: 1px 5px 2px 7px; background-color: #f5f5f5; vertical-align: top;}
#bringFrakt .bringHeaderRow th { padding-top: 25px; vertical-align: bottom; }
#bringFrakt .bringFraktHovedkategori { font-size: 15px; text-align: left; }
#bringFrakt .bringFraktUnderkategori { padding-top: 3px; padding-bottom: 3px; }
#bringFrakt .bringFraktvalg label { font-weight: bold; }
#bringFrakt .bringFraktvalg .bringFraktvalgRadio { margin-right: 5px; }
#bringFrakt .bringFraktvalg .bringFraktvalgdetaljer { margin: 6px 0 8px 16px; padding: 6px; background-color: #ffffff; }
#bringFrakt .bringFraktvalgPris { width: 9ex; text-align: center; }
#bringFrakt .bringFraktvalgAnkomstdato { width: 12ex; text-align: center; }
#bringFrakt .bringFraktvalgMiljobelastning { width: 15ex; text-align: center; }
#bringFrakt .bringFraktvalgTips { color: #ff9900; font-weight: bold; width: 18ex; text-align: center; font-size:smaller; }
#bringFrakt .bringHelpIconCell { padding-top: 4px; width: 1ex; }
#bringFrakt .bringHelpBox { display: none; }
#bringFrakt .bringSelectedPostautomatInfo { margin: 7px 0px 7px 16px; padding: 6px; background-color: #ffffff; }
#bringFrakt #bringPopUpPostautomatButton { padding: 0px 3px 0px 3px; font-size: 11px; margin-left: 16px; width:auto; overflow:visible;}
#bringFrakt #bringPopUpValgfrittPostkontorButton { padding: 0px 3px 0px 3px; font-size: 11px; margin: -5px 0 5px 16px; width:auto; overflow:visible;}
#bringFrakt .bringSelectedPostautomatInfoLine { margin-bottom: 6px; }
#bringFraktTooltip .bringHelpText { width: 300px; font-size: small; font-family: Arial, Tahoma, sans-serif; }
#bringFraktTooltip { position: absolute; z-index: 3000; border: 2px solid #919195; background-color: #ffffff; padding: 15px; opacity: 1; }
#bringFraktTooltip h3, #bringFraktTooltip div { margin: 0; }
Direkte lenke CSS eksempel: /fraktguide/css/fraktalternativer.css
Legge på tooltips med Javascript (anbefales)
HTML kildekoden som leveres av Bring har blokker med hjelpetekst på hvert fraktalternativ. Bruker man standardstilsettet (se over) er disse hjelpetekster usynlige. Anbefalingen er imidlertid at disse vises som tooltips på siden.
Vi anbefaler å benytte jQuery og jQuery Tooltip plugin for å vise tooltips på hvert fraktalternativ. Man kan evt. bruke plain JavaScript eller at annet JavaScript rammeverk for å vise tooltips. Man kan også vise denne informasjonen inline på siden dersom man ønsker dette (altså ikke som tooltip).
Eksempel med jQuery og jQuery tooltip plugin:
Følgende kodeblokk legges på samme side som viser fraktalternativ-skjemaet som er levert av Bring:
<!-- Start - Add Bring Fraktguide Tooltips with jQuery -->
<script type="text/javascript">
$(document).ready(function() {
//insert help icon (can be any icon)
$(".bringHelpTrigger").html(
'<img class="bringHelpImage" src="' + document.location.protocol + '//fraktguide.bring.no/fraktguide/images/helpGrey.png"/>'
);
//help icon -> set mouse cursor to help
$(".bringHelpImage").css(
{'cursor' : 'help'}
);
//bringHelpTrigger is span element with produkt ID --> insert the tooltip callback function:
$(".bringHelpTrigger").tooltip({
bodyHandler: function() {
tooltipBodyLocator = "#" + $(this).attr("id") + "_body";
return $(tooltipBodyLocator).html();
},
showURL: false,
id: 'bringFraktTooltip'
});
});
</script>
<!-- End - Bring Fraktguide Tooltips with jQuery -->
JavaScript som må lastes (script legges på lokal server):
<!-- Add Bring Fraktguide Tooltip JavaScript --> <script src="/js/jquery-1.3.2.min.js" type="text/javascript"></script> <script src="/js/jquery.tooltip.min.js" type="text/javascript"></script>
Håndtering av postautomat
Hvis man eksplisitt inkluderer produktet POSTAUTOMAT_NEXTDAY i spørringen mot tjenesten, vil HTML som leveres inneholde en "Velg postautomat" knapp. På denne må man legge på kode som håndterer klikk på knappen og sørge for å åpne popupvindu for å velge postautomat. Eventuelt kan samme logikk benyttes når man velger produktet uten å ha valgt en postautomat først. Vi anbefaler å benytte jQuery for å legge på popup-logikk på knappen. Man kan evt. bruke et annet JavaScript-rammeverk.
Eksempelkoden forutsetter at man har lest Postautomat - For utviklere. Eksempelkoden under følger disse retningslinjene og er tilpasset Levert av Bring HTML-koden.
Eksempel på postautomathåndtering med jQuery:
<!-- Start - Add Velg Postautomat popup handling with jQuery -->
<script type="text/javascript">
$(document).ready(function() {
//define function to invoke when postautomat radio button is clicked:
$("#bringPostautomatRadio").click(function() {
if ($(".bringSelectedPostautomatInfoLine").length == 0) {
//no previous selection, pop up window:
bringPopUpPostautomat($(this).attr("bringPopupUrl"));
}
});
});
//function invoked by both radio and input button:
function bringPopUpPostautomat(url) {
//convert callbackUrl to https if page was loaded with https
if ("https:" == document.location.protocol && url.indexOf("callbackUrl=http:") >= 0) {
url = url.replace("callbackUrl=http:", "callbackUrl=https:")
}
//open popup:
day = new Date();
id = day.getTime();
eval("page" + id + " = window.open(url, '" + id + "', 'toolbar=0,scrollbars=1,location=0,statusbar=1,menubar=0,resizable=1,width=690,height=680,left=160,top=50');");
}
function updatePostautomatValg(productCode, machineId, machineName, address, postalCode, city, locationDescription, bookingNumber, shippingDate, correlationId) {
//populate form with result from popup:
$("#bringSelectedPostautomatBox").html("<div class='bringSelectedPostautomatInfo'><div class='bringSelectedPostautomatInfoLine'>" + machineName + ", " + address + ", " + city + "</div><div class='bringSelectedPostautomatInfoLine'>" + locationDescription + "</div></div>");
$("#bringPopUpPostautomatButton").val("Endre postautomat");
$("#bringPostautomatRadio").click();
//in addition, some hidden fields could be populated.
}
</script>
<!-- End - Velg Postautomat popup handling with jQuery -->
