Social Component Framework | Adobe Experience Manager

Last update: May 3, 2023

Topics:
Communities

CREATED FOR:

User

CAUTION

AEM 6.4 has reached the end of extended support and this documentation is no longer updated. For further details, see our technical support periods. Find the supported versions here.

The social component framework (SCF) simplifies the process of configuring, customizing, and extending Communities components on both server-side and client-side.

The benefits of the framework:

Functional: Out-of-the-box ease of integration with little or no customization for 80% of use cases
Skinnable: Consistent use of HTML attributes for CSS styling
Extensible: Component implementation is object-oriented and light on business logic - easy to add incremental business login on server
Flexible: Simple logic-less javascript templates that are easily overlayed and customized
Accessible: The HTTP API supports posting from any client, including mobile apps
Portable: Integrate/embed into any webpage built on any technology

Explore on an author or publish instance using the interactive Community Components guide.

Overview

In SCF, a component is comprised of a SocialComponent POJO, a Handlebars JS Template (to render the component), and CSS (to style the component).

A Handlebars JS Template may extend the model/view JS components to handle user interaction with the component on the client.

If a component needs to support modification of data, the implementation of the SocialComponent API can be written to support edit/save of data similar to model/data objects in traditional web applications. In addition, operations (controllers) and an operation service may be added to handle operation requests, perform business logic, and invoke the APIs on the model/data objects.

The SocialComponent API may be extended to provide data required by a client for a view layer or an HTTP client.

How Pages are Rendered for Client

chlimage_1-25

Component Customization and Extension

To customize or extend the components, you write only the overlays and extensions to your /apps directory which simplifies the process of upgrading to future releases.

For Skinning
- Only the CSS needs editing
For Look and Feel
- Change the JS Template and CSS
For Look, Feel and UX
- Change the JS Template, CSS and extend/override Javascript
To modify the information availble to the JS Template or to the GET endpoint
- Extend the SocialComponent
To add custom processing during operations
- Write an OperationExtension
To add a new custom operation
- Create a new Sling Post Operation
- Use existing OperationServices as needed
- Add Javascript code to invoke your operation from the client side as needed

Server-Side Framework

The framework provides APIs to access functionality on the server and support interaction between the client and server.

Java APIs

The Java APIs provide abstract classes and interfaces which are easily inherited or subclassed.

The main classes are described on the Server-side Customization page.

Visit Storage Resource Provider Overview to learn about working with UGC.

HTTP API

The HTTP API supports ease of customization and choice of client platforms for PhoneGap apps, native apps, and other integrations and mashups. Further, the HTTP API allows a community site to run as a service without a client, such that framework components can be integrated into any webpage built on any technology.

HTTP API - GET Requests

For every SocialComponent, the framework provides an HTTP-based API endpoint. The endpoint is accessed by sending a GET request to the resource with a ‘.social.json’ selector + extension. Using Sling, the request is handed to the DefaultSocialGetServlet.

The DefaultSocialGetServlet

Passes the resource (resourceType) to the SocialComponentFactoryManagerand receives a SocialComponentFactory capable of selecting a SocialComponentrepresenting the resousrce.
Invokes the factory and receives a SocialComponentcapable of handling the resource and request.
Invokes the SocialComponent, which process the request and returns a JSON representation of the results.
Returns the JSON response to the client.

GET Request

A default GET servlet listens to .social.json requests to which the SocialComponent responds with customizable JSON.

chlimage_1-26

HTTP API - POST Requests

In addition to the GET (Read) operations, the framework defines an endpoint pattern to enable other operations on a component, including Create, Update and Delete. These endpoints are HTTP APIs that accept input and respond with either an HTTP status codes or with a JSON response object.

This framework endpoint pattern makes CUD operations extensible, reusable and testable.

POST Request

There is a Sling POST:operation for every SocialComponent operation. The business logic and maintenance code for each operation are wrapped in an OperationService which is accessible through the HTTP API or from elsewhere as an OSGi service. Hooks are provided supporting pluggable operation extensions for before/after actions.

chlimage_1-27

