Overview Guide for Shelf Self-Service Portal Theme Editor Feature


Document Version History 

Version number

Modified by

Modifications made

Date modified

Status

1.0

Shelf

Initial release of the document.

3 August 2022

Active



























Document Purpose 

This document has been developed for administrators and content managers of organizations that have subscribed to and are using the Shelf Self-Service Portal Products, in order to answer the following questions: 
  • What is the Shelf Self-Service Portal?
  • What is the Theme in Self-Service Portal? 
  • What is the Theme Editor feature?
  • What purposes does this feature serve?
  • How is it enabled?
  • How is it configured?
  • How is it used in practice?

If you require further assistance, feel free to contact us at support@shelf.io, via the live chat on the Shelf website or from the in-app chat support within the Shelf platform.




What is the Shelf Self-Service Portal? 

The Shelf Self-Service Portal (SSP) feature makes it possible for administrators to create public libraries, that is libraries designed for public use. These libraries can contain various public-facing content to be further added to a company’s website or used for deflection purposes.

The Self-Service Portal feature is an ideal choice to set up self-service portals for contact centers (CCs) as it allows CC’s users to solve multiple problems on their own, in a self-service manner. Moreover, using custom scripts, self-service portals can be integrated with web forms, chatbot, and virtual assistance solutions in conjunction with the Shelf MerlinAI Suggest module. Another great example of the SSP usage is FAQ-like websites where users can address their issues on their own, using the available content.


What is the Self-Service Portal Theme? 

A Theme for the Shelf Self-Service Portal is what defines how your SSP is expected to look and what elements - layout, widgets, content blocks, headers/footers, controls, localizations, etc. - it is expected to have. By default, there are two themes available for selection for your SSP at the stage of its configuration - Classic and Modern
The difference between these default themes lies in the general layout of the content on the Home page and presence of the initial sidebar panel and breadcrumbs in the Classic theme. At the same time, all the main functionality remains unchanged: header and footer, social media link buttons, logo, content block with folders and their content, and the link to the Shelf website.
The most important point is that visitors of your Self-Service Portal, regardless of its theme, are able to access the needed content easily by clicking the respective article or folder.
For example, if the Classic theme is selected for your Self-Service Portal, you or your visitors can browse the available content using the sidebar panel in the left part of the Home page. The panel shows folders that contain articles and it is possible to click the folder names to show what is stored in the respective folders. Refer to Figure 1 below in order to view these two themes and see how they differ from each other.

Figure 1. Viewing the differences between SSP Home page with the Classic and Modern themes

However, there is a possibility to set up your own theme if none of the default ones satisfies your requirements to the SSP layout and elements.  Jump below to learn what needs to be done to have your custom Self-Service Portal theme up and running.


What is Theme Editor?

Theme Editor is a feature developed by Shelf that provides an ability to configure custom themes for SSP to have it aligned with your organization’s brand guidelines or personal style preferences. The main users of this feature are Content Managers or Content Admins who are responsible for defining how the content on your organization’s SSP-based portal is structured and displayed to its visitors.


Prerequisites 

Though Theme Editor is a part of the bigger Shelf Self-Service Portal product, it needs to be additionally enabled by Shelf administrators on the Shelf side for your account plan. The number of custom themes you can create on your account is also limited and depends upon the plan.

Another prerequisite is that your user account in Shelf must possess the sufficient level of permissions to access the Shelf Admin Panel.




Using Theme Editor

This section contains information on how to access and use Shelf’s Theme Editor to build your own themes for your portals. 

In order to access Theme Editor, once logged in to Shelf under the relevant user role, go to the Admin Panel and find and select the Self-Service Configurator option in the sidebar panel there.


Figure 1. Accessing the Self-Service Portal configurations
Once done, you are redirected to the new window where you can (a) see your Self-Service Portals and access their settings, and (b) access the SSP themes section.

