Adding your own CSS or JavaScript assets to a Theme

Misty Flowers

February 26, 2019 19:09

Custom CSS and JavaScript files can be added to an existing Composer Theme to tailor visual style and behavior beyond Finalsite's defaults, including uploading your own stylesheet or script files via File Manager. This article covers what each controls, how to add custom files, and which files must never be edited directly.

💡Quick answers

What does CSS control vs what does JavaScript control? CSS controls visual design and layout (colors, fonts, spacing). JavaScript controls interaction and dynamic behavior (clicks, animations, plugins).
Adding a custom CSS file to a theme? Create a .css file (suggested name: client.css), upload it to File Manager, then in Themes click the green + next to CSS Assets, select the file, and click Update.
Is it OK to edit main.css or main.js directly? No. Finalsite-created Theme design assets get overwritten when their team makes updates, and edits may break the warranty. Always add separate custom .css or .js files instead.
Why use a unique element class name when adding custom CSS? To avoid impacting other parts of the site. Generic class names can cascade into elements you didn't intend to style.
Where are custom CSS files edited after upload? In File Manager. Click the pencil icon on the far right of the file to edit.

Themes in Composer are built using Cascading Style Sheets (CSS) and JavaScript (JS) files deployed by Finalsite. This article explains how to add your own custom files to an existing Theme to further tailor your site's appearance and behavior.

⚠️ Important Note

Any modification directly to the Theme design assets (main.css or main.js) may break the warranty. Fixing issues that occur due to modification of the Theme design assets may incur additional charges.

Understanding custom assets

CSS: Controlling design and layout

CSS files are used to control the design, format, and layout of a page or website.

Function: CSS files contain lists of rules (called "definitions") that instruct a user's browser how to display various page elements.
For example: If you want all the text on a specific element to be purple, you create CSS rules that tell the web browser to apply that style.

JavaScript: Enhancing interaction and behavior

JavaScript files are used to control the interaction and behavior of elements on a page or website.

Function: JavaScript files (sometimes called "plugins") are small, self-contained code sequences that a user's browser runs when a page loads to add dynamic functionality.

Add your own assets

Sometimes we work with clients who have the skills to be able to edit the CSS and Javascript of their website. If you have the desire and the chops to add your own styles, you can do that!

Here's how you can add your own assets using a CSS file example:

Create a blank file saved with a .css extension and add your code. A suggested name for the file is client.css, but you can name it anything relevant so we know it is your code and not Finalsite.
Upload this file to somewhere in File Manager where it will be easy for you to access.
Navigate to the Themes tab in Composer and click the green + icon next to CSS Assets (or JavaScript Assets if adding this piece).
Locate and add your file from the File Manager popup.
After your file is added, click Update so the Theme is published with your CSS file.
To make edits to your CSS file, go to File Manager and click the pencil icon on the far right side.

You are responsible for troubleshooting any code that you create in the client.css file.

Do	Don't
Create unique element classes to avoid negatively impacting other sections of the site.	Add code to any existing `main.css`, `main.js`, or school-specific Theme files created by Finalsite. These files get overwritten when Finalsite staff make repository updates; once that code is gone, it cannot be retrieved.
Give files a name that cannot be confused with Theme code (recommended: `client.css`).	Make live edits to a main site page, such as the home page. Clone the page first and add a temporary page class to avoid live errors.
Review articles on CSS specificity to avoid adding `!important` whenever possible.	Make too many major changes. Finalsite cannot provide support for custom code, so keeping modifications minimal is strongly recommended.

🛠️ Troubleshoot: Changes still not showing up?

Caching may prevent you from seeing updates right away. After saving your file, try the following:

In Composer, navigate to the Themes tab and click Update to republish the theme.
Then do a hard refresh in your browser using one of these shortcuts:
- Mac (Chrome, Firefox, IE): Command + Shift + R
- Mac (Safari): Option + Command + R
- Windows: Ctrl + F5
On mobile, clear your browser cache or open the page in a private/incognito window.