Technical Considerations for an OrchestraCMS Website

Now that you are familiar with the basic concepts related to managing pages and content when building websites with OrchestraCMS, we turn our attention to technical considerations designers and developers should be aware of.

Like any Web Page, OrchestraCMS Web Pages…

• prefer clean, valid markup, CSS, and JavaScript
• can include dynamic content elements (OrchestraCMS itself relies on being able to dynamically load content into its pages)
• require planning and thoughtful care throughout their lifecycle

Learn OrchestraCMS

Anyone developing pages or content for an OrchestraCMS website should have first-hand knowledge of how content authors and site administrators use OrchestraCMS. You should become familiar with standard features and capabilities of Salesforce technologies like Chatter and Ideas that can be exposed through OrchestraCMS. In some instances, extending behaviour may be possible, but could be development intensive.

Learn how to use OrchestraCMS’s content targeting to control the content items seen by Salesforce Community users based on user-specific data in their user record, like geographic location and more.

Learn how the out-of-the-box hierarchical taxonomy system works for tagging content and for retrieving matching content items.

Learn the significance of Content Types and Content Templates and how to organize them. As OrchestraCMS terminology, each of these is specific terms with a distinct meaning, but are often conflated.

Discover the abilities of OrchestraCMS’s Content Template Creator to rapidly create solution-specific content templates

Learn OrchestraCMS’s Out‐of‐the‐box Content Templates

Whenever possible, use the standard content templates available within OrchestraCMS. It will save development time if you don’t have to create solution-specific content editors and content templates. With only a few exceptions, OrchestraCMS does not provide CSS for its standard content templates; that is part of the solution-specific development work required for each site.  

Almost all interactive aspects of an OrchestraCMS page require solution-specific JavaScript. Only a few of the standard content templates used by OrchestraCMS provide any sort of user interaction out-of-the-box.  For example, all front-end (browser-based) validation of form input represents solution-specific development. Depending on the site’s requirements, the following content templates may be especially useful; designers and developers should be familiar with both the markup they produce and what facilities the content author has when editing them:

Class Styled Menu

• Expect that advanced menu designs may exceed Class Styled Menu’s abilities and therefore require custom development, either using client-side JavaScript or by creating a solution-specific content template

Text Block

• Understand the capabilities of OrchestraCMS’s rich text editor, CKEditor

Article Detail, Article Summary, Article Summary with Small Image, Article Detail with Related Articles

• Four content templates for a general purpose news article content item

Custom HTML

• For advanced users only, but allows the savvy content author to include manually-edited HTML, JavaScript, or CSS when required.  Warning: if you use this content template frequently, you’re doing OrchestraCMS wrong!

Plain Text

• Use this for small bits of simple text with absolutely no embedded HTML

Image

• May optionally be wrapped by a hyperlink

Basic Form

• Makes it easy for website users to add records to Salesforce objects
• Formatting options are limited (table-based layout)
• Provides some server side, but no front-end validation
• Radio buttons, checkboxes, or drop-down lists based on Salesforce picklist data fields are dynamically loaded after other parts of the form

Breadcrumb

• Navigation path to the current page

Taxonomy Menu

• Offers navigational abilities to explore a content-based dataset that has been tagged with taxonomy categories

Slider

• Has many options, but of course it cannot support all possible carousel design patterns
• Most carousel designs that include mixed content per slide beyond one image and one text element will require a custom solution such as using a third-party slideshow library and/or a custom content template for the slide

OrchestraCMS does not have a purpose-built, out-of-the-box content template suitable for defining video content.  Including a video player is typically a manual markup procedure - for example, copy-and-pasting an HTML snippet provided by a video hosting service.

Custom development can assist with a site-specific solution.  When the out-of-the-box content templates are insufficient for your needs, create your own using OrchestraCMS’s Content Template Creator, or by having a developer create solution-specific content templates manually.

Solution‐Specific Content Templates

Custom content templates should assume as little as possible about the size of the container in which they are placed; in general, they should fill the width made available to them.  It is best practice for custom content templates to wrap their markup in a distinctive container - for example, <div class="watermelon">.

Guidelines for Markup and CSS

