Theme Extensions

Requirements: 

• This feature assumes that you are a Thinkific Partner with access to the Partner Portal already. See Becoming An App Partner
• This feature is behind a feature flag. It is only accessible to partner accounts that we have turned it on for. Contact us at apps@thinkific.com to request access.

In this article

• Creating your first Theme Extensions
• Customer Experience
• Common Issues
• Other Notes and Considerations

Creating your first Theme Extensions

Theme Extensions can be registered in a Thinkific App and become accessible to Course Creators in Site Builder Sites when the app is installed.

Currently, Theme Extensions include the ability to make new Theme Sections available to customers. We will look at further additions to this in the future.

To build your first Theme Extension, you will need to do two things:

1. Create an App in your Partner Portal
2. Build a zip file that includes the necessary Theme extension files

If you are building your first Theme Extension you can also check out our free course for new app developers!

Building a Theme Extension Zip File

A Theme Extension Zip File contains all of the relevant code for installing custom sections into a Site Builder Site.

We recommend that you build your custom sections in the Theme Editor of a Site Builder Theme for testing purposes before installing it in a working app.

In order for a zip file to successfully be uploaded to an App, it must be created from the root of the project folder and contain a specific file structure.

Zip File Structure

Here is a Demo Zip File that you can use as a starting point.

Every Zip File must contain the following files

Notes:

• The section files must be uniquely named.
• The section files must have a valid {% schema %}. Please refer to the schema section in one of the section files as an example

Folder Structure

|- readme.md
|- manifest.json
|- sections/
|  |- section-name-1.liquid
|  |- section-name-2.liquid

Detailed Section Descriptions

When a Course Creator configures your section to their Site Builder, they will see a description above the settings. You can customize this description to include links, images, or video.

Example:

{% schema %}
{
  "label":"Astronauts",
  "description":"This is an astronauts app! <br/> For more details, visit our <a href='example.com'>website</a>. <br/> <br/> <img src='https://cdn.britannica.com/35/210535-050-60B90533/Roberta-Bodnar-Canadian-astronaut.jpg' width='200px' /> <br/> <br/> <iframe width='320' height='180' src='https://www.youtube.com/embed/CAxlduB68T4' frameborder='0' allow='accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture' allowfullscreen></iframe>",
  "previewImageUrl":"https://cdn.thinkific.com/57/20210222/bd6ff9e981480e3e5327fd4ee1b2e9ff.png",
  "previewDescription":"This section is only for Astronauts",
  "settings":[]
}
{% endschema%}

App and Extension Versioning

For security reasons, updates to the liquid files for existing sections are only permitted if the section has not yet been installed on a Thinkific Site. If you re-upload a section with the same name but different content you will receive a warning and the existing section will not be changed. This also applies to removing sections. If you have new functionality, or changes to a section, you can always create a new section with a different name.

Note: this only applies if your app has active installs on a customer site and does not apply if it is still in development and only installed on sandbox sites. In these cases changes will be applied and reflected on your sandbox site immediately.

If the recommended method of creating a new section does not work for you, you may request a temporary exemption to update and/or remove your app's sections. To submit a request, please reach out to us at apps@thinkific.com with your app details and the time frame you will need to be exempt. Your request will be reviewed, and if approved you will be able to make changes as needed.

Do you have more complex requirements when it comes to versioning sections? Let us know at apps@thinkific.com.

Customer Experience

Once your app has been installed on a Thinkific Site, the sections that you have defined become immediately available when selecting a new section to add to a page in Site Builder.

These sections can be found at the bottom of the Section Page Picker in a group with the name of your App.

Common Issues

Uploading a zip fails

• Verify that your sections contain a valid schema. A basic schema should look like this:

  {% schema %}
    {
      "label":"My Section",
      "description":"",
      "previewImageUrl":"",
      "previewDescription":"",
      "settings":[]
    }
  {% endschema %}

Uploading a zip succeeds but sections are not visible in Site Builder

• Verify that your zip contains a sections folder and that it contains at least one .liquid file
• Verify that your zip was created from the root project folder, rather than from compressing all the contents of the zip folder.

Other Notes and Considerations

1. This is an MVP.
2. It's a good idea to test sections on a sandbox site first.
3. No malicious code in Liquid templates (infinite loops, redirects, etc).
4. For now, all sections are available on all pages.
5. When a Thinkific Site changes its theme, its app sections are removed/overwritten (just like regular sections).