Figure 2. Accessing the SSP Themes section in the Self-Service Configurator

Once you have selected the Themes option in the sidebar panel there, you get to the Home > Organization > Themes page where you can view the available themes, both the prebuilt default themes - Classic and Modern, and the custom one - Minimal
This page is the starting point of the Theme Editor feature as it allows you to start creating a new theme from here by clicking the ADD THEME button in the upper right part of the page, or start editing a previously created custom theme by clicking the More Actions menu icon (...) next to the needed theme and selecting the Edit option from the popup list.

Note: 
Prebuilt default cannot be edited and deleted. You can only add or edit custom themes.


Adding a New Theme 

To add a new custom theme for your Self-Service Portal, perform the following steps:

  1. Click the ADD THEME button as shown in the figure above.
  2. Once clicked, you are directed to the New theme page that has the following look:

    Figure 3. Starting to add a new custom theme

  3. In the New theme page, you need to give a name to your new custom theme and can enter any desired description for it in the respective field. You need also to select one of the default themes to serve as a basis for the custom theme. Note that you cannot create a new custom theme from scratch: you always create it based on a default theme - Classic or Modern; however, once you have created at least one custom theme, you can also use it as a template for further custom themes. To do so, click anywhere in the Source Theme field and select the needed theme from the dropdown list. Finally, you can add some preview images for your new custom theme by clicking on the Upload button in the respective area. Once clicked, follow the prompts appearing on the screen to select and upload the needed picture for the preview image.
  4. Once all the data has been entered and selected, click the ADD button.

    Figure 4. Filling in the needed fields for your new custom theme


If no error messages have been displayed after clicking the ADD button and if the toast message reading “Successfully added theme” has been displayed, it means that the theme has been successfully created and added and you can see it in the list of available themes.

Figure 5. Viewing the newly added custom theme

Note: 
Adding a theme does not mean it is immediately ready for use. To make it operational, you need to publish it first. However, publishing is performed either in the theme editing mode that also allows you to configure your custom theme’s deeper settings or from the theme’s More Actions menu accessible from the Themes main page. Read the section below to learn more.



Editing a Custom Theme

To proceed to further configuration of your newly created custom theme, open the More Actions menu by clicking the respective button (...) and select the Edit option from the list that appears.

Figure 6. Accessing the theme editing mode

Once done, you are directed to the next page:


Figure 7. Viewing the custom theme in the editing mode

Note: 
It is necessary to mention that editing of a custom theme occurs on a deeper level and implies a high degree of frontend configurations. In order to be able to make editions to the theme, you need to have at least a basic understanding of JavaScript and HTML/CSS languages, because all settings are performed by way of modifying the existing or introducing the new JS and/or HTML/CSS code.
This Overview Guide will not detail the meaning of all JS and/or HTML/CSS strings and values but only provide an understanding of that where you can find the relevant settings you need to configure.

All settings of the theme and its components are split into blocks shown in the sidebar panel.

Figure 8. Viewing the theme settings panel

Table 1. Theme Settings Sections and Their Description


Settings Section Name

Description

GENERAL

This section contains the general settings of the theme, where you can edit its name, description, theme preview image, library (if any is published), save and publish the theme, and preview how the theme is going to look is applied to your Self-Service Portal. All these settings become available when you expand the GENERAL section and select the Theme Info option, as shown in Figure 8 above.

THEME FILES

This is the place where all configuration files of your theme are stored. This section is expandable/collapsible and opens/hides 4 (four) smaller sections.

Globals
This section contains two files that define the styles and scripts across your entire Self-Service Portals, without the need to edit individual blocks or pages of it. The first file - global-script.js - is the file that stores information and settings for scripts running across your entire portal. The settings are given in the form of JavaScript source code. The second file - global-styles.css - is where all the information about portal-wide styles resides and can be edited. The format of the file is HTML/CSS, and the source code must be the relevant HTML/CSS code.

Routes

