This section provides basic details about Slatwall & how to get started!
Slatwall is an extremely powerful and robust digital commerce management system. It is designed to work in a multitude of different business situations, and helps to centralize your commerce activity by integrating into existing systems. Slatwall easily operates as an eCommerce shopping cart for your website but it can also do a lot more like Inventory Mangement, Vendor Ordering, Subscription Management, etc.
These docs should provide all of the information you need to get up and running with Slatwall. Broken up into two sections, the first helps developers get slatwall up and running, and the second focuses on users, the admin, and how to use it.
It's important to note that these docs are part of the Slatwall core which means they get updated as new versions of Slatwall are rolled out. The most current version of the docs can always be found at docs.getslatwall.com, but your version spefic docs can be found in the slatwall admin under Help / Tools > Docs.
If you have a question that can't be answered by these docs you can post it to the google group (link in the top navigation above) where the community provides free support. In addition, ten24 offers professional support, maintenance agreements, and professional services for Slatwall. More information about these contracts can be obtained by contacting ten24 (www.ten24web.com/contact/).
*Slatwall is built on top of Java's Hibernate. Theoretically any of the databases that Hibernate supports should work, but as of right now only MS SQL & MySQL are tested with every release. Use other engines at your own risk.
You can install Slatwall a handful of different ways. Selecting the correct option really depends on your situation and how you intend to use Slatwall. At its core you can think of Slatwall as your back-office commerce management solution. Slatwall by itself does not have any CMS built in, so if you planing to be building a public facing eCommerce website we hightly recommend selecting an option that includes a CMS.
| Folder & File | Description |
|---|---|
| admin/ controllers/ layouts/ views/ |
Holds the primary administrative web application. This directory consists of 3 sub-directories; controllers, layouts & views. The majority of the admin application runs through the /views/entity directory so if you are interested in learning about how we layout our administrative views, this would be a good place to start. It's important to note that this directory is a FW/1 subsystem, and for more information on how FW/1 subsystems work please visit the wiki here: FW/1 Wiki |
| assets/ | The assets directory holds some of the core CSS & Images for the application |
| config/ dbdata/ resourceBundles/ scripts/ configApplication.cfm configApplication.cfm configCustomTags.cfm configFramework.cfm configORM.cfm lastFullUpdate.txt.cfm |
The config folder holds all of the data, and setup that Slatwall uses to set itself up. This folder should never be modified, if you would like to make instance level configuration changes they should be done in the /custom/config direcotry.
|
| custom/ config/ resourceBundles/ model/ dao/ service/ validation/ |
Any customizations to how the application functions can be defined in this directory. Any code added here will not be overridden when the application is updated. You will notice that the folder structure mirrors the the same folder structure from the root. |
| frontend/ | The frontend directory was previously used as the primary subsytem used by public facing websites in versions 2.3 and previous. This folder is deprecated so please use the 'public' subsystem for all new development. |
| integrationServices/ | This directory is the primary place where you can extend the Slatwall application to fit your businesse needs. It contains a handful of integrations that we provide, and in addition you can add new directorys to this folder in order to extend / customize the application. |
| meta/ | Contains a lot of meta information about the application, including these docs. It also has our Test suites, and some tools like snipits and dictionaries that can be used in your IDE or Text Editor |
| model/ dao/ entity/ process/ service/ transient/ validation/ |
This is the beating heart of Slatwall, and contains all of the businesse logic that makes up Slatwall (with the exception of the /org/Hibachi directory). It is strongly suggested that you explore these sub-directories and especially the /entity directory as it maps out the entire database structure.
|
| org/ Hibachi/ |
The org directory is where we store all libaries, frameworks, etc. that are independintly managed. The primary external library is /Hibachi which is a framework developed by ten24 that sits on top of FW/1 to provide abstract ORM features for Rapid Application Development. |
| tags/ | This directory holds some CF Custom tags that are used by Slatwall specifically in the admin and integrationServices |
* Folder is save to make changes within, without fear of being overwritten during update.
* Folder is not needed, but recommended
* Folder is deprecated.
If you are currently running Slawtall version 2.3 or newer as a plugin to Mura, please follow these steps to migrate to the latest version.
When this new Mura integration plugin gets installed, it will automatically download and install the latest stable release of slatwall directly in your Mura root folder. The new connector plugin serves as a go-between from Mura to Slatwall and is required now that Slatwall is a standalone application and not itself a plugin for Mura.
IMPORTANT: The old 2.x version of Slatwall used a "frontend" subsystem to do all of the listing displays, product detail, checkout, my-account, etc. This subsystem has been DEPRECATED in version 3.0 for the new "public" subsystem that functions differently. We highly recommend reading up on the "frontend development" portion of these docs to learn how the new API functions. If you do not wish to update the forms & displays for an existing site, you can tell the Mura integration to Inject the Legacy Views (ie: frontend subsystem). To do that follow these steps
Once you have Slatwall installed, it is important to keep it up to date with the latest releases. This ensures that you are always up to date with any new features & functionality as well as security bugs that have been fixed. The good news is that Slatwall makes this extreamly easy.
| Version | Description |
| Stable | This version should be used by all production sites. |
| Bleeding Edge | This version should only be used when testing on development server a new feature that is planned to be in a future release. |
| Custom | This should only be used by advanced users, and when explicitly asked to update to a custom branch from the support forums. |
IMPORTANT DEVELOPER NOTE: If you have made any changes to files in your slatwall instance that are outside of the "Update Safe" folders defined in the File Structure docs, there is a very high chance that those changes will be overridden so please take extream caution and always backup your work. You should never need to make a change to Slatwall that is outside of the "Update Safe" folders. If you don't know how to make your necessary customization inside the "Update Safe" folders, please post a question to the google group.
If you would like to get Slatwall connected to your larger CFML based application, follow these short, simple steps:
First: Tell Slatwall about your App
/custom/config/configApplication.cfm
this.name="myappname";
this.datasource.name="mydatasourcename";
Now tell your app about Slatwall
this.mappings["/Slatwall"] = "fullSystemPathToSlatwall"; this.ormEnabled = true; this.ormSettings.cfclocation = ["/Slatwall/model/entity","/Slatwall/integrationServices"]; this.ormSettings.dbcreate = "update"; this.ormSettings.flushAtRequestEnd = false; this.ormsettings.eventhandling = true; this.ormSettings.automanageSession = false;
Now that the two applications know about each other, you can navigate to the Slatwall directory in your browser to make sure it works. As you can imagine, there are a number of other configurations that can be set for Slatwall, so please review the App Config Files documentation.
Next, lets setup your app to talk with ours
The good news is that for both client side & server side, there is a single API to integrate with Slatwall: the "Slatwall Scope." The Slatwall Scope serves two functions: to pull information from Slatwall to process logic on your side, or display to users, and to accept information from the application & users by listening for actions. Set up Slatwall Scope using the steps below.
if (!structKeyExists(application, "slatwallFW1Application")) {
application.slatwallFW1Application = createObject("component", "Slatwall.Application");
}
application.slatwallFW1Application.bootstrap();
request.slatwallScope to be used to pull any information out of slatwall, or manually call service functions.
if(structKeyExists(form, "slatAction")) {
request.slatwallScope.doAction( form.slatAction );
} else if (structKeyExists(url, "slatAction")) {
request.slatwallScope.doAction( url.slatAction );
}
$.slatwall = request.slatwallScope; #$.slatwall.renderJSObject()#
The second line gives you client side access to the entire Slatwall api to pull objects back a JSON, and can be great for running functions like adding items to the cart, or updating you product listings via AJAX.
There are a lot of buttons to press, and knobs to turn... lets find out what they do.
Slatwall is extremely configurable -- unlike other eCommerce management solutions, Slatwall enables developers to completely override almost every aspect of the application if desired. This includes things like application settings, resource bundles, validation and even any of the services or dao's that are core to the application.
In the /custom/config directory of Slatwall, 5 important files allow for an override of the default settings, and give you controle over how the application functions. Normally, this folder is empty unless Slatwall was installed via a connector, like the Mura connector. In that case there may be some files that were automatically written to link Slatwall with that application.
Any config files added to the custom folder will be pulled into the application and override the defaults defined by Slatwall. The files will be loaded up in the order below.
These files allow you to designate all of the application level configurations that are avalable for ORM. The most common reason to add these files is to enable secondary cache for ORM which can be done with this simple 1 liner.
Time to get your hands dirty and start building your dreams.
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.
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()
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. |
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(). |
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="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"}). |
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.
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.
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 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 class="?slatAction=public:cart.addOrderItem">Add To Cart</a>
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" />
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.
Example as a form:
<input type="hidden" name="sRedirectURL" value="www.mysite.com/order-confirmation/" />
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. |
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 attem