W3StudioCMS Advanced Manual

Slot mappers

Slot mappers starts to play when you need to upgrade the theme for your website. Slot mappers can be defined as the technology used by W3StudioCMS to port the contents from the current template you are using for your site to the new awesome template you drawed for your website.

After you have loaded the new theme, you have to change the template for each group you have defined in your website. Open the edit groups interface from the control panel, then choose the new template you want to assign to the group.

After you made this, W3StudioCMS compares the two templates to find if there are slots in common between these two layouts. It can happen that every slot name matches from the old template and the new one: in this case nothing appens and you can safety edit the group with the new layout. But this case is very rare when you upgrade to a new template, because probably you reorganize the slot names, you cut some slots and you add new ones. This is what will probably happens in the most of the cases when you upgrade your theme. Here slot mappers enters in scene.

At the beginning of this chapter we said that slot mappers are used to port contents from a theme to another. In fact, after W3StudioCMS has analyzed the templates, it puts a link under the edit button of the group's editing interface which loads the slot mappers interface. A new panel is added on the top-left corner and the both the templates are loaded and each editable slot on the template gets a particular color. The CMS looks for slots with the same name on both templates, and maps them if it founds some. These slots are listed below the control buttons, into the slot's mapper area, and they are displayed in green on both the templates. The slots coloured in red are the ones which cannot be mapped by the CMS, so you have to map them manually.

In the slot mapper panel there is the button "Switch template" you can use to switch between the two templates. To map the slot you have simply to click the slot you want to associate from the old template, then change template using the button mentioned above and click the slot to map. To confirm the mapping, click the button "Map slots". The new mapping will be added to the slot's mapper area. This is how you can port contents from a template to another one.

To remove a mapped slot you can click the minus icon near the mapping in the slot's mapper area. The mapping will be removed and the slots return to red status. It's not needed to map all the slots, because it could happen that some contents could not be necessary anymore: in this case leave the contents you don't need in the red status.

To complete the mapping you have to confirm by clicking the "Save map" button. This will save the mapping you made to the database. Now you can close this mode and return to groups editor interface. Choose again the template from the combobox and now click the edit button to move to the new template. Note that if you have left some slots unmapped, the CMS will display the link to make the mapping again: the behaviour is correct and you simply ignore it.

At last note that if you have more groups with the same template which has to change to the same one, the mapping operation is needed only for the first time, then it's saved and you hanen't to do it again.

Upgrading a theme

Let's suppose you have to add a new slot to a template of your theme. Follow a code example that will be added to a template.

<div id="box3"><?php include_slot('box3')?></div>

In the yml file that fills the template when a new page is added, you have to provide the text to add for that content. An example could be the following one:

box3:
  className: Script
  slotId: box3
  content:  Insert a text
  contentPosition: 1
  edited: 1

You could change the stylesheet too if it is needed. This will add a new slot to the template. The changes are imported into the CMS from the Theme manager interface. Every time that the interface opens, every template is checked to find if changes occoured. When you add a new slot, or you edit a slot's name or you delete another one, a command "upgrade" is displayed near the theme. Click it to import your changes.