This section contains subsections that correspond to your SSP’s pages, in our case - 404 (Page not found), Article (Article page), Folder (Folder page), Home, and Search. Each page-specific subsection in its turn has two files that define: index.jsx - an entry point to make your portal work properly by mapping the routes for the page and generating the relevant URLs, and styles.css - a collection of definitions for the page styles.



You can make changes to the index.jsx file to change various page-specific settings: edit layout of the page (display or hide certain components), reroute the page to show different icons, change the size of the icons, change the colors etc. All this needs to be done by editing the source code in JSX format which is a HTML-like syntax of JavaScript used to create React components: 

<>
 <HTMLComment text="API - Folder Route" />
 <link rel="preconnect" href="https://fonts.gstatic.com" />
 <link href="https://fonts.googleapis.com/css2?family=Montserrat:wght@400;700&display=swap" rel="stylesheet" />
 <main className={'Page'}>
   <Layout withSidebar={true}>
     <div className={"PageHolder"}>
       <h1 className={'H1Bold'} role="heading">{RouteData.currentPageGem.title}</h1>
       {RouteData.currentPageGem.description.length > 0 && <p className={'Description Description--folder'}>{RouteData.currentPageGem.description}</p>}
       {RouteData.topFoldersWithChildren.length === 0 && RouteData.topArticles.length === 0 && (
         <div className={'EmptyFolderWithIcon'}>
           <ColoredIcon
             icon={'folder'}
             iconSize={'65px'}
             holderSize={'65px'}
             color={'#606d84'}
           />
           <span className={'EmptyFolderSign'}>
           <I18NT t={'ssp-app.folder.noContent'} />
         </span>
         </div>
       )}
       <TopArticles />
       <TopFolders twoFolders={true} />
     </div>
     <RightSection />
   </Layout>
 </main>
</>

Components

This section stores the settings for all components available on your SSP pages. 


Each of the components also has two defining files, the index file that defines routing and various other settings of the component, and the styles file that defines how the component is styled on the page and in respect to other components. The settings in the index file are represented as the source code in JSX format which is a HTML-like syntax of JavaScript used to create React components.

In the Components section, you can also create new components and delete the existing ones if you no longer need them.

To create a new component, click the plus (+) icon next to the section name and then in the appearing field enter the name for your new component and click the save icon.


You can create as many components as you want, if the theme size does not exceed 6 Megabytes. Maximum length of the component name must not exceed 25 characters.

Once the component is created, it is displayed in the sidebar and can be edited, that is you can enter the respective defining source code in the index and styles files.



You can also delete a component when you don’t need it. To do so, hover over the name of the needed component to show the delete icon and then click it.



Confirm your decision to delete the component in the confirmation popup window. 

Once done, the component is put to the deletion queue and becomes deleted only when the theme is saved.

i18n

This section contains localization files for your custom theme. It can help you adapt the theme to different markets of your visitors/customers. Note that the supported languages for the custom theme localization are only those which are enabled in the Customize section of the Shelf Admin panel. In our exemplary case, these are English, German, and Spanish.

You can add the theme localization file by clicking the plus (+) icon next to the section name and then selecting the needed language from the dropdown list.



Once the new localization file is created, it is displayed under the section name, and you can enter the respective localization configuration in the JSON format.



You can also delete no longer needed localization files in this section. To do so, hover over the relevant file to reveal the delete icon and click it. Then confirm your choice in the popup window that appears. Note that the file is not deleted unless you save the theme.




                   

Previewing a Custom Theme 

At any step of your custom theme editing you can check how the changes you make affect the look of your Self-Service Portal. For this purpose, click the Preview button in the upper part of the window.

Figure 9. Accessing the theme preview

You can also preview changes in the live mode even in the code editor. The preview feature picks up the latest change and displays the resulting appearance of the portal. Actually, you do not even need to edit the code, you can just click the Preview button to see how your current custom theme influences the appearance and layout of your Self-Service Portal.

