Brightspot CMS Developer Guide

Adding custom styling and scripting


You can add custom styling and scripting to Brightspot the same way you do with standard HTML. You can link to external resources, such as .css and .js files. You can also embed styling and scripts into Brightspot’s HTML with <style> and <script> elements.

The techniques described in this section customize Brightspot itself. If you want to customize styling for the output that Brightspot produces, see Theme guide.


For temporary changes or quick tests, you can configure inline CSS and JavaScript that the server includes in <head> tags for rendering the Brightspot UI.

Warning
Using this method to configure CSS and JavaScript may introduce errors that prevent operation of Brightspot and even impede your ability to revert the changes. Use extreme caution when adding styling and scripting through Brightspot. For a safer way to add custom styling and scripting, see Delivering custom coding and styling through classes.

To configure inline CSS and JavaScript through Brightspot:

  1. Click menu > Admin > Sites & Settings > Sites > Global. The Edit Global widget appears.
  2. Under Debug, enter the styling in the Extra CSS field, and enter the script in the Extra Java Script field. Do not include the <style> and <script> tags; the server provides them.

This feature is limited to inline code—you cannot add a reference to an external stylesheet or JavaScript file.


You can provide custom styling and scripting to Brightspot by implementing the ToolPageHead interface. The method #writeHtml(ToolPageContext) writes HTML elements inside of the UI’s head tag on every page load.

The following snippet shows how to provide custom JavaScript to Brightspot using ToolPageHead.

import com.psddev.cms.tool.ToolPageContext;
import com.psddev.cms.tool.ToolPageHead;

import static com.psddev.dari.html.Nodes.*;

public class ToolPageHeadExample1 implements ToolPageHead {

    /* Include a default or no-argument constructor */

    @Override
    public void writeHtml(ToolPageContext page) throws IOException {
        page.write(SCRIPT
            .src("//cdnjs.cloudflare.com/ajax/libs/Snowstorm/20131208/snowstorm-min.js"));
    }
}

Your can place ToolPageHead classes anywhere in your project as long as it gets compiled into your project’s .jar or .war file. Brightspot uses ClassFinder to discover all classes implementing ToolPageHead, and uses reflection to instantiate them. As such, your class must either have the default constructor or explicitly define a no-argument constructor so that Brightspot can instantiate and invoke your class’s writeHtml method.

For instances in which you are writing a link to a CSS or JavaScript file that is hosted locally as part of your web application, it is best practice to wrap the URL to the resource in a call to Cdn#getUrl(HttpServletRequest, String). This call uploads the local resource to your application’s default storage (usually a CDN) and serves it from there, ensuring optimal download performance by the visitor’s browser.

The following snippet shows how to link a custom CSS file to Brightspot using ToolPageHead and Cdn#getUrl.

import com.psddev.cms.tool.ToolPageContext;
import com.psddev.cms.tool.ToolPageHead;
import com.psddev.dari.util.Cdn;

import static com.psddev.dari.html.Nodes.*;

public class ToolPageHeadExample2 implements ToolPageHead {

    @Override
    public void writeHtml(ToolPageContext page) throws IOException {
        page.write(LINK
            .rel(LinkRel.STYLESHEET)
            .href(Cdn.getUrl(page.getRequest(), "/path/to/local/webapp/styles.css")));
    }
}


The method ToolPageHead#writeHtml outputs custom styling and scripting to all Brightspot pages, including unauthenticated pages such as the login screen. If you are providing sensitive styling or scripts, implement additional logic to ensure an authenticated user is present before writing the elements.

import com.psddev.cms.tool.ToolPageContext;
import com.psddev.cms.tool.ToolPageHead;

public class ToolPageHeadExample3 implements ToolPageHead {

    @Override
    public void writeHtml(ToolPageContext page) throws IOException {
        if (page.getUser() != null) {
            /* Write sensitive data elements here... */
        }
    }
}

The method page.getUser() returns not-null if the user is authenticated. (You can use this logic to conditionally render any element in the Brightspot UI, thereby improving performance or satisfying other business requirements.)

Always test your changes locally before deploying them to a production environment. As an extra precaution, consider adding logic that consults a setting or “feature toggle” to determine if the elements should be written to the page, giving you the flexibility to disable the feature in case something goes wrong without requiring a new build and deployment to remove the code.

Previous Topic
Multi-site considerations
Next Topic
Sitemaps
Was this topic helpful?
Thanks for your feedback.
The elements that get you up and running in a matter of days, from pre-built content types, to modules, to landing pages.

Content types
Modules
Landing pages
Everything you need to manage and administer content within Brightspot CMS, including plug-and-play integrations.

Dashboards
Authoring content
Workflows
Admin configurations
A guide for installing, supporting and administering code on the Brightspot platform, including integrations requiring developer support to use.

Field types
Content modeling
Rich-text elements
Images