Live editing

You can easily update the layout and colors of the registration, pricing and payment pages online directly on the live. Click on Theme in the dashboard sidebar, click Enable edition toolbar (see picture), then browse to a page you want to edit and use the tools. Watch a video »

Uploading a theme package

For more involved design and/or to fit your deployment process, You can upload a zip file that contains the theme templates through an API call:

curl -i -u *api_key*:  -X POST -F file=@*package*.zip https://*mydomain*/api/themes/

When you are modifying root templates, like base.html for example, you may inadvertently break the dashboard and become unable to access the theme page to upload a fix. You can always remove all custom templates and reset to the default theme but you will need an API key in order to trigger the reset (remember most or all functionality might not be accessible through a Web Browser after a broken theme was uploaded).

It thus recommended you obtain an API key before starting to deploy custom themes. To reset to the default theme, call the DELETE end point. For example:

curl -i -u *api_key*:  -X DELETE https://*mydomain*/api/themes/

Zip-Package structure

You must use the following structure in the zip file to override the default theme. All files are optional. The default template will be used for a missing file.

  • *package*/
    • templates/
      All files under the templates directory are HTML or email layout templates. Some file names are reserved and will interact with the reverse-proxy logic (ex: login.html, register.html, pricing.html) otherwise all other HTML files will be served as static HTML pages.
    • public/ (optional)
      All files in the public directory are static assets (i.e. Plain Old Data) to be served to the browser client. These includes stylesheets (.css), javascripts (.js), fonts, images and other media.
Example (cowork.zip):

cowork-v1.0/
    templates/
        index.html
        accounts/
            login.html
    public/
        favicon.ico
        static/
            base.css
          

Making text editable online

Editing HTML files and uploading them can be cumbersome. It is a process is also not suitable for other people in your business, with little or no technical knowledge.

We will want to make some text on the home page (index.html) editable online for example. In order to do that we add an .editable class and a unique id to a paragraph.

-<p>Hello World</p>
+<p id="title" class="editable">Hello World</p>

Reminder:

  • all editable elements must contain an editable class.
  • all editable elements must have an UNIQUE id attribute.
  • To enable Markdown edition on an element, add a edit-markdown class.
  • To transform <IMG> and <VIDEO> nodes into placeholders, add a droppable-image class.

Public static assets

Public static assets (images, js, css) are all files which are downloaded by the client as-is. For best performance, they are best cached and served by a Content Delivery Network (CDN) such as Fastly or Cloudflare.

Depending on how you have organized your development and deployment workflow, the reference files for public assets (images, js, css) can either be served from your app container, or installed as part of the theme package (package.zip). The only technical difference between putting the assets in the container vs. the zip is how the asset cache is filled.


The default theme

To get started in most cases, you will want to download the default theme, make your modifications and upload the changes.

Templates for the default theme are written in HTML5 and styled with Bootstrap4.

The following sections describe how the default theme was designed and where to find various elements.

(If you are looking to build a theme from scratch check out the bottom-up page design tutorial.)

The wireframe

The default theme is designed with mobile-first in mind because many boutique SaaS owner work out their support requests on-the-go, out of a large screen phone. As a result the wireframe is built to accomodate phone screens, then handle desktop screens with little changes to the look-and-feel.

The classic dashboard is defined in base.html. All other templates extend from base.html. The dashboard is split into 6 areas:

  • logo: A image that serves to quickly identify the company or product, doubled with a hot link to expand/collapse the sidebar.
  • menubar: Sign-in or authenticated user, doubled with primary links (ex: Pricing, Documentation) on a desktop.
  • content area: Content specific to the page
  • footer: copyright notice and secondary links on desktop
  • sidebar footer: copyright notice and secondary links on mobile
  • sidebar: links to pages for profiles, billing, subscriptions, etc. It also contains the primary links (Pricing, Documentation) on mobile.

On mobile the sidebar collapses. Mobile pages also tend to increase vertical scrolling. As a result the button to expand the sidebar out should stick to the viewport in order to be available when needed. The default theme chooses to stick the menubar on mobile and put the expand button in the top left corner. This has the benefit to also keep the menubar for the authenticated user on screen.

An Alaternative is to keep the right edge of sidebar always visible on screen so it can be pulled out when necessary. The sliding visual effect when the sidebar expand is nicer. It also works better in cases where the sidebar can vary in width based on a user intent.

Since the right edge is always visible, it does though shrink vertical space for the content, space that is in tight supply on a mobile screen.

HTML5 defines a Document Object Model (DOM) as a tree of nodes with parent and children. The sidebar being expandable and sticky to the viewport, we decide to put the 3 elements logo, sidebar and sidebar footer as siblings into a .dashboard-nav parent and the 3 elements menubar, content area and footer as siblings into a .dashboard-content parent. Both .dashboard-nav and .dashboard-content are at the same level, laid out side-by-side by using various css features.