Avoid making the content author manually edit CSS class names or in-line styles when editing content.  When required, solution-specific content templates can be developed to reduce the burden of the content author specifying detailed markup patterns.  Be aware that including all of a page’s production CSS rules within the OrchestraCMS page editor may cause unwanted side effects. For example, the unqualified rule select { position: relative; } may be correct for the production version of the page, but it will break OrchestraCMS dialogs if it is present in the page editor.

Use

• body.OCMSEdit
• body.OCMSPreview
• body.OCMSProduction

in CSS selectors when necessary to target the appropriate environments. Alternatively, separate the CSS enough so that only the rules that provide the overall WYSIWYG page structure and general appearance are present in the page editor, omitting CSS rules that are relevant only to the published page.

Iframes may be used, but as on all web pages, their use comes with many restrictions that can limit their suitability.

Avoid designs with insufficient text contrast, even if the client has not specifically mandated accessibility best practices.

Designers must know if the website will be translated into multiple languages and plan accordingly, especially with respect to the length of text labels.  For example, a button labelled “Events” is likely to become “Veranstaltungen” when translated into German; the visual design must be flexible enough to accommodate for such variations.

Similarly, any reference designs or page prototypes should use a variety of realistic, simulated content.  There should be minimal or no, use of lorem ipsum.  Use non-ideal sample text of varying lengths to challenge robustness of the markup and CSS.  Image size requirements should have some flexibility; discuss with the clients about their expertise in creating media resources.  For example, it may be too onerous to require exact pixel dimensions for all images.

Living in the Salesforce Cloud

There is limited ability to install server-side software, quite unlike the Apache server ecosystem many web developers are used to. For example, node.js can provide an efficient platform for developing prototype pages, but its related technology does not easily transfer to the Salesforce environment.  The Salesforce multitenant environment places (reasonable) limits on the use of computing resources.  Excessively inefficient or demanding server-side processing may cause difficulties.  As with all web pages, developers should think strategically and try to minimize server requests.

Other

The CSS and JavaScript files that are included in a page are determined by the page template.  Consequently, this is managed by the site developer, not the content author. An exception to this would be including CSS or JavaScript as page content by using the Custom HTML content template.

OrchestraCMS pages assume and require that JavaScript is enabled in the browser. All CSS and JavaScript that is active within a page template must be aware of the four possible OrchestraCMS page modes:

• Page Editor
• Preview
• Secure Preview
• Production

In particular, the page editor context often requires special attention to prevent conflicts with the OrchestraCMS web interface.  Some CSS rules might have unintended consequences by affecting elements of the OrchestraCMS web interface. Page initialization JavaScript will not be applicable from the page editor context and should not be executed.

Working with Stantive Product Enablement

When page prototype implementations are created outside of Stantive Professional Services, the agency is required to provide fully working prototype pages that demonstrate all required dynamic content load and responsive design behaviors.

Follow Stantive PE guidance for integrating CSS and especially JavaScript into the OrchestraCMS run-time environment.  Expect that some page content may be dynamically loaded; if there is JavaScript to be executed after the content is loaded, a modular approach is required that can be used equally well in both the prototype and production environments.

It is imperative to coordinate development efforts with the Stantive PE team to ensure all required JavaScript can be efficiently integrated.

JavaScript and JavaScript Libraries

OrchestraCMS includes jQuery and jQueryUI functionality on its pages.  If a different version of jQuery is required, care must be taken to manage it using jQuery.noConflict(), being sure to leave OrchestraCMS’s version of jQuery undisturbed. The developer may load other JavaScript libraries or frameworks on the page as required.  Keep JavaScript functionality granular and nicely factored and commented.

Page initialization JavaScript should either detect the OrchestraCMS page editor environment and not perform any operations that make no sense in that context, or simply be omitted from the page for the page editor environment.  This can be done using Visualforce conditional logic in the page template.

Categories of Dynamic Content Loading

A typical OrchestraCMS-based website will have several pieces of page content that are dynamically loaded; that is, they are not in the initial document delivered to the browser by the Salesforce server. Instead, client-side operations use AJAX requests to get information from a remote server and display the results within the page. Typically the remote server is the Salesforce org that hosts the site, but it could be another. For example, it may be a third-party server that provides stock feed data.

