Frontend Development

Formatting Values

In Slatwall, the base object utilizes the getFormattedValue() method. This method formats different data types depending on the settings defined in the Advanced Global Settings of the admin.

For example, "sku.getFormattedValue('price');" returns the value based on the currency format settings in the Advanced settings tab.

The "getFormattedValue()" method utlizes the "getPropertyFormatType()" method of the base object to discover the proper formatType of a property. This feature may be overridden. For instance, order.getFormattedValue('openDateTime', 'date') will display only the date and not the entire datetime.

Valid formatTypes are:

  • none
  • yesno
  • truefalse
  • currency
  • datetime
  • date
  • time
  • weight

By default, the "getPropertyFormatType()" method will use ormtype, type, and naming conventions of the property. Formatting can also be explicitly defined by using a custom attribute called "formatType".

Example

property name="price" ormtype="big_decimal" type="numeric" formatType="currency";

Results, Errors & Validation

Public Action Results

Whenever you submit a slatAction(s) to the public api, the SlatwallScope will return the success / failure of that action.  You can easily get those value by calling one of the following methods on the slatwallScope.

Method Arguments Return Type Description
$.slatwall.getCalledActions() none Array Returns an array of all actions that were called.
$.slatwall.getFailureActions() none Array Returns an array of all failed actions that were called.
$.slatwall.getSuccessfulActions() none Array Returns an array of all sucessful actions which were called.
$.slatwall.hasFailureAction( action ) action (string) Boolean Returns an array of all sucessful actions which were called.
$.slatwall.hasSuccessfulAction( action ) action (string) Boolean Returns an array of all sucessful actions which were called.

 

Displaying Error Messages

Slatwall makes it easy to display error messages that come back from unsuccessful actions. When a public slatAction is called there will always be an object in the SlatwallScope that the action is acting on. For example when calling ?slatAction=public:cart.addOrderItem, the object that is being acted on is $.slatwall.cart(). This means that when the action is completed any errors that might have been encountered such as validation errors can be found in $.slatwall.cart().getErrors() which will return a struct of error messages.

We've made the outputting of those errors simple, in the public tag library you will find: <sw:ErrorDisplay />. In the example above if you would like to output any errors that the cart object has after attempting to add an item you would do:

<sw:ErrorDisplay object="#$.slatwall.cart()#" />

However, if you would like to just output the errors related to adding the orderItem, you would specify the errorName

<sw:ErrorDisplay object="#$.slatwall.cart()#" errorName="addOrderItem" />

The nice thing about this custom tag is that it checks to see if the specific error or errors exist, and if not then nothing is output. You can also explicitly ask objects if errors exists, and then get those error mesaages with the following:

object.getErrors();
object.hasError(errorName="");
object.getError(errorName="");
Method Arguments Return Type Description
object.hasErrors() none Boolean Returns true / false if the object has any errors.
object.hasError( errorName ) errorName (string) Boolean Returns true / false if the object has a specific error.
object.getErrors() none Struct Returns a struct of all errors the object has.
object.getError( errorName ) errorName (string) Array Returns an array of all error messages for a specific error in the getErrors() struct.

Public API: slatAction

Overview

The frontend of your site will pass data back to Slatwall typically by using the frontend action paramater called 'slatAction'. This lets Slatwall know that you would like to trigger some type of action, and it can be passed as either a URL paramater or FORM paramater. For example the 'addToCart' action could either be called as:

<input type="hidden" name="slatAction" value="public:cart.addOrderItem" />

Or via a URL paramater as:

<a href="?slatAction=public:cart.addOrderItem">Add To Cart</a>

 

Chaining Together slatAction's

One of the great features about slatActions is that they are able to be chained together. A common use case for this is to create a new account and then directly after log that account in. An example of a chained actions would look like this:

<input type="hidden" name="slatAction" value="public:account.create,public:account.login" />

 

Redirects

Sometimes after calling an action you will want to redirect the user to a specific url. There are three different paramaters that can be used to facilitate this behavior.

Warning: Using redirects can sometimes have unintended consequences because as soon as the redirect happens you will lose all server side validation, success & failure information.

Best Practice: To avoid loosing the data, whenever possible, it is best to change either the form action you are posting to, or the url that you are getting to be the page that you would like the user to end up on after the action is complete. Because actions are called before any rendering you will then be able to display the results on that new page.

If you do need to use a redirect, then you can use the following paramaters again as either a URL paramater or hidden form field.

redirectURL
The url will be redirected to regardless of the outcome from the action that was called.
sRedirectURL
The url will only be redirected to if the action was a success. If you have chained multiple actions together it will be redirected to if ALL actions were successful.
fRedirectURL
The url will only be redirected to if the action was a failure. If you have chained multiple actions together it will be redirected to if ANY action failed.

Example as a form:

<input type="hidden" name="sRedirectURL" value="http://www.mysite.com/order-confirmation/" />

Frontend Display Templates

Concept

If you are building out a public facing shopping cart, the core of that experience is going to be driven by some type of content management system (CMS) or perhaps a custom application.  However when you break it down there are only a handful of template types that you are likely going to setup.

  • Product Listing
  • Product Detail
  • Shopping Cart
  • Checkout
  • My Account

These templates work by pulling data out of the SlatwallScope, which by convention should be setup as $.slatwall (it can also be found in request.slatwallScope). Then they submit form values or links with a paramater called "SlatAction" that defines public api methods to pass data into Slatwall.

