Introduction to themes
The Disqus Theme Editor provides a set of tools that allow you to personalize your website’s commenting experience with custom HTML, CSS, and JavaScript code. You can share your theme with other users, or even skip code entirely and use another user’s well-crafted theme. In this walkthrough, however, we’ll focus exclusively on the creation and editing of themes.
Enabling the theme editor
The theme editor is currently only available as an add-on purchase for your Disqus account. Once enabled, you can edit the themes for all of your websites using Disqus. To learn about or to purchase add-on packages, visit the Add-ons page on Disqus.
Note: If you’re a designer interested in creating a theme for our public theme library, please send an email to themes@disqus.com and we’ll provide you with free access to the editor.
Once enabled, you can access the editor by navigating to Settings > Appearance and then launching the theme editor.
Skill requirements
In order to continue, it’s expected you’ll have some knowledge of HTML and CSS. The theme editor is powered by our own in-house templating language, DTPL, so some experience with template or programming languages will be helpful. DTPL should look pretty familiar to you if you’ve created custom themes for Wordpress, Drupal, Tumblr, or similiar blogging and content management applications.
Navigating the theme editor
The theme editor is divided into two parts: a navigation pane on the left, and a text editor on the right. The navigation pane contains a list of blocks, which are reusable theme components that you can edit. To begin editing a block, simply click on it. The text editor on the right will be populated with the block contents, whereupon you can begin customizing it.
Above the text editor are three buttons, “Save”, “Preview”, and “Publish”. “Save” will save your current work for later, but won’t actually modify your live site. The “Preview” button generates an example thread carrying your customizations. When you’re happy with your changes, the “Publish” button both saves and publishes your customized theme, and will immediately affect your live website. Be careful! There is no undo button, so make sure you’re happy with your changes before hitting “Publish”.
Houdini, our reference theme
As you begin using the editor, you’ll notice that you already have some code to work with. This code belongs to Houdini, the default Disqus theme you’re already familiar with. We recommend following this code closely as it serves as an excellent reference point for your own customizations.
Note: If you’re unhappy with your changes, you can restore Houdini at any time by clicking the “Restore Defaults” button at the top of the editor.
Dynamic HTML with the Disqus Templating Language
Theme code is written using the Disqus Templating Language, or "DTPL" for short. DTPL looks and writes like any other templating language you may have used. In between ordinary HTML code, you’ll find special DTPL tags that allow you to build dynamic markup using a variety of data sources.
A DTPL template tag usually looks like this:
{ include comment }
In the example above, the template tag consists of an opening curly brace, a tag name (“include”), a value (“comment”), and a closing curly brace. The whitespace between the curly braces and the tag name are required; if you don’t leave this space, the template will not be interpreted correctly.
Lets go over some example DTPL tags.
Expressions
Expressions are the meat-and-potatoes of DTPL. They take a JavaScript expression, and output the result to the page.
{= <any valid JavaScript code> }
For example, you can use expressions to output variables to the page:
<p>The following comment is by: {= comment.username }</p>
You might be wondering, "Where did JavaScript come from?" DTPL actually compiles down to minified JavaScript, and is executed client-side on the browser.
We also have a theme editor variable list you can refer to while customizing your theme.
Conditionals
Conditional tags give you the ability to execute some code on the page only if the specified condition is true.
{ if condition }
...
{ elif another_condition }
...
{ else }
...
{ /if }
Here condition can be any valid JavaScript expression.
Loops
Loop tags allow you to repeat a piece of template code for every item in the given container.
{ for item in container }
...
{ /for }
Blocks
Blocks are reusable pieces of DTPL that can be re-used elsewhere in the code. Here’s an example:
{ block welcomeMessage }
<span>Hi, and welcome to my blog’s commenting section!</span>
{ /block }
On its own, this block doesn’t output anything. But we can include it using an include tag, whereupon it will be output to the page.
Includes
Include tags allow us to execute previously-declared blocks and output them to the page.
{ include welcomeMessage }
When this tag is interpreted, it will output the “welcomeMessage” block to the page. Giving us the following output:
<span>Hi, and welcome to my blog’s commenting section!<span>
Block argument variables
To reduce duplication, your blocks can also accept argument variables. Here’s how you can declare a local variable inside your block:
{ block welcomeMessage :name }
<span>Hi {= name}, and welcome to my blog’s commenting section!</span>
{ /block }
Now, to expand the block and pass it a variable, use the include tag. The following example passes a string literal for the argument variable “name”:
{ include welcomeMessage name:”Steve”}
You can even pass JavaScript variables as block arguments:
{ include welcomeMessage name:session.username }
Translatable strings
Many common string expressions in Disqus have translations available for different languages. If you plan to share your theme with other users, you should use our translatable string template tags where appropriate.
{ "This is a translatable string" }
Translatable strings are currently available only on default themes. Translatable strings for custom themes will be available in the future. In the meantime, you can also apply for our translation program to help us deliver Disqus in your language.
String substitution
You can use string substitution to output variables into translatable strings. For example:
{ "Jack has %(count)s apples.” count:apple_count }
Here “count” is a label, and "apple_count" is a variable containing the number of apples. If apple_count has the value “5”, then this code would output:
Jack has 5 apples.
Additionally, you can use string substitution with multiple variables:
{ “Jack has %(apple)s apples and %(orange)s oranges.” apple:apple_count orange:orange_count }
Presuming 5 apples and 3 oranges, this would output:
Jack has 5 apples and 3 oranges.
Comments
Comment tags are not interpreted, and are used as a means of documenting your code.
{* This code will be ignored *}
Spaceless
The spaceless tag is a tag that suppresses whitespace between HTML tags. For example, the following DTPL code:
{ spaceless }
<div>
<span> I don’t want this extra whitespace! </span>
</div>
{ /spaceless}
Would output:
<div><span>I don’t want this extra whitespace!</span></div>
The spaceless tag is useful for writing lines of code that must be output without whitespace for style reasons.