Slots
- What are Slots ?
- Slot Variables
- Activating Slots
- Configurations
- Autocomplete
- Comma Separated Values
- Item & Collection Templates
- Custom Fields
- Sorting
- Components
- Scopes
- Routes
- Debugging
What are Slots ?
A slot is a front-end function which pulls content dynamically based on it's configuration. Each slot can easily be called using the following syntax:
<{slot id=3}> |
The ID of the slot tells Core dna what to load, the ID is shown in the DXP on the left in the slots administration.
A slot is configured as follows: Component -> Configuration -> Slot -> Scope
A slot itself is just a container for a configuration, The purpose of the slot is to allow easy identification and to control the number of items returned (up to 100 items). The content returned will always be an array of objects.
You can easily disable / enable slots using the publish switch on the DXP, You can only delete the last created slot in order to ensure sequential slot numbering without breaks. This is done because the slot number is incremented in the back-end system by Core dna.
Slots can only be added to the Global Scope. All slots are then inherited into any scopes configured.
Slot Variables
Slots allow values to be dynamically passed in the slot function itself. This enables content to be loaded based on a variable from another data source, e.g: viewing a user → show all blog posts from this user.
You can pass the variable "lookup_author"
<{slot id=3 lookup_author="Sam"}> |
This value will be ignored unless the markdown for this variable is set in the configuration.
The syntax for this is "{lookup_author}", or whatever the passed in variable name is (surrounded by curly braces). It can be any string you want, as long as you set in the configuration that "author" is to load this variable's value.
Now the slot will load Blog content from; "Tom, Sam, John".
Activating Slots
When a scope is configured, it will automatically inherit the Global Slots by default. This is shown when a row is dark grey in colour.
You can "Activate" these slots at any point by using the Activate switch provided. This switch will create a new slot using the same content of the parent, but assigned into this scope. You now can make edits to this slot as you see fit.
This is done to allow small modifications on a scope, for example: We may only want to update slot 3 to five items instead of one on the scope of "/blogs". Instead of redefining everything every time, we just activate slot 3 and make the edit.
When you deactivate a slot, the slot is deleted from the scope. After deactivation, it will still inherit the Global Scope. In order to fully delete a slot, you must remove it from the Global Scope.
Configurations
A configuration is just an Component with custom arguments. For example; if you select the "Get Products" Component, then click save, it now becomes a configuration. In this configuration, you can set which product to load, or which category, or which order to load the products.
The Component allows Core dna to load the data, then the configuration tells us what to load.
Most configuration settings will accept multiple values via an autocomplete or an comma separated list of ids.
Autocomplete
Any field which has placeholder text starting with "Starting typing to search" is an autocomplete field. These fields allow you to easily search the content and select the relevant items.
Any items selected yet to be saved will be highlighted in blue. You can remove selected items using the blue cross icon to the right of the row.
Comma Separated Values
Any field which has placeholder text starting with "Enter Comma separated values" will take regular text input. These fields allow you to easily copy configurations from one config to another.
For example, you can enter the valid string: "123,456,2,3,4,5,10056" (without the quotes)to load seven products.
Item & Collection Templates
Every configuration allows you to set a single Item Template or a group Collection Template.
An Item Template (if set), will be evaluated for every single fetched item from the Component. Each Item Template will have a single variable called $item assigned. It is not required to set an Item Template, you can use a Collection Template instead if you wish. You can use an Item Template on it's own to display a single item if you want.
An Collection Template is evaluated for all items in the component. A single fetch is called on this template, it has the variable $items assigned. If an Item Template is also set with an Collection Template, The output from the Item Template will be appended into a single variable called $items_content, which can be used in the Collection Template. However, you can ignore this and just loop all the items if you wish.
The intended use case is that every item will have a Item Template assigned, which will be wrapped by a Collection Template.
Custom Fields
Some configurations allow you to search Custom Fields. Under the Custom Field name you must enter the single name you want to search, eg: "YouTube ID". Under Custom Field Value you can enter the search term.
Custom Field Values also accepts the following arguments:
- "(notempty)" - Return any populated Custom Field with the supplied name.
- ">" or "<" - Perform a check on this value, for example: "> 100" will check if the Custom Field value is over 100.
Sorting
Every configuration allows you to set the sorting field or sorting order of the items returned.
The sorting is usually by:
- Ascending
- Descending
- Random
Components ?
A Component is the core of how a slot works. It defines the database model to work with, and the kind of content returned. Each slot has a single component configured. Components are continuously being added by the Core dna team, so functionality will continue to expand. The current list of Components include;
- Get Blog Posts
- Get Banners
- Get Products
- Get Widgets
- Get News
A Component is required to create a configuration, which in turn is required to complete a functioning slot.
Scopes ?
A scope allows an admin to control which slots are shown on a given URL. For example; A scope could be setup for page; "/blogs" to show slots 1-3 with Blog configurations set. Another scope could be set for "/products", also using slots 1-3. However, the slots used on "/products" will have different configurations set. scopes allow us to control which kind of configurations are loaded based on the URL provided. We use routes to define which scope should be loaded.
By default, the scope will be set to "global" until a new scope has been added.
Now we have 2 scoops; "Test Scope" and "Blogs Scope". These scopes will be available on the scopes drop down on the slots screen.
If you hover over any scope, you will be shown two options; "Routes" and "Delete". Delete will remove the scope and all assigned routes. Routes define how the scope is loaded.
Routes
A route tells Core dna what mixture of URL, action, form_name and form_action relate to a scope.
It is possible to create very simple routes which will load for Paths as simple as '/blogs', or complex routes with multiple values passed in the POST.
A scope can have multiple routes, the first route found which matches the set fields will be returned. If more than one match is found, then the indexes of the items is used and the lowest found index will be returned.
Routes accept the following:
- Index: The position of the rule. The lowest (e.g: id 1) is the most important.
- Path: The URL to check. Must begin with a forward slash. This field has two modes of operation; 'Starts With' which will find everything with matches the string and anything afterwards.
The second option is 'Equals'; which require the entire string to be found, nothing more - nothing less. - Action: The action passed in the Request.
- Form Name: The form name passed in the Request.
- Form Action: The form action passed in the Request.
No Path can contain a question mark or hash character, All routes have inline editing.
Debugging ?
Enter expose_slots=1 into the URL of your page to view the breakdown of the current slots and scopes.
www.yoursite.com/?expose_slots=1 |
When this flag has been passed, the content is not displayed but replaced by simple borders for each slot.