Storage Resource Provider (SRP)

To learn about handling UGC stored in the community content store, see

Storage Resource Provider Overview - Introduction and repository usage overview
SRP and UGC Essentials - SRP API utility methods and examples
Accessing UGC with SRP - Coding guidelines

Server-side Customizations

Visit Server-Side Customizations for information on customizing the business logic and behavior of a Communities component on the server-side.

Handlebars JS Templating Language

One of the more noticeable changes in the new framework is the use of the Handlebars JS templating language (HBS), a popular open-source technology for server-client rendering.

HBS scripts are simple, logic-less, compile on both server and client, are easy to overlay and customize, and naturally bind with the client UX because HBS supports client side rendering.

The framework provides several Handlebars helpers that are useful when developing SocialComponents.

On the server, when Sling resolves a GET request, it identifies the script that will be used to respond to the request. If the script is an HBS template (.hbs), Sling will delegate the request to the Handlebars Engine. The Handlebars Engine will then get the SocialComponent from the appropriate SocialComponentFactory, build a context, and render the HTML.

No Access Restriction

Handlebars (HBS) template files (.hbs) are analogous to .jsp and .html template files, except they may be used for rendering both in the client browser and on the server. Therefore, a client browser requesting a client-side template will receive an .hbs file from the server.

This requires that all HBS templates in the sling search path (any .hbs files under /libs/ or /apps) can be fetched by any user from author or publish.

HTTP access to .hbs files may not be prohibited.

Add or Include a Communities Component

Most Communities components must be added as a Sling addressable resource. A select few of the Communities components may be included in a template as a non-existing resource to allow for dynamic inclusion and customization of the location at which to write user generated content (UGC).

In either case, the component’s required client libraries must also be present.

Add a Component

Adding a component refers to the process of adding an instance of a resource (component), such as when dragged from the component browser (sidekick) onto a page in author edit mode.

The result is a JCR child node under a par node, which is Sling addressable.

Include a Component

Including a component refers to the process of adding a reference to a “non-existing” resource (no JCR node) within the template, such as using a scripting language.

As of AEM 6.1, when a component is dynamically included instead of added, it is possible to edit the component’s properties in author *design *mode.

Only a select few of the AEM Communities components may be dynamically included. They are:

The Community Components Guide allows includable components to be toggled from being added to being included.

When using Handlebars templating language, the non-existing resource is included using the include helper by specifying its resourceType:

{{include this.id path="comments" resourceType="social/commons/components/hbs/comments"}}

When using JSP, a resource is included using the tag cq:include:

<cq:include path="votes"
 resourceType="social/tally/components/voting" />

NOTE

To add a component to a page dynamically, instead of adding or including it in a template, see Component Sideloading.

Handlebars Helpers

See SCF Handlebars Helpers for a list and description of custom helpers available in SCF.

Client-Side Framework

Model-View Javascript Framework

The framework includes an extension of Backbone.js, a model-view JavaScript framework, to facilitate development of rich, interactive components. The object-oriented nature supports an extensible/reusable framework. Communitication between client and server is simplified by means of the HTTP API.

The framework leverages server side Handlebars templates to render the components for the client. The models are based on the JSON responses generated by the HTTP API. The views bind themselves to HTML generated by the Handlebars templates and provide interactivity.

CSS Conventions

The following are recommended conventions for defining and using CSS classes:

Use clearly namespaced CSS class selector names and avoid generic names such as ‘heading’, ‘image’, etc.
Define specific class selector styles so the CSS stylesheets work well with other elements and styles on the page. For example: .social-forum .topic-list .li { color: blue; }
Keep CSS classes for styling separate from CSS classes for UX driven by JavaScript

Client-Side Customizations

For customizing the appearance and behavior of a Communities component on the client-side, reference Client-Side Customizations, which includes information on:

Feature and Component Essentials

Essential information for developers is described in the Feature and Component Essentials section.

Additional developer information may be found in the Coding Guidelines section.

Troubleshooting

Common concerns and known issues are described in the Troubleshooting section.

recommendation-more-help