Building Your Zippy Courses Theme Part 5: Theme Requirements

What's Required in a Custom Theme?

When you're building a Zippy Courses theme, the template rendered will expect there to be specific files that it will be able to find.

If any of them are missing, you may see an error on your site, but only if the file itself is missing.

So what files do you need?

The Required Layouts

Here's the list:

├── /checkout
│   └── checkout.tmpl
├── /course
│   ├── /student
│   │   └── student.tmpl
│   └── /visitor
│       └── visitor.tmpl
├── /lesson
│   ├── lesson.tmpl
│   └── quiz.tmpl
├── /order
│   ├── orders.tmpl
│   └── order.tmpl
├── /page
|    ├── /affiliate
|    │   ├── application.tmpl
|    │   ├── dashboard.tmpl
|    │   └── preferences.tmpl
|    ├── /auth
|    │   ├── forgot-password.tmpl
|    │   ├── login.tmpl
|    │   ├── register.tmpl
|    │   └── reset-password.tmpl
|    ├── /course
|    │   ├── dashboard.tmpl
|    │   └── directory.tmpl
|    ├── /order
|    │   └── thank-you.tmpl
|    ├── /user
|    │   ├── email-preferences.tmpl
|    │   ├── password.tmpl
|    │   └── profile.tmpl
|    └── page.tmpl
└── /worksheet
    ├── submission.tmpl
    └── worksheets.tmpl

If you count them up, there are exactly 23 files that are necessary for your themes to work. As long as these files exist, in the exact folder structure used in the example above, your site is guaranteed to load, no matter which page a visitor is using.

Even better news is that you can use the Starter Theme, which will put all of those files in the right place for you automatically.

Let's walk through the purpose of each layout, one-by-one, and see when they'll be used:

  1. /layouts/checkout/checkout.tmpl: This layout will be used on your checkout page when someone goes to purchase one of your courses.
  2. /layouts/course/student/student.tmpl: This layout will be used when a student views your course.
  3. /layouts/course/visitor/visitor.tmpl: This layout will be used when a visitor or an unenrolled student attempts to view your course.
  4. /layouts/lesson/lesson.tmpl: This layout will be used when an enrolled student views a lesson within your course.
  5. /layouts/lesson/quiz.tmpl: This layout will be used when an enrolled student takes a quiz.
  6. /layouts/lesson/worksheet.tmpl: This layout will be used when an enrolled student fills out a worksheet.
  7. /layouts/order/orders.tmpl: This layout will be used when a student views a list of all of the orders they have made on your site.
  8. /layouts/order/order.tmpl: This layout will be used when a student views an individual order they have made on your site.
  9. /layouts/page/affiliate/application.tmpl: This layout will be used for accepting applications to become an affiliate.
  10. /layouts/page/affiliate/dashboard.tmpl: This layout will be used to display an affiliate's performance on a dashboard.
  11. /layouts/page/affiliate/preferences.tmpl: This layout will be used when an affiliate wants to update their preferences, such as a mailing address or payment preferences.
  12. /layouts/page/auth/forgot-password.tmpl: This layout will be used when a student has forgotten their password.
  13. /layouts/page/auth/login.tmpl: This layout will be used to allow students to login.
  14. /layouts/page/auth/register.tmpl: This layout will be used after a purchase has been made and a new student needs to register.
  15. /layouts/page/auth/reset-password.tmpl: This layout will be used after a user has received a password reset email, and they are following their one time link to reset their password.
  16. /layouts/page/course/dashboard.tmpl: This layout will be used when a student views a list of all of the courses they have purchased on your site.
  17. /layouts/page/course/directory.tmpl: This layout will be used when a user views all of the courses available on your site.
  18. /layouts/page/order/thank-you.tmpl: This layout will be used after a purchase has been made and directs people to register or login to claim their order.
  19. /layouts/page/user/email-preferences.tmpl: This layout will be used by students to update their email preferences and subscriptions on your site.
  20. /layouts/page/user/password.tmpl: This layout will be used by students to change their password while logged in.
  21. /layouts/page/user/profile.tmpl: This layout will be used by students to update their profile (name, email, and other basic details).
  22. /layouts/page/page.tmpl: This layout will be the basic page template and used in any cases where a more specialized template does not apply.
  23. /layouts/worksheet/submission.tmpl: This layout will be used to view a student's submitted worksheets.
  24. /layouts/worksheet/worksheets.tmpl: This layout will be used to view a table of the student's submitted worksheets.

