Best practices for developers
These best practices are intended for people who develop custom page templates and content templates for use within OrchestraCMS.
- Templates should always have ‘Disable Superfluous Span Tags’ (in ‘Setup > Site: Detail’) checked and CSS designed as such.
- Leaving this option off can assist in certain edge cases when needing to style native Content Layouts, which is accomplished by being able to target the `<span>` elements.
- When modifying the underlying code of Visualforce pages used as page templates in OrchestraCMS, or Apex classes used for custom content templates, a site-wide cache refresh should be initiated for any sites using that code.
- OrchestraCMS is not dynamically connected to the underlying Salesforce code. Any modifications to the code might not automatically be in effect on the live site. The impact of modifying the underlying code depends on the caching settings of the page templates and content templates. To have OrchestraCMS update the cache files, an OrchestraCMS Administrator can refresh the caches from within each site in OrchestraCMS Setup by clicking on the Cache | Page or Cache | Content options and choosing Refresh Caches. In the case of Content, both the Level 1 and Level 2 caches should be refreshed.
- When developing page templates for OrchestraCMS, the content of the page is static. For dynamic content, Stantive recommends a class that implements the cms.ServiceInterface class referenced in the OrchestraCMS Developers Workbook.
- OrchestraCMS supplies a REST API which allows a developer to reference a custom Apex class that implements cms.ServiceInterface from within a custom content template or javascript. Requests are sent as an Ajax request which returns a JSON string. A script can then process the returned JSON.
- This would be used in place of Javascript remoting.
- Wherever possible use code that can be cached in a static state.
- OrchestraCMS pre-renders content and page code and stores the static pre-rendering which is then served up when a page is requested by a site visitor.
- This behaviour is controlled by
- Page Caching Enabled on the page template properties in OrchestraCMS
- isPageCacheable and isContentCacheable on the Content Layout record in Salesforce
- All three of the above settings should be enabled for best performance. This will only work if the code can be statically captured and stored in a pre-rendering.
- When developing page and content templates for OrchestraCMS, consider two key features: reusability and editability.
- Pages throughout your site should share as much generic structure as possible so that you can minimize the number of page templates that need to be created.
- Custom content templates should expose any messages or features that may need to be changed by users. The goal is to limit the number of changes your design/development team might be called upon to make and empower the editors and authors to make as many of the modifications to the content as possible. For example, if a developer hard codes a paragraph of text into a custom content, OrchestraCMS users will not be able to modify that paragraph of text.
- When developing Visualforce page templates for use with OrchestraCMS, the approach should be that you are creating a reusable template. Avoid building the page template as a Visualforce page for use within Salesforce, and keep in mind it is intended to provide a template for building pages in OrchestraCMS.
- Items that are specific to a particular website page should be coded as custom content instead of being included in the Visualforce page template. This will allow the template to be reused throughout multiple pages on the website.
- Encapsulating code into custom content allows that code to be reused over multiple pages in your site and centrally managed.
- When coding rendering URLs for images stored in the OrchestraCMS media library test for a site prefix. For example
- public static String getSiteURLForMedia (String ImageURL) {
if (String.isNotBlank(ImageURL)) {
String sitePrefix = Site.getPathPrefix();
if (sitePrefix != null && ImageURL.startsWith('/servlet')) {
ImageURL = sitePrefix + ImageURL;
}
} else {
ImageURL = '';
}
return ImageURL;
}
- When creating Visualforce pages and Apex classes in Salesforce for use with OrchestraCMS, adopt a naming convention that will tie the code together.
- SiteName_TemplateDescription
- CreditUnion_HomeTemplate
- CreditUnion_SearchResultsTemplate
- CreditUnion_Level1LandingTemplate
- Assign the panels in your Visualforce page templates unique names within the template but reuse those names across multiple templates for panels that serve the same function.
- Name a footer panel "footer"
- Name a left nav panel "leftNav"
- Name a header panel "header"
- This allows content to remain in the appropriate panel when switching page templates.
- Keep live site and edit mode styling and scripting separate.
- Since cms:panel tag are encased in the save div tags used to target items in live site code it is best to ensure that commands that would affect these div tags in the live site be kept in different css or js files then styling or scripting for the page editor in OrchestraCMS. A common example would be a scripting command that hides a div. In order to prevent it from hiding the panel in edit mode you could place the commands that hide the div in a script that is only loaded in edit mode.
- Use panelDynamic="true" in your Visualforce page templates to reduce the network traffic.
- Each piece of content placed in a panel in OrchetsraCMS may result in an Ajax request to retrieve that content if it cannot be included in the OrchestraCMS page cache. Using panelDynamic="true" in the definition of the panel will cause all content in that panel to be returned in one request instead of multiple requests.
- Group common scripts/headers/footers into their own Visualforce pages.
- Use <apex:include pageName="yourvisualforcepage" /> from the main template. Centralizing common code chunks in this manner will make it easier to manage changes.
- Note that Salesforce will wrap anything called in this fashion within <span></span>. This makes this method unsuitable for calling items that would go in the<head> section of the resulting markup.
- When calling custom versions of JQuery, use the .noConflict to avoid superseding the version of JQuery embedded with OrchestraCMS.
- As of OrchestraCMS Summer 2015, the embedded version of JQuery is 1.11.2. Prior to this the embedded version of JQuery was 1.5.1.
- If you use a version of JQuery other than those specified, OrchestraCMS may not function correctly. To avoid this you can use the .noConflict call with JQuery to call the custom JQuery library and avoid the issue.
- Use $.(document).ocmsDynamicLoadFinished in place of $.(document).ready when trying to affect items that are content.
- OrchestraCMS caching may include tokens representing content in the markup of a page in certain circumstances. The $.(document).ready will fire before these tokens have been replaced by the markup they represent resulting in your JQuery not affecting the target components.
- Using $.(document).ocmsDynamicLoadFinished instead will cause the encased function not to run until after the tokens have been replaced in the page source with the markup being targeted.
- When code updates are made to the underlying code, refresh the OrchestraCMS caches.
- When updating apex classes or Visualforce pages representing content markup, you need to refresh both the L1 and L2 content caches in all OrchestraCMS sites that make use of that content template.
- When updating Visualforce pages representing OrchestraCMS page templates you need to refresh the page caches in all OrchestraCMS sites that make use of that page template.
- Do not place panels between <p> or <h1>, <h2>, etc. block elements, only within <div> or <table> elements. The generated content typically creates <div> blocks which Chrome filters out of <p> and <h*> elements. i.e., replace <p> or <h*> with <div> and make sure CSS has appropriate class designations.