SlatwallScope

In addition to the RESTful API the most common way that you will interate with Slatwall is via the SlatwallScope.  The SlatwallScope provides a single API for everything you could ever need.  Throughout these docs you will see numerious example and code samples that all reference the SlatwallScope so it is important to farmiliarize your self with the concepts below.

With this single API entry point and a convention based architecture, we are able to translate the SlatwallScope into many different languages so that you have native classes to work with on whatever programming language or combination of languages you might need.

 

Concepts

The entire API of functionality can be broken up into 3 simple concepts.  We will go into deeper detail of each concept in the sections below.

Conecpt Description
Current Session Data One of the key aspects of any eCommerce application is Session Management.  There are 2 top level entities involved with Slatwall's Session, the current account logged in & the current cart that a user might be adding items to before placing their order.
Public Processing This can be thought of as all the 'Actions' a user might take when on the fronted of an eCommerce website, or within a custom web/mobile application.  For Example; login, logou, addToCart, placeOrder, etc.
Data Access & Processing Lastly the SlatwallScope provides access to all of the underlying entities in the database.  This would include getting entity data, saving, deleting & various other processing methods.

 

SlatwallScope Types

While the SlatwallScope proviodes the conceptual functionality descibed above, it is also available in a variety of different langauges that have their own conceptual stipulations.

Language Description
CFML (Native)

This is the most powerful version of the API that provides access to the three concepts describe above as well as a handful of additional methods that are less comonly (if ever) needed.

All objects returned by the native SlatwallScope are fully functional entities.

In addition and unique to this version you have access to the underlying native application, services and DAO's

JavaScript

This version of the SlatwallScope is typically only used to retreive Current Session Data & Access to Public Processing Method.  You can choose to have your data returned as simple JSON objects, or lightweigth JavaScript helper objectes that provide convenience methods for lazily loading & processing data over the API.

While it is posible to have direct Data Access & Processing against the full data API using an AuthToken this is NOT RECOMMENDED. JavaScript is typically run from the public users machine which makes passing AuthToken required to the clients machine a completley unsecure process.  The only situation where it would make sense to use this feature would be on server-side JavaScript like Node.js

Language SDKs

Lastly there are a series of Language Specific SDK's that provide a SlatwallScope as a helper class to the RESTful API.  Again these version provide access to all 3 of the concepts above, and you can choose to have the data returned as simple JSON or lightweigth Language Specific helper classes that provide convenience methods for lazily loading & processing data over the API.

Setting Up The Slatwall Scope

Add overview and various code samples here to descibe how to instantiate the 3 various version of the SlatwallScope.