<div class="dashboard-container">
  <div class="dashboard-nav">
    <header>
    </header>
    <div class="dashboard-nav-menu">
    </div>
    <div class="dashboard-nav-footer">
    </div>
  </div>
  <div class="dashboard-content">
    <header>
    </header>
    <div class="content-area-container">
    </div>
    <footer class="footer">
    </footer>
  </div>
</div>

Pages built out of the wireframe

It is a lot simpler to manage various dynamic elements (ex: form error messages) and enforce a consistent style when all pages are derived from the same wireframe. Thus this is what the default does for the two categories of pages

  • Workflow pages

    Pages that are typically associated with a specific workflow, such as registration or checkout for example.

  • Dashboard pages

    Pages for a subscriber to update their profile, credit card on file, view billing history, unsubscribe and other administrative features expected by a user of a Software-as-Service product.


Workflow pages

The workflow pages include all the classic pages you can expect to find browsing the website of a Software-as-Service product as a visitor, or onboarding as a user. Following is diagram of the accounts & billing workflows on djaodjin:

accounts/activate.html

Landing page for links sent in an activation e-mail.

accounts/disabled.html

This page is presented to visitors when login and/or registration have been disabled for the site.

accounts/login.html

The classic username (or email) and password login page.

Related APIs
Related notifications
accounts/logout.html

Landing page after a user signs out.

accounts/recover.html

Page typically linked from a "Forgot password?" link to recover a user account through an e-mail address.

Related APIs
Related notifications
accounts/register.html

A versatile user registration page.

For example, see tutorial on how to use this page to implement frictionless onboarding.

accounts/reset.html

Landing page for the link sent in an recover password e-mail.

Related notifications
contact.html

A "Contact Us" form. Managers of the site will receive an e-mail with the content of the contact form.

Related notifications
saas/billing/balance.html

Presents the user with a payment page for past due balances. This page is very similar to the Cart page.

Related APIs
saas/billing/cart.html

Presents the user with a checkout page to pay for subscription plans selected in the pricing page.

saas/billing/receipt.html

Presents the user with a receipt for a successful charge on a credit card.

saas/legal/index.html

List of legal documents (ex: terms of service, security policy)

saas/legal/agreement.html

Shows a single agreement (or policy) document. The content of the agreement is read from saas/agreements/slug.md.

saas/legal/sign.html

Asks the user to sign the agreement presented in order to continue with using the product.

saas/pricing.html

Pricing page with subscription plans for the service.

Related APIs
saas/profile/new.html

Presents the user with a form used to create a new profile.

User and Organization are separate models linked together through a Role. By default, the request user becomes a profile manager of the newly created profile (also called Organization model).

The complete User, Organization and role might be exposed right away to the person registering to the site. This is very usual in Enterprise software.

On the hand, a site might decide to keep the complexity hidden by enforcing a one-to-one manager relationship between a User (login) and an Organization (payment profile).

Related APIs
saas/redeem.html

Redeem a discount code. After the code is submitted, the pricing page is displayed with prices reflecting the discount.

Related APIs

Dashboard pages

Pages for subscriber to update their profile, billing and subscriptions.

Pages for providers to support subscribers and assess the performance of the business.

Pages for brokers to modify the theme and update access control rules.

saas/profile/index.html

Page to update name, e-mail and street address of an account.

Related APIs
saas/billing/card.html

Page to manage the credit card on file associated with the profile.

Related APIs
saas/billing/index.html

Page with list of historic orders and payments, as well as the current balance due and a link to edit the credit card on file. The same functionality is also available through the

saas/profile/subscriptions.html

Page to show active and expired subscriptions for an account. On this page a user can also unsubscribe.

Related APIs
saas/profile/roles/role.html

Page with all users having the specified role on the organization account. Through this page, already registered users or not yet registered users can be granted a role on the account. The newly added user will be notified by an e-mail that it was granted a role on the account.

Related APIs
Related notifications
saas/users/roles.html

This page is the dual of the account role page. Instead of listing the users with a specified role on an account, it lists all the accounts the specified user has a role on.

Related APIs
Related notifications
users/notifications.html

Enable or disable specific notifications sent by the site (ex: user registered, charge receipt).

Related APIs
users/password.html

Page to update a user password.

Related APIs
billing/receipt.html

Receipt for a successful charge by the payment processor. This page is used in both in the workflow and dashboard. As the last step of a payment workflow, before moving to the application business logic, the dashboard sidebar is showing on a receipt page, such that a user has the opportunity to understand where the receipts can be found later on in the interface.

saas/metrics/dashboard.html

High-level dashboard for a quick glance of the business in real-time. Entry point to search for a account.

Related APIs
saas/billing/bank.html