Examples

Slatwall ships with a set of example templates like the list above (and a couple additional). These templates can and should be modified to fit whatever type of shopping experience you are looking for. In order to make it as easy as possible to get you up and running, we heavily document via comments the inside of these example fiels. You can find these templates in: /public/views/templates/ but it will be important not to use them directly from that location but to instead copy them into your desired look and feel. The example templates use the Twitter Bootstrap UI conventions, but Twitter Bootstrap is not required for any of them to work.

Important: If you are using one of our connector plugins for a common CMS platform then these templates were likely already copied over to that application on install. For Mura CMS they should be in you /templates folder and for contentbox they should be in your /layouts directory.  For more information on this view the docs for your specific CMS in the Integrations section.

The SlatwallScope

Overview

One of the most important objects to understand, especially for frontend development, is the SlatwallScope. It operates as the primary progromatical interface for getting information both in and out of Slatwall. The SlatwallScope is created on every request and stored in request.slatwallScope, however by convention a reference to this will be stored in every template as $.slatwall.

Request Objects

The SlatwallScope contains all of the contextual information for that page request including all of the current request objects like the session, account, and cart. In addition when you are on specific "detail" pages the slatwall will also contain those request objects like the product, productType or brand. The convention for accessing these objects is very simple, and follows the following example syntax:

Method Description
$.slatwall.getAccount() Returns the current account object.
$.slatwall.account() Shorthand for returning the current account object, the result is the exact same as above.
$.slatwall.account( 'firstName' ) Shorthand for returning a specific property of the object, this is the exact same as doing $.slatwall.getAccount().getFirstName().
$.slatwall.account( 'firstName', 'John' ) Shorthand for setting a specific property of the object which can then later be persisted to the database. This is the exact same as doing $.slatwall.getAccount().setFirstName('John')

The request objects that get set in the SlatwallScope are:

$.slatwall.getAccount()
$.slatwall.getBrand()
$.slatwall.getCart()
$.slatwall.getProduct()
$.slatwall.getProductList()
$.slatwall.getProductType()
$.slatwall.getSession()

Request Helpers

In addtion to the request objects there are some helper methods that will get you some quick insights about the request

Method Return Type Description
$.slatwall.getLoggedInFlag() Boolean Returns true / false if the current request is a logged in account. If it isn't then $.slatwall.getAccount() will just return a new account object that has not been persisted to the database.
$.slatwall.getLoggedInAsAdminFlag() Boolean Similar to the method above, but returns true / false if the current account that is logged in belongs to any of the admin permission groups.

Custom Request Values

The SlatwallScope also has the ability to store custom request values directly inside of it. This can be very useful for setting custom values, and then calling them back up somewhere else in the request.

Method Arguments Return Type Description
$.slatwall.hasValue( key ) key (string) Boolean Returns true / false if a value has been set for that key.
$.slatwall.getValue( key ) key (string) Any Returns the value of a key that was set.
$.slatwall.setValue( key, value ) key (string)
value (any)
Void Shorthand for returning a specific property of the object, this is the exact same as doing $.slatwall.getAccount().getFirstName().

General Entity Access

All of the objects that have been described above like account, cart, ect are actually a specific type of object called an "Entity". Entities are just objects that get saved to the database. However there are a lot more entities in the Slatwall database that you may want to read, update, delete and save. Again the SlatwallScope provides a consistent API for working with all of the entities. The easiest way to know what entities are available as well as their properties is just to open the /Slatwall/model/entity directory.

Method Arguments Return Type Description
$.slatwall.newEntity( entityName ) entityName (string) Object Returns a new entity that when saved will turn into a single row in the database. For example you could call: $.slatwall.newEntity( 'Product' )
$.slatwall.getEntity( entityName, entityID, [returnNewOnNotFoundFlag] ) entityName (string)
entityID (string)
returnNewOnNotFoundFlag (boolean)
Object || Null Loads an entity by it's ID property. If the ID is not found in the database, and returnNewWhenNotFoundFlag is true then you will get the same result as newEntity(). For example you could call: $.slatwall.getEntity( 'Product', '22d919cefca3bafd8c6f35d792287683', true)
$.slatwall.saveEntity( entity, [data] ) entity (object)
data (struct)
Object Calling this method will persist the object to the database so that it is saved as long as it passes 'save' context validation. The data argument will allow a structure of property values to be populated into the entity before saving. For example you could call: $.slatwall.saveEntity( $.slatwall.newEntity('brand'), {brandName="Nike", brandWebsite="http://www.nike.com"} ) Keep in mind, that because Slatwall runs on a persistent ORM framework, and you make changes to an existing entity that was pulled out of the database those changes will be saved even WITHOUT calling saveEntity(), however calling saveEntity() will ensure that it passes validation.
$.slatwall.getEntity( entityName, entityID, [returnNewOnNotFoundFlag] ) entityName (string) Boolean This will delete the entity from the database so long as it passes 'delete' context validation. It will return true / false based on if the object passed validation.
$.slatwall.getSmartList( entityName, [data] ) entityName (string)
data (struct)
Object This will return a SmartList of all of a specific type of entity. The data argument allows you to pass in specific values for filtering, sorting, paging, ranges & searching. For example you can call $.slawall.getSmartList('product', {orderBy="productName"}).

Questions & Comments