Creating Additional Page Templates

Sometimes, you just want options. Maybe you create a page that deserves its own layout. How do you make that work with your theme?

The default page template is located at /layouts/page/page.tmpl.

Let's assume that you want to create a Super Awesome alternative. That would live at: /layouts/page/page--super-awesome.tmpl. Then, when you're editing your page, you can choose which template to use for that page and select the "Super Awesome" layout.

If you want to see an example of an alternate page template in action, check out the Landing Page template in our 1kStudents theme. This template creates a nice landing page for your site, similar to the one used on sites like Feel free to use that design as a reference for your own custom layout or get creative with your own ideas!

Using Components Within Layouts

When you're working with layouts, making changes can quickly become tedious if you have to make the same change in more than twenty different spots.

This is where components can rescue you!

Component files can be used to encapsulate elements of your site in a way that is easier to keep organized. Because this can be as simple or as complex as your needs require, we're going to show you something very basic to help communicate what's possible.

├── common
│   └── blocks
│       ├── audio.tmpl
│       ├── blocks.tmpl
│       ├── html.tmpl
│       ├── image.tmpl
│       ├── opt-in-modal.tmpl
│       └── video.tmpl
├── forms
│   ├── login.tmpl
│   ├── checkout.tmpl
│   └── ...
└── site
    ├── footer
    │   ├── footer.tmpl
    │   └── scripts.tmpl
    └── head
        ├── head.tmpl
        ├── open-graph.tmpl
        ├── scripts.tmpl
        └── styles.tmpl

In the example above, we have three folders in our components/ directory that will help us re-use common areas of our HTML: common/, forms/, and site/. Here's what each of them do:

  • common/: For elements such as blocks, which we know will be used in both lessons and pages (and maybe more locations in the future), we want something that is flexible and re-usable. To facilitate that, we have components for audio, video, html, image, and opt in blocks.
  • forms/: Forms can be complicated. In some cases, it's easier when you're building a page to move a form out of a layout and into its own component. This makes it easier to think about and problem solve with as you design, and if you ever need to re-use it, it's already a component!
  • site/: There are some elements that are present every time a url on your site is visited. Usually, these are things like Javascript files and Stylesheets or the head of your HTML documents that contains information like your <title></title> tags. Make them once and include them in every layout.

Now let's look at a template that uses these components:

<!DOCTYPE html>
{{> site.head }}
    <div class="card card--login w-360px">
        <header class="card-header">
	    <h3 class="card-title">{{ entity.title }}</h3>
       {{> common.blocks blocks=entity.blocks}}

        <div class="card-block">
            {{> forms.login }}

        <footer class="card-footer">
            <p class="text-muted text-center ma-0"><small><a href="{{ links.user.password.reset }}">Forgot your password?</a></small></p>

    {{> site.footer.scripts }}

If you read through our Guide to Handlebars and the guide to Using Data in Your Templates, everything above should look very similar. The magic of using components in our layouts is that they become very readable and very easy to understand.

Think about it - when you're creating a layout, you don't really care about all of the nitty-gritty details when you open up the layout file. You want to understand, at a higher level, what information is going to be included on the page.

When you read the example above, that's exactly what you can do: There's the standard opening HTML tag, followed by the site head tag (which is included). Farther down, we display all the content using {{> common.blocks }} (which are what our individual block type components were for earlier!), followed by the form and a password recovery link, and then we close it out by including the footer scripts component that belongs right before the closing </body> tag.

What's Next?

Ahhh, you're pretty smart! You know that once you know which layouts you need to create, it's important to make sure that you include the correct structure and information in your layouts, right?

Good thing that's what's coming up next. Dive into Advanced Forms and Core Components to get the 411 on other goodies that Zippy Courses provides for your custom themes.