CFScript
// Added to your Application.cfc
// Make sure that the application has a mapping to the Slatwall Application
this.mappings["/Slatwall"] = "/FullPathToSlatwallInstallDirectory";
// Add Instantiation code to the onRequest method so that it runs on every page request
public any function onRequest() {
<!--- Add an application variable that connects your application to Slatwall --->
if(!structKeyExists(application, "slatwallFW1Application"){
application.slatwallFW1Application = createObject("component", "Slatwall.Application");
}
<!--- Actually Instantiate the SlatwallScope --->
application.slatwallFW1Application.bootstrap();
// Now request.slatwallScope should be available to your application on every request, lets perform a test dump
writeDump(var="#request.slatwallScope#", top="3");
}
Tag Based CFML
<!--- Added to your Application.cfc --->
<!--- Make sure that the application has a mapping to the Slatwall Application --->
<cfset this.mappings["/Slatwall"] = "/FullPathToSlatwallInstallDirectory" />
<!--- Add Instantiation code to the onRequest method so that it runs on every page request --->
<cffunction name="onRequest">
<!--- Add an application variable that connects your application to Slatwall --->
<cfif not structKeyExists(application, "slatwallFW1Application")>
<cfset application.slatwallFW1Application = createObject("component", "Slatwall.Application") />
</cfif>
<!--- Actually Instantiate the SlatwallScope --->
<cfset application.slatwallFW1Application.bootstrap() />
<!--- Now request.slatwallScope should be available to your application on every request, lets perform a test dump --->
<cfdump var="#request.slatwallScope#" top="3" />
</cffunction>
<!-- Be sure to add this before any code that would use the slatwall scope -->
<script type="text/javascript" src="http://www.mySlatwallServer.com/slatwall.js"></script>
<script type="text/javascript">
// Output the SlatwallScope so that we can know it was setup correctly
console.log( SlatwallScope );
</script>
package org.slatwall.slatwallscope;
// Import the Slatwall Java SDK
import java.io.File;
import java.util.*;
import com.slatwall.client.*;
import com.slatwall.slatwallscope.api.*;
import com.slatwall.slatwallscope.model.*;
import com.slatwall.slatwallscope.authentication.*;
/*
* Instantiate the SlatwallScope API with the following arguments:
* @param String serverURL The URL of the Slatwall Service that hosts your API
* @param SlatwallAuthToken authToken (optional) The auth token that you have generated for your account on the server
*/
public class SlatwallScopeAPIService throws APIException {
//Set your baseUrl.
String serverUrl = "https://www.mySlatwallService.com/";
//Instantiate the API and test some endpoints.
try {
/**
* To GET a Slatwall Object
**/
/** instantiate the API helper */
SlatwallScope slatwallScope = new SlatwallScope( serverUrl, new SlatwallAuthToken(205c1fd430fb4588bf5a5b82a03fe1af) );
/** Display the configuration */
System.out.println(slatwallScope.getConfig().toString());
/** Test getting an account */
SlatwallEntity[] accountList = slatwallScope.getAccounts();
System.out.println(accountList.toString()); //<--should be json string containing all Slatwall accounts
/** Once you have a list of accounts, you can iterate through them getting individual accounts by accountID. */
for (SlatwallEntity account : accountList){
SlatwallEntity accountData = slatwallScope.getAccount(account.accountID);
if (!accountData['firstName'].isEmpty() && !accountData['lastName'].isEmpty()){
/** display the account information */
System.out.println("Account: " + accountData.firstName + " " + accountData.lastName);
}
}
/**
* To UPDATE a model object, you populate a SlatwallEntity (hashmap<String, Object>) and then pass that to the API.
**/
SlatwallEntity account = accountList[0]; //<--grab the first account from the accountList.
/**
* You 'put' keys into it, assign a value and then you can call any api update method using it.
* The key is always a string, and the value can be any object. The values are automatically (de)serialized
* to JSON for you, to make using the API as easy and intuitive as possible.
**/
account.put("firstName", "John");
account.put("lastName", "Waters"); //<--populate the entity with data which overwrites what is already there (if any).
/** Pass that data back to the API for processing */
SlatwallEntity response = slatwallScope.updateAccount(account);
/** View the success or error message that is returned as well as any validation messages. */
System.out.printf("Response: %s\n", response.toString());
} catch (ApiException e) {
System.out.printf("Exception e =: %s\n", e.getMessage());
}
}//<--end SlatwallScope tutorial
<?php
// Include the PHP SDK
include slatwall.php
// Instantiate the SlatwallScope
$slatwallScope = new slatwallScope( "http://www.mySlatwallInstance.com/", "205c1fd430fb4588bf5a5b82a03fe1af" );
// Output the slatwallScope to verify that it's been created correctly
var_dump( $slatwallScope );
?>

Current Session Data

You can think of a current session defined as 2 key entities, the current account that is logged in, and the current shopping cart that is being modified.  Keep in mind that a session can have an active shopping cart WITHOUT having an account logged in.

In addition, there is one other entity that is the parent entity to both the account and cart, the session entity.  This object is used to store other pieces of information like IP address, cookie, sessionExpiration, etc.

 

CFScript
// Determine if there is a current user logged in
writeDump( var=request.slatwallScope.getLoggedInFlag() );
// Retrieve the entire account entity
writeDump( var=request.slatwallScope.getAccount(), top=3 );
// Retrieve just the account data that would normally be sent over the RESTful API
writeDump( var=request.slatwallScope.getAccountData() );
// Retrieve a specific properties of the account entity
writeDump( var=request.slatwallScope.getAccount().getFirstName() );
writeDump( var=request.slatwallScope.getAccount().getLastName() );
writeDump( var=request.slatwallScope.getAccount().getEmailAddress() );
// Retrieve related objects
writeDump( var=request.slatwallScope.getAccount().getAccountAddresses(), top=3 );
Tag Based CFML
<!--- Determine if there is a current user logged in --->
<cfdump var="#request.slatwallScope.getLoggedInFlag()#" />
<!--- Retrieve the entire account entity --->
<cfdump var="#request.slatwallScope.getAccount()#" top=3 />
<!--- Retrieve just the account data that would normally be sent over the RESTful API --->
<cfdump var="#request.slatwallScope.getAccountData()#" />
<!--- Retrieve a specific properties of the account entity --->
<cfdump var="#request.slatwallScope.getAccount().getFirstName()#" />
<cfdump var="#request.slatwallScope.getAccount().getLastName()#" />
<cfdump var="#request.slatwallScope.getAccount().getEmailAddress()#" />
<!--- Retrieve related objects --->
<cfdump var="#request.slatwallScope.getAccount().getAccountAddresses()#" top=3 />
// Determine if there is a current user logged in
console.log( SlatwallScope.getLoggedInFlag() );
// Retrieve the entire account JS helper object
console.log( SlatwallScope.getAccount() );
// Retrieve just the account data that was passed down over the RESTful API, and not the Account helper object
console.log( SlatwallScope.getAccountData() );
// Retrieve a specific properties of the account entity
console.log( SlatwallScope.getAccount().getFirstName() );
console.log( SlatwallScope.getAccount().getLastName() );
console.log( SlatwallScope.getAccount().getEmailAddress() );
// Retrieve related objects (this will do a subsequent call over the RESTful API.
console.log( request.slatwallScope.getAccount().getAccountAddresses() );
CFScript
// Retrieve the entire cart entity
writeDump( var=request.slatwallScope.getCart(), top=3 );
// Retrieve just the account data that would normally be sent over the RESTful API
writeDump( var=request.slatwallScope.getCartData() );
// Retrieve a specific properties of the account entity
writeDump( var=request.slatwallScope.getCart().getOrderID() );
writeDump( var=request.slatwallScope.getCart().getCurrencyCode() );
writeDump( var=request.slatwallScope.getCart().getCalculatedTotal() );
// For all of the 'Cart' properties that are available please see the 'Order' entity api reference
// Retrieve related objects
writeDump( var=request.slatwallScope.getCart().getOrderItems(), top=3 );
Tag Based CFML
<!--- Retrieve the entire cart entity --->
<cfdump var="#request.slatwallScope.getCart()#" top=3 />
<!--- Retrieve just the cart data that would be sent over the RESTful API by default --->
<cfdump var="#request.slatwallScope.getCartData()#" />
<!--- Retrieve a specific properties of the account entity --->
<cfdump var="#request.slatwallScope.getCart().getOrderID()#" />
<cfdump var="#request.slatwallScope.getCart().getCurrencyCode()#" />
<cfdump var="#request.slatwallScope.getCart().getCalculatedTotal()#" />
<!--- For all of the 'Cart' properties that are available please see the 'Order' entity api reference --->
<!--- Retrieve related objects --->
<cfdump var="#request.slatwallScope.getCart().getOrderItems()#" top=3 />
// Retrieve the entire cart JS helper object
console.log( SlatwallScope.getCart() );
// Retrieve just the account data that was passed down over the RESTful API, and not the Account helper object
console.log( SlatwallScope.getCartData() );
// Retrieve a specific properties of the account entity
console.log( SlatwallScope.getCart().getOrderID() );
console.log( SlatwallScope.getCart().getCurrencyCode() );
console.log( SlatwallScope.getCart().getCalculatedTotal() );
// Retrieve related objects (this will do a subsequent call over the RESTful API)
console.log( request.slatwallScope.getCart().getOrderItems() );
CFScript
// Retrieve the entire session entity
writeDump( var=request.slatwallScope.getSession(), top=3);
// Retrieve cookie info used for maintaining session
writeDump( var=request.slatwallScope.getSession().getSessionCookiePSID() );
writeDump( var=request.slatwallScope.getSession().getSessionCookieNPSID() );
writeDump( var=request.slatwallScope.getSession().getSessionExpirationDateTime() );
// Retrieve a specific properties of the session entity
writeDump( var=request.slatwallScope.getSession().getLastRequestDateTime() );
writeDump( var=request.slatwallScope.getSession().getLastRequestIPAddress() );
writeDump( var=request.slatwallScope.getSession().getLastPlacedOrderID() );
writeDump( var=request.slatwallScope.getSession().getLastPlacedOrderID() );
// Retrieve related objects
writeDump( var=request.slatwallScope.getSession().getAccount(), top=3 );
writeDump( var=request.slatwallScope.getSession().getOrder(), top=3 );
// Important Note: getSession().getOrder() is the current shopping cart
Tag Based CFML
<!--- Retrieve the entire session entity --->
<cfdump var="#request.slatwallScope.getSession()#" top=3 />
<!--- Retrieve cookie info used for maintaining session --->
<cfdump var="#request.slatwallScope.getSession().getSessionCookiePSID()#" />
<cfdump var="#request.slatwallScope.getSession().getSessionCookieNPSID()#" />
<cfdump var="#request.slatwallScope.getSession().getSessionExpirationDateTime()#" />
<!--- Retrieve a specific properties of the session entity --->
<cfdump var="#request.slatwallScope.getSession().getLastRequestDateTime()#" />
<cfdump var="#request.slatwallScope.getSession().getLastRequestIPAddress()#" />
<cfdump var="#request.slatwallScope.getSession().getLastPlacedOrderID()#" />
<cfdump var="#request.slatwallScope.getSession().getLastPlacedOrderID()#" />
<!--- Retrieve related objects --->
<cfdump var="#request.slatwallScope.getSession().getAccount()#" top=3 />
<cfdump var="#request.slatwallScope.getSession().getOrder()#" top=3 />
<!--- Important Note: getSession().getOrder() is the current shopping cart --->
// Retrieve the session helper object
console.log( request.slatwallScope.getSession() );
// Retrieve just the sessionData returned by the RESTful API
console.log( request.slatwallScope.getSessionData() );
// Retrieve cookie info used for maintaining session
console.log( request.slatwallScope.getSession().getSessionCookiePSID() );
console.log( request.slatwallScope.getSession().getSessionCookieNPSID() );
console.log( request.slatwallScope.getSession().getSessionExpirationDateTime() );
// Retrieve a specific properties of the session entity
console.log( request.slatwallScope.getSession().getLastRequestDateTime() );
console.log( request.slatwallScope.getSession().getLastRequestIPAddress() );
console.log( request.slatwallScope.getSession().getLastPlacedOrderID() );
console.log( request.slatwallScope.getSession().getLastPlacedOrderID() );
// Retrieve related objects
console.log( request.slatwallScope.getSession().getAccount() );
console.log( request.slatwallScope.getSession().getOrder() );
// Important Note: getSession().getOrder() is the current shopping cart

Public Processing

Data Access & Processing

Questions & Comments