Salesforce Community Developer Guide


Document Version History

Version number

Modified by

Modifications made

Date modified

Status

1.0

Shelf

Initial release of the Developer Guide on Salesforce Community. New structure developed, sectioning introduced, and other standardization efforts taken.

16 March 2022

Expired

1.1

Shelf

The document is updated as a result of new Shelf component deployment and a new Slesforce package release.

30 March 2022

Expired

1.2

Shelf

The Shelf Group List Component section updated: Folder ID > Filtering Category.

07 April 2022

Expired

1.3

Shelf

The document has been restructured and reauthored in accordance with the change of approach to the Shelf Components development instructions.

26 April 2022

Expired

1.4

Shelf

The document has been updated with the new section on the styling and designing the Shelf components.

23 May 2022

Expired

1.10*

Shelf

Link to the new version of the Salesforce installation package has been added. Document version has been updated. No other major changes.

22 June 2022

Expired

1.11

Shelf

Link to the new version of the Salesforce installation package has been added. Document version has been updated. No other major changes.

6 July 2022

Expired

1.12

Shelf

Link to the new version of the Salesforce installation package has been added. Document version has been updated. No other major changes.

12 July 2022

Expired

1.13

Shelf

Link to the new version of the Salesforce installation package has been added. Document version has been updated. No other major changes.

19 July 2022

Active



* Numbering of the Developer Guide versions has been brought to compliance with the Salesforce Package version numbering, so the Guide version is now 1.10 and matches the Salesforce Packages version, which is 1.10 as well.


Salesforce Package Version

Package

Download link

V.1.0

https://login.salesforce.com/packaging/installPackage.apexp?p0=04t7Q000000PtAR

V.1.1

https://login.salesforce.com/packaging/installPackage.apexp?p0=04t7Q000000Puvo

V.1.2

https://login.salesforce.com/packaging/installPackage.apexp?p0=04t7Q000000PxLK

V.1.3

https://login.salesforce.com/packaging/installPackage.apexp?p0=04t7Q000000Pz7P

V.1.4

https://login.salesforce.com/packaging/installPackage.apexp?p0=04t7Q000000Q0XE

V.1.6

https://login.salesforce.com/packaging/installPackage.apexp?p0=04t7Q000000Q2FM

V.1.7

https://login.salesforce.com/packaging/installPackage.apexp?p0=04t7Q000000Q6SV

V.1.8

https://login.salesforce.com/packaging/installPackage.apexp?p0=04t7Q000000Q9TV

V.1.9

https://login.salesforce.com/packaging/installPackage.apexp?p0=04t7Q000000QDMu

V.1.10

https://login.salesforce.com/packaging/installPackage.apexp?p0=04t7Q000000QEJW

V.1.11

https://login.salesforce.com/packaging/installPackage.apexp?p0=04t7Q000000QGqx

V.1.12

https://login.salesforce.com/packaging/installPackage.apexp?p0=04t7Q000000QHHL

V.1.13

https://login.salesforce.com/packaging/installPackage.apexp?p0=04t7Q000000QIr8 







Introduction

Salesforce Community Cloud is an online social platform for companies to create branded sites connecting customers, employees, and partners with each other. 

The platform provides them the records and data they need to accomplish their work efficiently.


This document is designed to help Salesforce developers to understand how to work with the Shelf components on the Salesforce Community Cloud and provides them with valuable information on how to set the proper search parameters. 


Software Requirements

No matter what tool is used by developers for the programming tasks, testing efforts must be taken using the latest version of Google Chrome or Mozilla Firefox web browsers.  Other browsers are supported but can be subject to random errors and failures. 

For installing the latest versions of the recommended web browsers, visit their respective pages: 




Using ShelfCategoryController search method

This method enables you to search for various outcomes, such as a list of Gems matching your requirements. Below is the description of how you need to build and send your search requests to get the needed result.


To get a list of Gems, perform a search request and use ShelfSearchController class method search as shown in the code snippet below.

