Embedding a list of Discourse Topics in another site

announcements
1

If you grab the latest builds of Discourse you’ll get a the ability to embed topic lists in other sites via some simple Javascript and HTML.

The typical use case for this is a blog or other content driven site, where you want a widget on the side of the screen that lists topics. You can filter by category, tag, or any of the other public filter options available.

How to Embed a list of Topics

First, you must enable the embed topics list site setting.

Then, in your HTML add a <script> tag that includes the javascript necessary to embed the Discourse topics. You can add this wherever you normally add scripts. For example:

<script src="http://URL/javascripts/embed-topics.js"></script>

Replace URL with the forum address, including the subfolder if it exists.

After that, in the <body> of your HTML document, add a d-topics-list tag to indicate the list of topics you’d like to embed. You’ll need to replace URL with your base URL here too:

<d-topics-list discourse-url="URL" category="1234" per-page="5"></d-topics-list>

Any attributes you provide (besides discourse-url which is required) will be converted into the query parameters for the topic search. So if you wanted to search topics by tag you could do this:

<d-topics-list discourse-url="URL" tags="cool"></d-topics-list>

If a query parameter has underscores, convert it to dashes. In the above example, you probably noticed thatper_page became per-page.

In SameSite contexts (i.e. the embedding site and your forum share a parent domain), Discourse will know if you’re logged into the forum, and will display the results accordingly. Don’t be surprised if you see secure categories and such when logged in - anonymous users will not be able to!

List of parameters

template: Either complete or basic (default). While basic is just a list of topic titles, the complete complete brings title, user name, user avatar, created at date, and topic thumbnail.

per-page: Number. Controls how many topics to return.

category: Number. Restrict topics to a single category. Pass the id of the target category

allow-create: Boolean. If enabled the embed will have a “New Topic” button.

tags: String. Restrict topics to ones associated with this tag.

top_period: One of all, yearly, quarterly, monthly, weekly, daily. If enabled will return the “Top” topics of the period.

Examples

I’ve created an example site here:

https://embed.eviltrout.com

You should be able to view source in your browser to see the code, but also the entire source is on github:

This is a brand new feature so any feedback / requests would be appreciated.

Styling the list

You can use our existing theme feature to add custom styles for the embed list.

For example, by default our embed list using the complete template looks like this:

image
image573×536 65.9 KB

If you want it to look like, for example, a grid, you can add custom SCSS to Theme > Common > Embedded CSS:

.topics-list {
  display: grid;
  grid-template-columns: repeat(2, 1fr);
  
  .topic-list-item { 
    .main-link {
      border: 1px dotted gray;
      padding: 0;
    }
  
    .topic-column-wrapper {
      flex-direction: column-reverse;
      
      .topic-column.details-column {
        width: 100%;
      }
        
      .topic-column.featured-image-column .topic-featured-image img {
        max-width: initial;
        max-height: initial;
        width: 100%;
      }
    }
  }
}

Which will make it look like this:

image

94 Likes