Figure 10. Accessing the theme preview in the code editor

Once you click the Preview button, you will see how the changes you make affect the layout and appearance of the portal.

Figure 11. Previewing the custom theme applied to SSP
Shelf recommends using the Theme Editor with one Preview page per one theme editing session.

You can also select the library - Self-Service Portal - you want your new or edited custom theme to preview for or apply to. To do so, click the respective field and choose the needed library from the dropdown list.

Figure 12. Selecting the library for the theme in the editing mode

Figure 13. Selecting the library for the theme in the code editor

Note that only the published libraries are available for selection, that is there must be at least one published Self-Service Library. The dropdown list with available libraries is scrollable and searchable.


                                          

Publishing a Custom Theme 

You can publish the custom theme you have added but not yet published, at any stage of its further editing. To do so, when in the editing mode, find and click the SAVE AND PUBLISH button.

Figure 14. Publishing the previously non-published theme, from the code editor

Then, confirm your choice in the respective popup window. 


Figure 15. Confirming the theme publishing

Once done, you are redirected to the Themes main page where you can view that the status of the theme has changed to Published.

Figure 16. Checking the theme status

Once your new custom theme has been published, it becomes available in the Theme tab of your Self-Service Portal configuration. To check it, follow the below steps:
  1. While in the Admin Panel, go to the Self-Service Configurator and select the Portals section in the sidebar panel.
  2. In the Self-Service Portals table grid that appears, find the needed portal, open its More Actions menu by clicking the respective icon (...), and select the Configure Portal option in the popup list. 

    Figure 17. Accessing the Self-Service Portal configuration

  3. In the selected Self-Service Portal’s configuration window that appears, find and open the Theme tab to check whether the custom theme you have just published is available or not. When it is displayed on the list of themes, you can select and assign it to the respective Self-Service Portal. 
    Figure 18. Selecting and assigning a custom theme to a Self-Service Portal
Another option to publish the previously unpublished theme is from the More Actions menu (...) next to the needed theme in the Themes main window. Open the menu and select the Publish option from the popup list. Confirm your choice in the popup window that appears, and check the status of the theme in the Themes main window.

Figure 19. Publishing a custom theme from the More Actions menu


If the theme has been already published before its editing, there is no SAVE option but only SAVE AND PUBLISH.

Figure 20. Publishing the theme that has been already published


                           

Unpublishing a Custom Theme 

If your custom theme has not been applied to the Self-Service Portal, it can be easily unpublished from the More Actions menu (...). Open the menu and select the Unpublish option from the dropdown list.

Figure 21. Unpublishing a custom theme not linked to any Self-Service Portals
If no errors occur, the theme becomes unpublished and you are redirected to the Themes main page where you can check its status that must be changed to Unpublished.

If the custom theme has already been associated with some Self-Service Portal(s), you first need to unassign that theme from it (them). Check the Theme Settings Chapter of the Shelf Self-Service Portal Introductory Guide for details on how to assign or unassign themes.

Figure 22. Viewing the options for the custom theme associated with a Self-Service Portal
Once the theme has been unassigned from the SSP, open its More Actions menu and select the Unpublish option from the dropdown menu as shown in Figure 18 above. The theme becomes unpublished and changes its status on the Themes main page.


                            

Deleting a Custom Theme 

If you no longer need a custom theme you have previously created and added, you can delete it. To do so, open the theme More Actions menu by clicking on the respective button next to it, and select the Delete option from the dropdown list.

Figure 23. Deleting the custom theme

Confirm your decision in the popup window that appears. 


Figure 24. Confirming the custom theme deletion

The theme becomes deleted from the theme list on the Themes main page.

Note that you can only delete those custom themes that have not been assigned to any Self-Service Portals. If the theme is linked to any SSP, you need first to unassign it. See more details about it in the Unpublishing a Custom Theme section above.