Social Component Framework social-component-framework

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:

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

Overview 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 how-pages-are-rendered-for-client

Component Customization and Extension 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.

Server-Side Framework server-side-framework

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

Java APIs 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 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 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

GET Request

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

HTTP API - POST Requests 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.

Storage Resource Provider (SRP) storage-resource-provider-srp

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

Server-side Customizations 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 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 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 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" />

Handlebars Helpers handlebars-helpers

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

Client-Side Framework client-side-framework

Model-View Javascript 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 css-conventions

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

Client-Side Customizations 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 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 troubleshooting

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