Was this helpful?
The Alpaca Toolkit provides a method of integrating assets provided by Alpaca Travel. These assets include various prebuilt area guides, maps and itinerary layouts.
Using the below script examples, you can configure the behaviour and content
using data attributes. The examples load an itinerary and an area guide into the
alpaca-container div. You can style CSS for the presentation of the elements
as appropriate for your site.
Example: Presenting an itinerary using a script tag
The below example will draw an itinerary onto the page of your site. The
specific itinerary is configured by changing the data-id data attribute on the
script tag. The data-view-mode attribute can configure the layout presentation
that is used to present the asset. The data-container-id will configured 
which div to replace the contents with the asset once it is ready. Finally, the
data-inline data attribute will load the asset on page, allowing it to share
the local storage access (opposed to using an iframe to seperate).
1<!-- Example of configuring script -->
2<div class="alpaca-wrapper alpaca-itinerary">
3 <div id="alpaca-container">
4 <!-- Recommended: Add you strategy here for the loading presentation -->
5 <span class="loading">Loading...</span>
6 </div>
7 <script
8 src="https://cdn.alpacamaps.com/scripts/alpaca-widget@v2.js"
9 data-id="journey/94d8276c-fd26-11ea-96fe-067ec0c7e8f4"
10 data-view-mode="article"
11 data-container-id="alpaca-container"
12 data-inline="true"
13 ></script>
14</div>Example: Presenting an area guide using a script tag
The below example places an area guide on the page, as defined by the data-id
data attribute. It is configured to run inline, necessary to operate the asset
on the same domain to share the local storage access. The content will load into
the alpaca-container div once the application has downloaded and is ready to
boot.
This example also passes through some query parameters, in order to filter the content to a specific state of the application.
1<!-- Example of configuring script -->
2<div class="alpaca-wrapper alpaca-area-guide">
3 <div id="alpaca-container">
4 <!-- Recommended: Add you strategy here for the loading presentation -->
5 <span class="loading">Loading...</span>
6 </div>
7 <script
8 src="https://cdn.alpacamaps.com/scripts/alpaca-widget@v2.js"
9 data-id="locale/wine-australia"
10 data-container-id="alpaca-container"
11 data-inline="true"
12 data-query-params="tags:prefilter=_appointment_only"
13 ></script>
14</div>Example: Advanced customisation of base URL's and API links
In certain circumstances, you may be advised to change the URL's that are being used for the toolkit to communicate with. These could be to do with changing the domain for custom domains, or changing API targets for preview releases.
1<!-- Example of configuring script with changing URL endpoints -->
2<div class="alpaca-wrapper alpaca-area-guide">
3 <div id="alpaca-container">
4 <!-- Recommended: Add you strategy here for the loading presentation -->
5 <span class="loading">Loading...</span>
6 </div>
7 <script lang="text/javascript">
8 // Modify the API URL for the content
9 var API_URL = 'https://embed.alpacamaps.com/api/v1'; // Default
10 // Modify the v2 API URL for the trip planning
11 var ALPACA_API_URL_V2 = 'https://withalpaca.com/api/v2'; // Default
12 </script>
13 <script
14 src="https://cdn.alpacamaps.com/scripts/alpaca-widget@v2.js"
15 data-id="locale/wine-australia"
16 data-container-id="alpaca-container"
17 data-inline="true"
18 data-base-url="https://made.withalpaca.com/"
19 ></script>
20</div>Assets can be enabled to provide itinerary planning features within the JavaScript application. You can integrate and share the itinerary planning features more broadly into the application via GraphQL.
You can leverage Itinerary GraphQL functions within your website application
You need to read/write to the local storage key detailed here in order to have the assets and your website application kept in sync
Example integrations
Full functioning Itinerary Creation, including simple lists and automatically routed itineraries
Create "Add to Itinerary" buttons on your website application that can determine whether a place is present within an itinerary
Show the number of places added to a users itinerary
Present a list of the places added to the itinerary
Add, remove and reorder places
Automatically create routes between an itinerary
Requirements You must be using the script tag with "inline=true" in order to leverage this feature. This is required due to the shared local storage, which is used to store the selected itinerary ID's.
Alpaca assets access the reference to the current itinerary being edited via the
local storage key alpaca:add-to-itinerary:itinerary:ref:selected. The value of
this must be in the format of alpaca://<itinerary-id>, such as:
alpaca://itinerary/62rrSQLRqmPcER0YTQr2g1
You can listen to local storage events in order to obtain the reference to the itinerary as it is created.
Read the created itinerary from the localStorage key 
alpaca:add-to-itinerary:itinerary:ref:selected on load to obtain any 
itinerary that is in progress
Add an event handler to the window.localStorage so that if a new itinerary is started in the asset, you will also then have access to the ID
Push any newly created itineraries made outside the asset to local storage so that the asset also can use the itinerary.
As an example gist, the below provides a basic javascript event handler for subscribing to the local storage to obtain the created itinerary.
1// Create a window variable in sync with the current itinerary
2var itineraryId = null;
3
4// Local storage key for accessing the current selected itinerary
5var localStorageKey = "alpaca:add-to-itinerary:itinerary:ref:selected";
6// Local storage key for accessing all the known itineraries (multiple list)
7var localStorageKeyList = "alpaca:add-to-itinerary:itinerary:refs:known";
8
9/**
10 * Obtain the current value of local storage for the selected itinerary
11 */
12function getLocalStorageItineraryId() {
13 // Access the current itinerary ref from the local storage
14 try {
15 // Update the local variable
16 var localStorageItineraryRef = window.localStorage.getItem(localStorageKey);
17 if (typeof localStorageItineraryRef === "string") {
18 return localStorageItineraryRef.replace("alpaca://", "");
19 }
20 } catch (err) {
21 // There is an issue accessing the window local storage (SecurityError)
22 console.warn(err);
23 }
24 return null;
25}
26
27/**
28 * Set the local storage itinerary to a supplied itinerary ID
29 * @param {string|null} id ID of the itinerary to set into local storage
30 */
31function setLocalStorageItineraryId(id) {
32 try {
33 // Correct the ID to be a ref
34 var ref = (() => {
35 if (typeof id === "string") {
36 return "alpaca://" + id.replace("alpaca://", "");
37 }
38 return null;
39 })();
40
41 // Set the itinerary ID reference into local storage
42 window.localStorage.setItem(localStorageKey, ref);
43 } catch (e) {
44 // Error handling...
45 console.error(e);
46 }
47}
48
49// Add an event listener to local storage to update our local variable
50window.addEventListener("storage", () => {
51 // When the local storage is updated, keep it in sync
52 var localStorageItineraryRef = getLocalStorageItineraryId();
53 if (localStorageItineraryRef !== itineraryId) {
54 itineraryId = localStorageItineraryRef;
55 // You can do something else with the updated itinerary ID here...
56 // callMyFunc(...)
57 }
58});
59
60// Set the itinerary ID when we boot
61itineraryId = getLocalStorageItineraryId();Alpaca also triggers custom events on the window that you can subscribe and observe. These are triggered by the application when certain events happen, and can bne an alternative to listening to the storage layer.
1// Create an event handler to listen to events from Alpaca
2function alpacaEventHandler(event) {
3 var method = event.detail.method;
4
5 console.log("Caught an event, such as createItinerary or deleteItinerary");
6}
7
8// Register to the window as the event target
9window.addEventListener("alpaca", alpacaEventHandler);Copyright © 2024 - Made with love ❤️ in Australia.