Dynamic content-loading within an OrchestraCMS website can be divided into three categories:

• Load Token Replacement
• Content Completion
• Event-based Loading

It is sometimes necessary to know when a dynamic content loading operation has completed. For example, some content items may require minor markup changes; or another, independent page element may need to be regenerated when the page’s content changes. Each of the above categories requires different techniques for determining when all the relevant content has been fully loaded into the page.

Load Token Replacement

Most OrchestraCMS pages will have a page cache file that will be delivered to the browser instead of requiring the Salesforce server to generate the page from its many content items each time a request for that page is received. OrchestraCMS maintains these cache files and they greatly improve site performance.

However, not all content items can be saved to a page cache file. Some content items need to show up-to-the-minute data for information that changes throughout the day. Some content items should only be shown to certain users, such as those in a given geographic region. Content items like this will not be saved into a page cache. Instead, a placeholder “dynamic load token” is inserted. Once delivered to the client’s browser as part of the initial static page load, these load tokens are automatically replaced with up-to-date content via AJAX requests that respect the user’s access permissions and targeting considerations.

When is Load Token Replacement Content on the Page?

Once all dynamic load tokens have been replaced, OrchestraCMS will invoke callback functions that have been registered with $(document).ocmsDynamicLoadFinished() . Therefore, if actions are required after certain content items are on the page, instead of doing them within a $(document).ready() callback function, do them within a callback function registered with ocmsDynamicLoadFinished() .

The developer can rely on callback functions registered with ocmsDynamicLoadFinished() still being called even when there are no dynamic load tokens on the page.

$(document).ocmsDynamicLoadFinished(function() {
    // Execute code when all dynamic load tokens have been replaced.
});

Content Completion

For a few content items, the initial markup that is delivered to the browser is incomplete; it’s just a first-stage down payment for the full content yet to come. The second stage happens when the markup delivered in the first stage is used to retrieve the rest of the content dynamically. When a content item relies on one or more AJAX requests to complete the loading of its markup, we call everything that follows Content Completion loading.

Two everyday examples of this occur with the Form and Taxonomy content templates.

Forms

The fields/values/labels in an OrchestraCMS form are populated via Ajax call after the initial page load.  In order to format these elements you would need to fire your functions doing the work on $(document).ocmsAjaxFormLoadFinished(yourFunctionHere).

$(document).ocmsAjaxFormLoadFinished(function() {
    // Execute code when all form load requests have been completed.
});

Taxonomy Loader

The content loaded by a taxonomy loader is retrieved via Ajax call after the initial page load.  To format the elements returned you would need to fire your functions doing the work on $(document).ocmsTaxonomyLoadFinished(yourFunctionHere).

$(document).ocmsTaxonomyLoadFinished(function() {
    // Execute code when all taxonomy load requests have been completed.
});

Event‐based Loading

This category of dynamic content loading is familiar to many web users today, and is typified by, say, a button on a news page labeled “View More” that inserts more news items into the page when clicked. A weather page that automatically updates forecast information every 15 minutes is another example of event-based dynamic content loading.

When is My Content on the Page?

Again, this will be handled on a case-by-case basis. There are very few out-of-the-box OrchestraCMS content templates that use event-based loading.

Developers of solution-specific content templates that provide this sort of interaction are free to use whatever approach works for their use cases.

Taxonomy Loader

When a taxonomy loader’s optional “View More” button is provided, the content loading operation invoked by clicking it will follow the same global JavaScript callback conventions described above. That is, when the additional content items have been loaded, two different pre-determined global JavaScript functions will be invoked if they exist.

Forms

When submitted form data fails server-side validation tests, OrchestraCMS will write error messages into the DOM, but it does not provide a JavaScript API for signalling this action.

Page Load Completed

When each of the three other events have completed ocmsDynamicLoadFinished, ocmsTaxonomyLoadFinished and ocmsAjaxFormLoadFinished the ocmsPageLoadFinished event will fire.  This event shares the same syntax as the other three $(document).ocmsPageLoadFinished(yourFunctionHere).

$(document).ocmsPageLoadFinished(function() {
    // Execute code when all dynamic load tokens have been replaced and taxonomies and form requests have completed.
});