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.

Configuring custom styling and scripting in Brightspot

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:

Click menu > Admin > Sites & Settings > Sites > Global. The Edit Global widget appears.
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.

Delivering custom coding and styling through classes

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")));
    }
}

Security and development considerations for custom styling and scripting

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