Theming in NationBuilder is fully featured and easy to learn. You can customize any element of the user facing website and have access to all the objects and variables that make NationBuilder so powerful. NationBuilder extends HTML with the Liquid template language, and extends CSS with SASS. All that means is you can use regular HTML and CSS, but you also get some cool plugins, variables, and logic in both. Have you noticed how easy it is to change the color scheme of the Revolution theme? That all happens with SASS and a couple of color variables.
Using one of our official themes is the quickest way to get your nation online and looking great.
To create your own custom theme, sign in to your control panel and click Pages > Theme > New custom theme.
The Template page displays all the theme level page and autoresponse templates you can edit. If you have modified a template, it will say "Yes" under the custom column. To upload images, SCSS, javascript or other files click on Files and then Upload. Reference these files in your HTML and SCSS without any path and use the filename theme.scss for your SCSS file, like so:
Learn more about the appropriate way to reference images and other files in NationBuilder.
Your new theme won't be published to your website until you're ready. As you build your theme, you can view all the changes you make within the theme editor by clicking Save as draft, then clicking on the Preview button. Use the drop downs at the top of the preview pane to choose which theme and page you want to view.
Clicking Publish Theme won't actually publish changes to your website until you select your theme. You select your theme from the Pages, Theme page. You shouldn't select your theme until it's finished and ready to go live.
To create a thumbnail for your theme, take a screenshot and resize it to 222x139. Name it theme.png and upload it to the Files page.
Learn the important distinction between theme and page level editing.
Upload images and files to Pages > Theme > Files if you are going to reference them in a theme level template (meaning all templates listed under Pages > Theme). Upload images and files to the Files page of a particular page if you are going to reference them on a page level template or the wysiwyg editor within the Content area of a page.
You should only ever reference images, stylesheets, and javascript files using just the file name, not the full URL.
This applies everywhere:
- Images in SCSS or CSS files
- Images in img tags:
- Images in CSS tags:
- Images in inline CSS attributes:
- SCSS or CSS files linked in the header:
- Javascript files linked in the header:
Never link to an absolute URL (ie. http://d3n8a8pro7vhmx.cloudfront.net/.../myimage.jpg) , as they are likely to stop working eventually.
The only exception is if you are referencing an image or file within a <script> tag. In that case, upload the file to Pages > Theme > Files and use the following code:
NationBuilder uses the open source liquid template language to access objects and variables. There are two basic types of markup in liquid:
{{ two curly brackets }}
Tags are surrounded by
{% a curly bracket and a percent %}
Output blocks are replaced with the data they reference, such as printing the name of a supporter:
Tags drive the logic of templates. They are responsible for loops and branching logic such as If / Else.
Example of output blocks and tags in use:
Mixins:
Mixins are one of the most powerful Sass features. They allow re-use of styles – properties or even selectors – without having to copy and paste them or move them into a non-semantic class.
For example, let's say you want rounder corners on a background element. Instead of typing out the border-radius property for all the different browsers, you can just use the border-radius mixin like so:
Of course there's much more SASS can do, so view more SASS tutorials or check out the reference docs before getting started.The main stylesheet for each theme is a SCSS file called theme.scss. When you create a new custom theme, you will start with the theme.scss from the official Basic theme. To make it a bit easier to structure your styles, all the default page templates adhere to a common ID structure, which is reasonably self explanatory if you know HTML/CSS.
As a reference, the official themes use a width of 960px. The left column is 660px and the right column is usually 240px. Generally there is 15px of padding on both sides of both columns, but this can vary a bit from theme to theme. You can also disable the sidebar on any page so it uses full width.
You may want a particular page (such as your homepage) to include content from another page, such as your latest 3 blog posts. To do this, click Pages > Theme > New File and name the file _blog_latest.html, and click Create and edit file. Next, copy the following contents into the file and click Save and Publish.
The code above was pulled from the blog template, and will display the latest 3 posts, and truncate each post to 50 characters each. Adjust or restyle this as you desire.
Note: To display content from other page types, copy and paste the for statement from the template of that page type into the new file instead of the code above.
Next, click Pages and then Edit next to the page where you wish to display the posts. Then click Template, and paste the following where you want the posts to display:
This is using the page with the slug blog and the partial template _blog_latest.html. You can apply this technique with other pages as well. Just adjust the partial template and {% subpage %} tag to match what you wish to display.
While clicking on page tag will display all pages with that tag, you may want to include pages with the same tag on another page. Doing this is very similar to the method listed above.
For example, let's say you wanted to include all blog posts with the tag "California" on a basic page. To do this, click Pages > Theme > New File and name the file something like _ca_posts.html, and click Create and edit file. Next, copy the following contents into the file and click Save and Publish.
This will display the latest 5 blog posts. Adjust as you desire.
Next, click Pages and then Edit next to the page where you wish to display the posts tagged California. Then click Template, and paste the following where you want the posts to display:
This will use the ca_posts.html file we first created and populate it with all the blog posts tagged California.
Note: Always use lower case letters for the tag in the code above. If your tag is more than one word, use an underscore instead of a space.