Page to connect a processor to handle charges (ex: Stripe).

saas/billing/coupons.html

Page for a provider to manage the discount codes available at checkout. The same functionality is also available through the API:

Related APIs
saas/billing/import.html

Page for a provider to upload a payment that was made offline.

Related APIs
saas/billing/transfers.html

List payments made to a provider or funds transfered to the provider bank.

Page to with list of historic orders and payments made to the provider. This page also contains a link to connect the processor (see Bank page). balance due and a link to edit the credit card on file. The same functionality is also available through the

saas/metrics/coupons.html

Presents details about the use of a discount code.

Related APIs
saas/profile/plans/index.html

Page to manage a provider's plans.

Related APIs
saas/profile/plans/plan.html

Page used by a provider to manage a single plan.

Related APIs
saas/metrics/plans.html

Presents the performance of subscription plans for a time period (as a count of subscribers per plan per month).

Related APIs
saas/profile/subscribers.html

List active and churned subscribers on any plans of a provider.

saas/metrics/revenue.html

Reports cash flow and revenue in currency units from subscriptions over a trailing 12-month period.

notification/detail.html

This page presents the user with the tools to live edit a notification e-mail template.

Related APIs
pages/theme.html

This page presents the user with the functionality to download and upload a theme, reset to the default theme, turn on the live edition tools for web pages and live edit the notification templates.

Related APIs

Notification templates

These are e-mail templates sent to users as part of various workflows.

notification/card_updated.eml

Template for e-mail sent to a customer when the credit card on file has been updated.

notification/charge_receipt.eml

Template for e-mail sent to a customer when a charge was successfully created on the credit card. This template is also used to notify customers of refunds.

notification/claim_code_generated.eml

Template for e-mail sent to notify a user that a third-party has paid for their subscription on the site as part of GroupBuy checkout workflow.

notification/expires_soon.eml

Template for e-mail sent to notify a customer that their subscription on the site is about to expire.

notification/order_executed.eml

Template for e-mail sent to a customer when an order has been recorded but payment is still due.

notification/organization_updated.eml

Template for e-mail sent to a customer when fields in her profile have been updated.

notification/password_reset.eml

Template for e-mail sent to a user in response to a recover forgotten password event. The template contains a back link to the website where the user will be prompted for a new password.

notification/role_grant_accepted.eml

Template for e-mail sent to profile managers in response to a user accepting a role on the profile. This e-mails are only sent for roles requiring a double opt-in.

notification/role_grant_created.eml

Template for e-mail sent to a user who was granted a role to a profile.

notification/role_request_created.eml

Template for e-mail sent to profile managers that a user requested a role on the profile.

notification/subscription_grant_accepted.eml

Template for e-mail sent to profile managers in response to a subscription that was previously granted being accepted. This e-mails are only sent for subscriptions requiring a double opt-in.

notification/subscription_grant_created.eml

Template for e-mail sent to a subscribers who were granted a subscription.

notification/subscription_request_accepted.eml

Template for e-mail sent to subscribers when a provider has accepted their request for a subscription. This e-mails are only generated when a subscription plan is setup for double opt-in.

notification/user_activated.eml

Template for e-mail sent to profile managers of a broker when a user has activated their account.

notification/user_contact.eml

Template for e-mail sent to profile managers of a broker when a user has submitted a contact form through the /contact/ URL.

notification/user_registered.eml

Template for e-mail sent to profile managers of a broker when a user has registered an account.

notification/user_welcome.eml

Template for e-mail sent to a user after they register their account.

notification/verification.eml

Template for e-mail sent to a user as part of the account activation flow to verify their e-mail address.


Partial templates

This template files are building blocks that are meant to be included in other templates through an include directive. Example:

{% include "_generic_navbar.html" %}
_generic_navbar.html

Menu items for the menubar at the top of the page.

_navbarbrand.html

Logo in the top left corner of a page.

_menubar.html

Pop-up menu that is displayed when a user clicks on their username in the top menu bar.

This partial is also used to fill the HTML element with class="header-menubar" on the pages served by the app container.

saas/_sidebar.html

Menu items in the sidebar of the dashboard pages.

saas/agreements/terms-of-use.md

Text of the terms of use for the site.


Error pages

These templates are used when various errors are inevitable generated by the site.

400.html

Page displayed when a generic HTTP error code 400 is generated.

403.html

Page displayed when a permission denied, aka HTTP 403, is generated.

404.html

Page displayed when a URL can not be found, aka HTTP 404.

500.html

Page displayed when an internal server error, aka HTTP 500, is generated.

Because 500 errors indicates something with the internal logic of the site went horribly wrong, it is important that this template is a self contained plain HTML file, otherwise it might result in cascaded errors and the page will not show up as expected.

rules/forward_error.html

Page displayed when the application behind djaoapp cannot be reached.