Make sure to enter the following parameters in your search request.

Figure 1. Search code


Parameters in this search request means the following:
  • communityId - ID of the selected community (required),
  • term - search term, should be empty  ''
  • recordsFrom - starting value for the search result, should be 0
  • parentId - folder/library ID for the search, should be empty  ''
  • size - number of the search results to be returned, default 100
  • language - language code, f.e. 'en'
  • categories - list of IDs for categories, including ID for the groupGem category for this community, also dsTypes, geography, and knowledge categories could be added; all of them being sent as a list of strings
  • libIds - list of IDs for libraries to be included in search request (not required)

Figure 2. Code of the real search request example

Figure 3. Code of the real search request example without libIds


Run preparation

To perform a search request, you need to indicate the respective communityId and categoryId values for the groupGem category.

  1. To get the ID of your community, you can check all communities in your organization and select the proper one by its name. For this purpose, execute a query and find the needed ID.
    For example, 0DBf4000000XZg3GAG is a required id for your community.
  2. To get ID for the product group (groupGem category), send a respective request to Shelf API to get a list of all available categories for your Shelf environment.

    Figure 4. Code of the request to Shelf API

    In the code above, 0DBf4000000XZg3GAGis the ID of your community.
  3. Look through the list of received categories in result.payload to find and map the required categories and then use these IDs as an array of categories.

    Figure 5. Code of the response example


In the code above, "id":"01FVAJAB5M5V2ATPB5ESQMHMH5","name":"groupGem" is the required category. Therefore, you can now use 01FVAJAB5M5V2ATPB5ESQMHMH5 to perform your search request. If you need to filter results by dsType or another additional category, pass these category IDs to the categoriesId parameter of the shelf_Com.ShelfSearchController.search() method.

Library Ids you can get from your Shelf account - from url for selected Library


In order to avoid performing the same preparation requests to get IDs of the needed community and groupGem category every time, you can hardcode it in the APEX class or save as the custom metadata.

The result of the search request performed via the shelf_Com.ShelfSearchController.search method with the required parameters is 11 Gems of the groupGem category, as shown below.

Figure 6. Search request result

You can use this data for different purposes, for example to create a static link to the selected Gem.


Creating unique link 

To create a link to a groupGem item, you can use _source.title as a title for the link and _source.gemId as a relative link href.
Depending on the configuration of your Shelf Group List Component, you can use the Group Page API name as the Base URL. In our case, this name is Article, as shown in the figure below.

Figure 7. Shelf Group List Component properties window

Note:
Values in the URL and API Name and URL fields in the page properties should be the same. If the different values are used, there might be an unexpected error returned.

Figure 8. Viewing page properties

Finally, the static link href will be ‘article?id’ + gemId, like 
article?id=b3bc425c-6b84-4bd3-b0ac-187e3ede2fa2

You can also create a link to a single gem. For this purpose, use the Gem Detail Page API name as the link prefix, for example: gem_detail?id=b3bc425c-6b84-4bd3-b0ac-187e3ede2fa2

To switch to a specific language, add the language parameter to the URL, for example: 
gem_detail?id=b3bc425c-6b84-4bd3-b0ac-187e3ede2fa2&language=en_us




Shelf Components Style and Design

Shelf has implemented the following approach to the Shelf components styling and designing:
  1. All the components’ styles and design are based on the standard SLDS (Salesforce Lightning Design System) attributes.
  2. All custom components’ styles and design are imported from a static resource file that is configured by Shelf Support Team upon request.

Example of the current static resource file

:root {
    --c-hns_titleFontSizeXL: 66px;
    --c-hns_titleFontSizeLg: 44px;
    --c-hns_titleFontSizeMd: 35px;
    --c-hns_titleFontSizeSm: 22px;
    --c-hns_subtitleFontSizeXL: 42px;
    --c-hns_subtitleFontSizeLg: 22px;
    --c-hns_subtitleFontSizeMd: 18px;
    --c-hns_subtitleFontSizeSm: 14px;
    --c-hns_subtitleColor: #333;
    --c-hns_linkFontSizeXL: 30px;
    --c-hns_linkFontSizeLg: 18px;
    --c-hns_linkFontSizeMd: 15px;
    --c-hns_linkFontSizeSm: 13px;
    --c-hns_fontFamilyNeue: Helvetica Neue, Helvetica;
    --c-hns_lineHeight: 1.05;
    --c-hns_lineHeightSubtitle: 1.5294717647;
    --c-hns_imageBackgroundColor: #FFF;
    --c-hns_limeGreenColor: #78BE20;
    --c-hns_lightGreenColor: #A4D65E;
    --c-hns_darkGreenColor: #5CA425;
    --c-hns_darkGrayColor: #696969;
    --c-hns_mediumGrayColor: #9EA2A2;
    --c-hns_lightGrayColor: #D4D4D4;
    --c-hns_whiteColor: #FFF;
    --c-hns_darkGrayColor: #4D4D4D;
    --c-hns_titleColor: #515151;
}


Shelf Gem Page and Group Gem Page components styling

The new version of the Shelf Components package for Salesforce Community Cloud has the advanced styling features for the Gem Page and Group Gem Page components. These features deal with image and video embedding and display in the content stored in Shelf NextGen KMS.


Styling images and videos in Shelf Gem Page component

The embedding of an image occurs on the Shelf side in the respective Gem and is performed by means of adding a new custom class - class="fr-fic fr-dib hero-image" - to the source code of the image added (or embedded) to the Gem. 

Example of the code: 

<p><img src="https://s3.amazonaws.com/gemshelf-stag/eb1541e7-ce1a-4d76-865d-f184468b3544%2Fgems%2F82adf5f3-566e-4fe5-a48f-2e71de394a26%2Fwiki%2Fimages%2F1695398515404-Beoplay-EX-Anthracite-Oxygen-Hero.png" style="width:888;" class="fr-fic fr-dib hero-image"></p>

where https://s3.amazonaws.com/gemshelf-stag/*************.png is the location of the image in Shelf NextGen KMS, in particular - in some Image type Gem, which needs to have the Public category and be stored in a library having the same category. 

The embedding of a video is also enabled on the Shelf side in a Gem by means of the code strings. The exemplary template is given below. 

<div class="slds-grid">

 <div class="slds-col video-container">{iframe}</div>

 <div class="slds-col">

  <h1>{title}</h1>

  <p>{description}</p>

 </div>

</div>


where {iframe} needs to be replaced with the video embedding code copied from the respective storage source. The Title and Description details should be also added as needed.


Styling images in Shelf Group Gem Page component 

This component supports the display of two embedded images which are added by two new classes to the Gem’s source code The embedding of an image occurs on the Shelf side in the respective Gem and is performed by means of adding a new custom class - class="fr-fic fr-dib hero-image" - to the Gem’s source code. 

Example of the code:

<p><img src="https://s3.amazonaws.com/gemshelf-stag/eb1541e7-ce1a-4d76-865d-f184468b3544%2Fgems%2F82adf5f3-566e-4fe5-a48f-2e71de394a26%2Fwiki%2Fimages%2F1695398515404-Beoplay-EX-Anthracite-Oxygen-Hero.png" style="width:888;" class="fr-fic fr-dib hero-image"></p>

where https://s3.amazonaws.com/gemshelf-stag/*************.png is the location of the image in Shelf NextGen KMS, in particular - in some Image type Gem, which needs to have the Public category and be stored in a library having the same category. 

The embedding of a video is also enabled on the Shelf side in a Gem by means of the code strings. The exemplary template is given below. 

<div class="slds-grid">

 <div class="slds-col video-container">{iframe}</div>

 <div class="slds-col">

  <h1>{title}</h1>

  <p>{description}</p>

 </div>

</div>


where {iframe} needs to be replaced with the video embedding code copied from the respective storage source. The Title and Description details should be also added as needed.