Creative Commons Licence
Creative Commons Licence

onCourse documentation copyright ish group. Licensed under CC BY 4.0. You are free to, share and adapt this documentation for any purpose, as long as you give appropriate credit.

I: Design overview

1. Customising onCourse Websites

Your onCourse Website is designed to be extremely flexible, allowing you to implement almost any concept you create for your site. When you engage your graphic designer to work on your brand and website, you will want to make your onCourse website reflect your organisation at every level. That means not only skinning the site to reflect your colour and logo, but thinking about navigation, search and the overall user experience (UX). onCourse has been built with this in mind.

At the same time, we want to save you time and money by giving you many of the basic building blocks you need to create your site.

If you are after quick simple results, skip straight to Stylesheets and focus on changing just the stylesheets to get the look you are after. A lot can be done with little effort in this way. If you want to make changes to the structure of the site itself, read onto HTML Templates for an understanding on how to change the html which makes up the site.

If you are not a web designer and reading this manual, you may find many of the concepts quite technical. Don’t worry: you can still edit content using the online CMS without understanding anything here. Your designer, or ish, will be able to work on the page design and create something into which you can drop your content.

1.1. Editing your site via WebDAV

While you can log into your CMS to edit content, to make more granular changes to the code or design of your website you’ll need to use WebDAV. This is very similar to FTP (File Transfer Protocol) except it makes it easier for us to encrypt your connection and apply special automatic rules and filters.

To access and log into WebDAV we recommend using any standard compliant application, like Cyberduck, which is free for use on Windows and Mac. To configure a connection in Cyberduck, first click the Bookmarks tab, then in the bottom left of that screen, click the '+' button to add a new bookmarked connection.

cyberduck bookmarks
Figure 1. The Bookmarks screen in Cyberduck

A screen like below will appear:

cyberduck configuration
Figure 2. Cyberduck Configuration

Enter the following details:

  • Server = the URL of your website

  • Username = the username you use to access your site’s CMS

  • Path (located under the expandable menu More Options) = /editor/webdav.

Close the box. If you’ve entered everything correctly, your connection will now appear in the bookmarked like. Double-click your new bookmarked connection and you’ll be asked to enter your password, which will be the same as the one you use to access the CMS. Once you have access you’ll see your site’s folder structure.

1.2. Draft site

All onCourse websites have both draft site and a live website. The draft site will be visible to you only when you are logged into the Editor. If your site is http://www.acme.edu.au, then you can log into the Editor at https://www.acme.edu.au/#editor. Any changes you make in the Editor or through WebDAV are only visible to you and any other users logged into the Editor. You can make content changes and experiment in any way you choose without disturbing your live website.

Once you have finished with your changes to the draft site and are ready to publish them to the live site you can do this within the Editor. The "publish" button can be found on the left hand side of the Editor panel. Any changes made within either WebDAV or the Editor will be deployed to the live site when you press the publish button. You’ll need to wait a few minutes before the content is visible on your production site due to caching in our cluster of servers. Some users may need to wait even longer if they have a local proxy server, which keeps a copy of the old site until it expires from its cache.

Publishing your site
Figure 3. How to publish your site

1.3. Special URLs

Some URLs in your site are reserved for special pages. These pages are delivered by the onCourse software itself. To customise them, consult the templates chapter for details of how these pages are created. You cannot edit the content of the pages within the Editor because you will use the onCourse software to edit the courses, classes and other information which drives them. These pages include:

/courses

A list of all courses which are marked as web visible.

/courses/arts

A list of all courses tagged with the tag "arts" from the "subject" tag group.

/course/ABC

The detail of the course with code ABC.

/class/ABC-123

The detail of the class with code ABC-123

/sites

A list of all sites marked as web visible.

/site/12

The detail of site with internal id 12.

/tutor/23

The detail of the tutor with internal id 23.

/page/1

Every page you make in the Editor will be given an automatic page number reference. Even if you don’t give it a nicer path, it will always be accessible by this URL.

/enrol

All pages under this path are reserved for the enrolment, application and sales processing pages.

/cms

All pages under this path are reserved for the cms engine.

/editor/webdav

All pages under this path are reserved for webdav access.

1.4. Creating pages

Pages which are not 'special' are delivered from the Editor. That is, you are able to create pages and assign them to any URL you choose. Each page belongs to a website. You can have more than one website for the same onCourse database. Each page can also be given a theme which defines which blocks appear on the page. Themes are then linked to layouts which defines the html and stylesheets used. The following graph shows the relationship between the onCourse database, websites, pages, themes and layouts.

The database

Starting from the top of the diagram we have the onCourse database itself. This is the application which contains courses, classes, tags, students, tutors, and so on. The data in the onCourse database is entered completely within the onCourse client/server applications and is automatically synchronised with the website.

The website

Each onCourse database can drive one or many websites. Each website will have one or more domains which are used to access them. So Acme Training might have the general leisure learning site at http://www.acme.edu.au and the corporate training at http://corporate.acme.edu.au and also http://www.acme-corporate.com. The leisure and corporate sites can have completely different content (pages), different graphic design (layouts) and even display different sets of courses.

The pages

The website is made up of pages entered through the Editor. For full details on how to write and build web pages, consult the onCourse website and Editor handbook. Each page has content (text, pictures, etc) and will be linked to a theme.

The theme

Themes are a way of grouping pages and giving them their own character, and are applied per URL path.

You can place blocks on a theme, so you might create a theme for policies, another theme for news, and one for general pages. The policy theme could then include a block on the right side with information for students about lodging complaints and contacting the principal. The news theme might contain a block down the left with a random 'hot' course and a block across the top with a rotating banner ad. Finally, the general theme contains a block on one side with navigation elements and assorted other blocks of special offers.

The layout

The final piece of this structure is the layout. This is where you as a designer will weave your magic. The layout is represented by a folder in the layouts folder you access in WebDAV. You can place templates inside that folder where each template overrides a certain piece of html on the page. In this way you have full control over the entire layout and design of the site, right down to every line of html sent to the browser.

There is always a layout called 'default' which is used by the system for the special pages outlined above. You can create as many layouts you like and link them to themes you create in the Editor.

1.5. WebDAV files

When you login into WebDAV you will see folders like this:

  • pages

  • blocks

  • templates

    • default

  • s

    • stylesheets

    • fonts

    • img

    • js

In addition you will see a redirects.txt file that will contain a full list of the redirects on your website.WebDAV folders The s folder contains static files which are not parsed by the application server. These include css, fonts, images and javascript. Keeping things organised within the folders as provided will make everything easier, but you are free to create whatever additional folders you need to here. Template overrides live inside the templates folder. One layout is provided for you called default which you cannot delete.

You can edit pages and blocks directly from within WebDAV. The result is the same as if you had edited those same items from within the CMS.

1.6. Editing redirects in WebDAV

Any 301 redirects added to your site can be seen in plaintext format in the redirects.txt file, located in your sites root directory. These redirects are structured with a From URL on the left, a To URL on the right, and a space seperating them.

301 redirects can be added in the Editor or typed directly into this file.

The redirects.txt file accepts 301 redirects that conform to the following structure:

  • "From" URLs must point from a page on your site. All "From" URLs must start with a forward slash "/"

    Example: / /courses /contact/about-us /courses/business/business?tag=/business/accounting

  • "To" URLs can point to another page on your site or an external webpage. "To" URLs can start with a forward slash "/" (for internal redirects) , "http://", or "https://" (for external redirects).

    Example: / /checkout ** https://www.ish.com.au/

  • Each 301 redirect must be on a new line.

  • The "From" and "To" URLs in a redirect must be seperated by a space. "From" and "To" URLs must be on the same line.

    Examples of valid redirects: /contact/about-us xml /contact /course/ABC123 /courses/ ** /courses?near=2000 https://www.externalsite.com.au

If an invalid redirect is entered into the redirects.txt file, the file will not be able to be saved.

1.7. Video

Although it is possible to load small video files directly into the static folder, the onCourse servers are not optimised for serving video. You will get much better results by hosting your video at a site such as YouTube or Vimeo and linking to them from within your pages. Their engineers have optimised their networks for serving video to many different types of devices.

1.8. Favicon

Some websites show a tiny icon in the URL bar and in bookmarks. This is called a favicon.

To add a favicon to your onCourse website, you need an image in both '.ico' and '.png' format. The standard is to have the .ico images in either 16x16 or 32x32 size, and the .png up to 180x180.

Both of these images should to be uploaded via WebDAV to the directory '/s/images' with the names 'favicon.ico' and 'apple-touch-icon-precomposed.png' (you can use any names for these images, but these are the convention).

Next, add the relevant html to the PageHead.tml file, found in the '/templates/' directory in WebDAV.

<link href="/s/images/favicon.ico" rel="icon" type="image/vnd.microsoft.icon"/>
<link href="/s/images/favicon.ico" rel="shortcut icon" type="images/x-icon"/>
<link rel="apple-touch-icon-precomposed" href="/s/images/apple-touch-icon-precomposed.png"/>

1.9. Robots.txt

onCourse automatically generates a robots.txt file, with a pointer to the sitmap.xml which is also automatically generated.

If you have specific pages on your website you’d like to stop search engines from crawling, you can manually add a robots.txt file to the folder /templates/default/. You can then add 'disallow' commands using the following syntax:

Disallow: /room/200
Disallow: /course/abc123/

Don’t forget to add the link to sitemap.xml as well if you override this asset.

It is not necessary to hide class pages, or any page which you have otherwise hidden (such as a site you no longer use). onCourse will automatically remove them from the sitemap.xml or add noindex meta headers as needed.

1.10. Checkout

In order to help with styling the Checkout portion of the website, you need to first have a course added to the cart and add a student (move past the Add a Student page). Once these are done, you can appaend the following the checkout URL in order to see the Thank You/Confirmation page usually shown at the end of a transaction

?previewMode=true

If done correctly, the Thank You page should show, allowing you to style it without having to put through a transaction.

II: Stylesheets

One of the first ways you’ll want to modify the look of your site is by changing css stylesheets. onCourse comes with a set of default stylesheets to make your life easier, so you will probably start with a copy of our template-a, template-b or template-c. These in turn build on our base stylesheets which we update once a year or so.

Because you are building on existing stylesheets, lots of things are already taken care of for you. Your html/css developer can save weeks of work with our existing responsive layouts, grid and basic styling.

2. File structure

First let’s see where all the files are. To make it easier to navigate, all the CSS is broken up into lots of files within a set of folders.

Start inside the '/s/stylesheets' folder in WebDAV. You’ll see two folders: 'css' and 'src'. It is important that you do not edit the files in 'css' directly, but instead only edit the files in 'src'.

/s/stylesheets/src/

Start by looking at the file site.scss. That’s the top of the stylesheet structure and it includes all the other files you need. Look for lines like this:

@import "application/settings";

We recommend you create a new file with your customisations and add a reference to that from site.scss. Don’t remove the import of the 'base' stylesheets. That import brings in the core stylesheet definitions which are required for your onCourse site: shortlists, course and class listings, enrolment templates and much more. Override them however you want, but they will save you a lot of work rather than starting from scratch.

3. SCSS

If you didn’t recognise the @import command above as CSS, that’s because onCourse uses a variation of CSS called SCSS (also known as SASS). This extends the basic stylesheet concepts and adds some very useful abilities:nested rules, variables, mixins, selector inheritance

Every time you edit any file in /s/stylesheets/src/, the destination /s/stylesheets/css/site.css is automatically regenerated by libsass. This takes less than a second, so you can see the results almost immediately. Remember that to see changes in the staging site you must be logged into the CMS in your web browser. You should not edit the site.css file directly, as any changes you make will be overwritten.

If you don’t want to bother with learning SCSS that’s fine. Just write ordinary CSS in the site.scss file. As your stylesheets become more complex, you will find that SCSS gives you valuable shortcuts to achieving what you want and you will never want to go back.

If you would like to break up your stylesheets into more manageable pieces, add another import statement under the 'base' import like this:

@import "colours";

Then create a file /s/stylesheets/src/_colours.scss (with the underscore). When you make changes to that file, onCourse will automatically merge any content from _colours.scss into the main css for your site.

Look through the default styles for variables which you can easily modify to change your site. For example, override $bodyFontFamily in order to change the font right through your site. Or change $primaryColor, $secondaryColor and $containerWidth.

3.1. Bourbon

By default your stylesheets include Bourbon. This css library gives you lots of useful functionality that you’d otherwise have to write by hand. Read up on this library and get instant rounded corners across all browsers, typography features, reset, and much much more. As just one simple example

section {
  @includelinear-gradient(totop,red,orange);
}

will give you the following output

section {
  background-color:red;
  background-image:-webkit-linear-gradient(bottom,red,orange);
  background-image:linear-gradient(totop,red,orange);
}

without having to remember to put Opera, webkit, Mozilla and html5 elements into your css. You don’t need to use bourbon, but it can help you keep your site consistent across browsers more easily and save you time with common css blocks.

Read the docs for Bourbon.

3.2. Compression

No matter how many separate files you break up your stylestyles into, the output will be compressed into one file and minified. This means whitespace is stripped and the file is pretty hard to read. However browsers will be able to parse it just fine; this minification can make a big improvement to page load speeds and also to your SEO.

Comments will be stripped out, so don’t hesitate to put lots of useful notes in your scss files.

Finally we compress the file with gzip to serve it across the internet as fast as possible. You’ll see these output files as:

/s/stylesheets/css/site.css
/s/stylesheets/css/site.css.gz

3.3. Map

Because it can be hard to review minified and combined CSS in your browser, we also output a map file. This allows your developer tools to identify the real file and line number in the source scss where your stylesheet rule can be found, saving you a lot of searching. The map can be seen as:

/s/stylesheets/css/site.css.map

Your browser or other dev tool will automatically find and use that file.

4. Responsive design

It is extremely important in a modern world filled with tablets and smart phones that your site is built to make life easy for those users. onCourse sites already are prepared with responsive designs at four sizes. That means that as the browser window gets smaller with different sized devices, the design itself alters to work better at that size. It is still up to you as a designer to properly take advantage of this responsive design, but the groundwork is already there for you in onCourse and the enrolment pages as well as skillsOnCourse are optimised already.

onCourse has media sizes of $small-screen, $tablet-screen and $desktop-screen throughout the base stylesheets.

III: Javascript

5. File structure

Log into webDAV and look at the folder /s/js/.

In there you’ll see a number of javascript files which drive your onCourse website. Some are third party vendor supplied files and others are default parts of onCourse itself. site.js is the starting point and it has a list of all the other files which are included. Note that the order of including files can sometimes be important. Let’s look at base.js now:

//= minify off
//= require base.js
//= require extra.js

This is telling you that minification is disabled and that the javascript files base.js and extra.js are included. This is a different syntax to SCSS so don’t get them confused. The combined output file is called all.js and the files which are merged don’t need to start with an underscore.

5.1. Minification

Unlike CSS, the javascript is not automatically minified. This is because sometimes javascript minification can actually break your javascript (particularly if it contains errors). Browsers will often manage to figure out your broken javascript, but once minified, errors really cause problems.

You can enable minification by changing the "off" to "on" and saving the file. Wait about 30 seconds and then review your site in staging before pushing it to live.

We use the Google Closure compiler to verify and minify the output.

5.2. Compression

all.js.gz is automatically created and used by browsers. This is another reason minification may not be quite so important: compression often does a pretty good job of reducing the file sizes.

6. Core libraries

We supply a number of third party javascript libraries with your site by default. The following list are bundled together as dynamic.js and cannot be removed without breaking some key shopping basket functionality on the site:

  • classnames

  • react

  • react-dom

  • react-redux

  • redux

  • redux-thunk

  • jquery 3.x

In addition there are some useful libraries which are often used when building sites:

  • BxSlider 4.x

  • jquery.customSelect

  • jQuery Validation Plugin

You may wish to remove or add more libraries for your particular design

7. config.js

config.js controls the location of the checkout pages on your site. You can relocate checkout to anywhere you’d like.

var checkout_config = {
  "checkoutPath": "/checkout"
}
checkoutPath

The path on which your checkout page lives. You can point this to any page on your site, as long as you create that page in the editor and add the correct markup for the checkout engine to be displayed.

<div data-cid="checkout" id="oncourse-checkout"/>

8. SEO

onCourse is pre-configured with a whole range of SEO features to make your life easier and get good search ranking with minimal effort.

8.1. Copywriting

Although we take care of many of the technical details, there is absolutely no substitute for writing good copy. If you write descriptive text which is both engaging to potential students and incorporate the search terms that people will search for, you are well on your way to a successful website. Put these descriptions into:

  • tags

  • courses

Tags should be at least a paragraph and course descriptions should be 1-2 pages of copy. The first sentence of the course description is particularly important since it is used for the short description on the search results. Try to incorporate:

  • aspirational goals. What will they gain from doing this course? Can they expect to advance their career? Will it be fun? Will they meet interesting people?

  • what they will learn. Describe the outcomes in detail. Will it be challenging or easy?

  • what should they bring? Do they need to prepare in any way?

Your goals are to:

  • Get them excited about the content.

  • Alleviate any concerns about difficultly. Give them enough information to feel confident about what will be expected of them.

  • Explain the value proposition. What will they gain in exchange for their time and money?

Don’t even think about SEO keywords until you can do all the above. There is no point in getting clicks unless you convert them into sales through engaging copy.

Next, log into Google Adwords (even it you aren’t going to spend money with Google ads). Find the keyword planner and use it to understand what search terms rank for your site. Now add those words and phrases to your copy, but not at the expense of keeping your copy clear and engaging to humans.

8.2. Google search console

Google search console (previously called Google Webmaster tools) is a useful resource for to you review aspects of your website. Here you are able to see your site in the way Google sees it, understand how markup affects Google’s schema parsing, and see which pages are indexed. Its also an important place to tell Google if you’ve changed domain names, ensuring your SEO isn’t left behind on your old site.

In order to log in, Google will give you an html file to upload to your site named something like google4ddabfacdb4f6795.html. Log into webDAV and put that file just inside the 's' folder, not inside any other folder. Publish your site for Google to be able to see this file.

8.3. Tag Manager

Every site we build is created with Google Tag Manager integrated. This service drives the injection of javascript, tracking pixels and html into your site in really neat ways.

In particular it allows:

  • Adding livechat systems to your site

  • Facebook, Google and other tracking code

  • A/B testing (show some elements to some people and not others)

  • Different content for different country regions

  • Inject advertising panels

  • Javascript is asynchronously loaded (so it doesn’t slow the page draw)

  • Versioned changes (so you can roll back easily)

  • Event tracking (such as add to shopping basket)

When we build your site, we’ll give you access to Google Tag Manager, set up some initial Analytics tags for you, and get you started. You can then build more tracking or hand over access to your SEO consultants. We will continue to need access to tag manager so that we can debug problems and update core code as needed.

8.4. Google analytics

If you want to see how your site is performing, this is the tool for you. Typical analytics shows you page view, user demographics and much more, but onCourse injects even more data into your analytics:

  • Transactional sales dollars. Every sale through the website puts the dollar value into your Analytics. So not only can you see how many page views you got from that ad campaign, you can see the dollar value of the sales that generated. You’ll discover that the two aren’t always correlated. Do you care about ten thousand views from Facebook likes or the 200 real sales from a targeted campaign? This is how you can tell the difference.

  • Course and products. Drill down in your data to see where sales are coming from. Getting lots of language course sales from an ad you placed on a friendly site? Great, now you know what works and where to focus your time and money.

  • Events. Because we log "add to shopping basket" and other events, you’ll be able to see who is engaging with your site but not following through to the end.

  • Checkout steps. You can track each step in the checkout process through a Google Analytics acquisition funnel. See where and why people are dropping off.

Google Analytics Setup

In order to get data into your Google Analytics account you’ll need to complete the following steps:

  1. Create a new Google Analytics account (or use an existing one). Under Admin > Property > Tracking code look for the tracking id and make a note of it.

  2. Log into Google TagManager and find ish onCourse Google Analytics settings under variables. Put your tracking id in there to replace the dummy one.

  3. Back in Google Analytics, you should soon be able to the Tracking Code status update to show data coming in. Visit your website to generate a bit of traffic.

  4. Enable enhanced ecommerce reporting in the Google Analytics under Admin > View > E-commerce settings

  5. Select names for your checkout steps

    1. Empty Cart

    2. Add Contact

    3. Edit Contact

    4. Summary

    5. Payment

  6. Submit changes

google analytics settings

When you have some time, explore the Analytics "goals" setup for ways to get useful information such as dropoff in your checkout rates.

Events

Events are sent to Google Analytics at various points in the checkout process. Along with the event, onCourse sends a rich data structure which you can then report on. The following steps are sent as events:

  • Checkout step: 1 - checkout without any items in cart

  • Checkout step: 2 - Add payer screen

  • Checkout step: 3 - Edit contact screen

  • Checkout step: 4 - Summary screen

  • Checkout step: 4 option: Change Parent - change parent for child from summary

  • Checkout step: 4 option: Add concession - add concession for contact

  • Checkout step: 4 option: Add contact - add contact from summary

  • Checkout step: 5 - Payment screen

  • Checkout step: 4 option: Add a company - Add a company from payment screen

  • Checkout step: 4 option: Add a payer - Add a payer from payment screen

  • Checkout step: 4 option: Payment Page (Credit Card) - Payment Page Credit Card tab;

  • Checkout step: 4 option: Payment Page (Corporate Pass); - Payment Page Corporate Pass tab;

Add or remove items from shopping cart:

dataLayer.push({
    'event': 'addToCart' | 'removeFromCart',
    'ecommerce': {
      'currencyCode': 'AUD',
      'add': {
        'products': [{
          'name': {{item_name}},
          'id': {{item_id}},
          'price': {{item_price}},
          'category': 'Course Class' | 'Product',
'quantity': 1,
        }],
      },
    },
  });

Set Checkout Page:

dataLayer.push({
    'event': 'checkout',
    'ecommerce': {
      'checkout': {
        'actionField': {
          'step': {{ 1 | 2 | 3 | 4 | 5 }},
          'option': "Init Checkout Process" | "Add Payer" | "Edit Contact Details" | "Summary Page" | "Payment Page"
        },
        'products': [{
         'name':{{item.name}},
         'id': {{item.id}},
         'price': {{item.price}},
         'category': 'Course Class' | 'Product',
         'quantity': 1,
        }],
      },
    },
  });

Set Checkout Page Option (something like sub page/phase):

At the moment we have options only for 4,5 steps

dataLayer.push({
  'event': 'checkoutOption',
  'ecommerce': {
    'checkout_option': {
      'actionField': {
        'step': {{ 4 | 5 }},
        'option': "Change Parent" | "Add concession" | "Add contact" | "Add a company" | "Add a payer" | "Payment Page (Corporate Pass)" | "Payment Page (Credit Card)"
      },
    },
  },
});

purchase:

dataLayer.push({
    'event': 'purchase',
    'ecommerce': {
      'purchase': {
        'actionField': {
          'id': {{ data.id }},
          'affiliation': 'credit card' | 'corporate pass',
          'revenue': {{ amount.total }}, // includes tax
        },
        'products': [{
         'name':{{ item.name }},
         'id': {{ item.id }},
         'price': {{ item.price }},
         'category': 'Course Class' | 'Product',
         'quantity': 1,
        }],
      },
    },
  });

When you’re done setting up within Google Analytics, head over to the [websiteSetup-analytics] section to connect your analytics with your onCourse instance. You won’t see any data from onCourse until this last step is complete.

8.5. Sitemap

We generate a /sitemap.xml file automatically which you can add to Google’s webmaster tools. This allows Google to quickly find all the pages on your site without crawling through them one at a time, and it also gives Google hints about when those pages are updated so that they are crawled more quickly.

onCourse will let Google know that this sitemap exists using a special entry in the robots.txt which is also generated.

8.6. HTML markup

The html markup of your site is customisable throughout, but by default you get some robust templates that Google will love.

Semantic HTML

By building the html of your onCourse site with a clear structure and meaning, search engines such as Google are able to make sense of the structure and meaning. onCourse comes with good html that gives you a good starting point. For example, each page should only have a single h1 element, sections, footer and other modern html elements.

Accessibility

Although this is not strictly an SEO benefit, adhering to accessibility standards means that students with disabilities such as poor sight will be able to access your website more easily. This goes hand in hand with good semantic HTML and also means that Google and other search engines will properly index your site and understand the content structure rather than just index a mass of words.

Schema.org

Schema.org is a set of markup rules endorsed by Google and other search engines. It specifies ways to annotate the html to give it specific meaning allowing Google to create rich search results. For example, we can markup data so that Google can provide navigation structure, course dates, prices and other information right in their search results.image::images/schema-results.png[]

8.7. Navigation

The navigation and structure of the site’s page are important to good search results.

Some pages in your onCourse site don’t last very long. In particular, the class pages with a URL like /class/ABC-123 will be irrelevant as soon as that class is finished. You don’t want to accumulate page rank on these pages, only for that to evaporate. onCourse automatically adds a canonical link to the correct course page, transferring any page rank and inbound links to somewhere it will do good.

Canonical links are generated for all pages:

For pages created using the editor, the canonical link is the page URL set as default

For pages of Course and Class canonical link = https://website.com/course/course_code

For pages of Product canonical link = https://website.com/product/product_skuCode

For pages of Site and Room canonical link = https://website.com/site/site_Id

For pages of Tutor canonical link = https://website.com/tutor/Id

For Web static pages like canonical link = https://website.com/page_url

The canonical link will also follow the rules described above if you use redirects. Example: Page: Memberships (URL = https://website.com/memberships) Redirect: page/tutors → page/memberships Canonical Link = https://website.com/memberships (because we render Page membership)

URLs

onCourse has clean URLs which are easy for users and contribute to your SEO. All course detail and list pages contain the word "course" and you are free to create long course codes which contain useful SEO keywords. And your tag structure can be structured however you want.. For example, a URL like "/courses/business/communication" picks up several important keywords.

Redirects

If you ever change URLs it is vital that you don’t lose page rank on those old pages. While you don’t need to worry about classes, tags and course pages can accumulate valuable scores and you should implement redirects to the closest new page.

8.8. Meta headers

onCourse does not implement meta-keyword headers since it is well documented that no search engines use them for indexing. However we do implement:

  • og:image for course and class detail pages. The image is pulled from the first attachment of the appropriate type (jpg/png) linked to the course.

  • og:type is hardcoded to "website" to satisfy Facebook.

  • og:description and meta-description. The contents of this field is automatically populated from the beginning of the text in the course description or page content. Special formatting is stripped out (eg. headers and images). For this reason, it is useful for you to ensure the first paragraph of text is relevant and well written.

  • Page title (and og:title) is constructed using the name of your college and other details such as the name of the course or tag, or the name of the page.

These tags are useful for both Facebook, Bing and Google, helping you display better search results from data discovered by each of their crawl engines.

Should you wish to customise the behaviour of how onCourse inserts meta headers you can do this in PageHead.tml. You can customise the page title in Title.tml

8.9. SSL/TLS encryption

Google has indicated that sites with end-to-end encryption will get higher search rankings since they are more likely to be ligitimate sites which care about the privacy of their users. All onCourse sites redirect immediately to HTTPS for even the non-payment gateway parts of the site.

8.10. Page speed

A lot of effort goes into making onCourse really fast, even when displaying faceted search results from thousands of courses. We use separate SSL/TLS load balancers to remove encryption load from the application servers, we cache database requests and page rendering, and use Apache Solr as a high speed search cache. We also offload large image serving to a third party AWS S3 storage, again increasing the speed with which your site displays.

The end result of all this is that search engines give your site bonus points for being fast. Which is good.

IV: HTML Templates

9. Editing templates

Once you have exhausted the capabilities of styling your site purely through modifying css, you may want to customise the html which is generated by the web application. To do this, you will edit the templates which are used to build the site. You can do this using any WebDAV editor, like Cyberduck.

If you want to override the templates below, simply place your modified files into an appropriate layout. For example to customise the body structure on the default template, create a file here:

/templates/default/BodyStructure.tml

You can override any of the templates below, but don’t go overboard: if you can achieve the results through modifying the css, do that first since it will be easier to upgrade your site to take advantage of new features as they become available in onCourse. If you do make a mistake and need to revert to the default source file, you can find them in the /templates/_system folder. These cannot be edited, but can be copied back into the /templates/default folder.

In onCourse templates are well-formed XML documents. That means that every open tag must have a matching close tag, every attribute must be quoted, and so forth. You can override any of the templates in this handbook by simply creating a file with the appropriate name in the /templates/default folder. Naturally if you are using more than one layout, you can have multiple sets of templates, each in their own folder within /templates.

templateStructure
Figure 4. The hierarchy of the templates is quite complex

10. Page wrappers

All pages on the site are wrapped in one of two main templates. Most pages will have PageStructure.tml wrapped around them to render menus, headers, blocks, etc. Other web requests might be drawn inside a 'lightbox' effect and so should not have all this extra content.

10.1. Page Structure

Page structure is one of the few templates that is not editable. You cannot override this particular template since it controls how the CMS integrates to the site. But you have enough other hooks that you should not need to worry about this template.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:t="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd"
xmlns:p="tapestry:parameter" lang="en">
<head>
  <head t:type="ui/pagehead" title="${title}"/>
</head>

<body t:type="any" class="prop:agentAwareBodyClass" id="prop:bodyId">
  <div  t:type="ui/BodyStructure" webNodeType="webNodeType">
    <t:body/>
  </div>
  <span t:type="ui/googleAnalytics"></span>
</body>
</html>

10.2. Body Structure

Filename

BodyStructure.tml

The important thing about the body structure is that it is called by other page templates. So when Courses.tml wants to render itself, PageStructure is used to provide the main structure of the page. When you reach <t:body/> in the template below, Courses.tml is inserted.

10.3. Dialog Structure

Filename

DialogStructure.tml

This is a more minimalist page layout which is used for things that display in a 'lightbox' style dialog within the page. It contains no javascript references, but does include the main site.css stylesheet.

11. Page templates

Some of the templates you can edit are reached by a particular URL. For example, the /course/ABC renders CourseDetails.tml. All of these top level page templates begin with something like this:

<html t:type="ui/pagestructure" title="Page title" bodyId="literal:DetailsPage">

This will render the template, wrapped with the PageStructure.tml template (to draw the main page design and layout), and give you the opportunity to override the page title and body css id.

11.1. Courses

Filename

Courses.tml

URL

/courses/[tag]/[tag]/*

URL

/courses?s=[search terms]

Renders the course list after a user performs a search or browses the subject tags. The parameters in the URL define the position in the subject tag tree the user is looking at, or the search parameters they used. The first form of URL showing the list for a particular subject tag is deliberately designed to be Google friendly and encourage bookmarking.

11.2. Course Details

Filename

CourseDetails.tml

URL

/course/[course code]

Renders a single course description page.

11.3. Class Details

Filename

CourseClassDetails.tml

URL

/class/[class code]

Renders a single class description page. For technical reasons a class is called "CourseClass" within the internals of onCourse.

11.4. Tutor Details

Filename

TutorDetails.tml

URL

not public (ajax only)

Renders a tutor profile in a lightbox.

11.5. Sites

Filename

Sites.tml

URL

/sites

When called, renders a listing of Course sites (venues) and appropriate maps.

11.6. Site Details

Filename

SiteDetails.tml

URL

/site/[id]

Displays the details of the site including the map and site information.

11.7. Page Not Found

Filename

PageNotFound.tml

URL

undefined

Renders a page when the URL cannot be found.

11.8. Promo Codes Page

Filename

PromoCodesPage.tml

URL

not public (ajax only)

Allows the user to enter a promotional code within a lightbox.

11.9. Room Details

Filename

RoomDetails.tml

URL

/room/[id]

Displays details about the room, including the site details.

11.10. Add Discount

Filename

AddDiscount.tml

URL

not public (ajax only)

Allows the user to enter a promotional code within a lightbox.

11.11. Sitemap XML

Filename

SitemapXML.tml

URL

/sitemap.xml

Google, Bing, Yahoo and other search engines love this.

12. Component templates

These templates can never be called directly from a URL. Instead they are used by other templates to build up a page.

12.1. Block Display

Filename

BlockDisplay.tml

Builds the parameters to include content - copy, images, components

Filename

BodyFooter.tml

Builds the parameters for the Copyright, Disclaimer info, etc at the foot of the page

12.3. Body Header

Filename

BodyHeader.tml

Builds the Header area for the mast - logo, navigation, search, etc at the top of the page.

12.4. Class Item

Filename

CourseClassItem.tml

Produces the brief, panelled class descriptions.

classPanel
Figure 5. Snapshot display of Course Class and Class Times

You can add some extra detail to show the number of places left in a class by adding the following piece of code to this template.

<t:if test="isInStock">
     <link itemprop="availability" href="http://schema.org/InStock"/>
     <p:else>
           <link itemprop="availability" href="http://schema.org/OutOfStock"/>
     </p:else>
</t:if>

When added correctly you should see the following text below your Enrol Now buttons

places available
Figure 6. Snapshot display of Course Class and Class Times

12.5. Course Class Places Available

Filename

CourseClassPlacesAvailable.tml

Produces a Class enrolment status display. Called by "CourseClassItem".

12.6. Course Class Price

Filename

CourseClassPrice.tml

Produces a class pricing display. Called by "CourseClassItem".

12.7. Course item

Filename

CourseItem.tml

Produces a brief introduction to a Course Class

Called by "Courses" and "CourseDetails"

getImages(courseItemModel.course) retrieves all images related to this course and have 'image/jpeg' mimeType

<t:loop source="getImages(courseItemModel.course)" value="attachment">
    <div t:type="ui/image" name="attachment.name"/>
</t:loop>

12.8. Course Search Form

Filename

CourseSearchForm.tml

Produces a Course Class specific search

Called by "BodyHeader" and in turn calls "Search Inputs"

12.9. Class Grouping

Filename

GroupedCourseClassesList.tml

Renders list of classes grouped by site.

To display a list of classes grouped by site using following piece of the code in CourseItem.tml, you need to replace:

<t:loop source="courseItemModel.availableClasses" value="courseClass">
   <span t:type="ui/courseclassitem" courseClass="courseClass" linkToLocationsMap="linkToLocationsMap" isList="isList" allowByAplication="allowByAplication" feeOverride="feeOverride"/>
</t:loop>

with

<span t:type="ui/groupedCourseClassesList" courseClasses="courseItemModel.availableClasses"  linkToLocationsMap="linkToLocationsMap" isList="isList" allowByAplication="allowByAplication" feeOverride="feeOverride" />

Classes that have no site assigned will be displayed last in a group called "Venue TBA".

12.10. Course/CourseClass Tutors

Filename

TutorsDetails.tml

Renders list of all the tutors associated with particular course.

course class tutors details
Figure 7. course / course class tutors details

Display tutors in course detail using following piece of the code in CourseItem.tml

<span t:type="ui/tutorsDetails" course="courseItemModel.course"/>

Display tutors in course class detail using following piece of the code in CourseClassDetails.tml

<span t:type="ui/tutorsDetails" courseClass="courseClass"/>

12.11. Course Relations

Filename

CourseRelations.tml

Display the courses description under related courses using the following code in the CourseRelations.tml file

<t:container xmlns:t="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd" xmlns:p="tapestry:parameter">
    <div class="relatedCourses">
    <ul>
        <t:loop source="courseRelations" value="relatedCourse">
            <li><a href="/course/${relatedCourse.code}" rel="nofollow" target="_blank">${relatedCourse.name}</a></li>
                        ${convertCustomText(relatedCourse.detail)}
        </t:loop>
    </ul>
    </div>
</t:container>

12.12. Global Navi

Filename

GlobalNavi.tml

Defines the parameters for global menus

Called by "BodyStructure"

12.13. Google Analytics

Filename

GoogleAnalytics.tml

Places the appropriate Google Analytics code on the page

Called by "CourseClassItem" in "CourseClassDetails"

12.14. Google Map Sites

Filename

GoogleMapSites.tml

Produces a Google map of the predefined site/sites/venue

Called by "Courses" and "Sites" and in turn calls "GoogleDirections"

12.15. Google Directions

Filename

GoogleDirections.tml

Produces directions - written and verbal for site directions

Called by "GoogleMapSites" and "SiteDetailsComponent"

12.16. Hint Component

Filename

HintComponent.tml

Provides validation text (showing data entry errors) for forms throughout the application, but particularly within the enrolment process.

12.17. Menu

Filename

Menu.tml

Renders a Menu display. Called by "BodyStructure".

menuBase
Figure 8. Course Class

12.18. Menu Item

Filename

MenuItem.tml

Renders a specific menu. Called by "Menu"

12.19. Page Head

Filename

PageHead.tml

12.20. Payment Agreement

Filename

PaymentAgreement.tml

12.21. Promo Codes View

Filename

PromoCodesView.tml

12.22. Quick Search View

Filename

QuickSearchView.tml

Produces specific parameters for the display of the page masthead

Called by "PageStructure"

12.23. Room Location

Filename

RoomLocation.tml

12.24. Room Location Text

Filename

RoomLocationText.tml

Produces specific parameters for the display of the page masthead

Called by "PageStructure"

12.25. Search Criteria

Filename

SearchCriteria.tml

Produces specific parameters for the display of the page masthead

Called by "PageStructure"

srchOptions
Figure 9. Search Options

Produces specific parameters for the display of the page masthead

Called by "PageStructure"

12.26. Search Inputs

Filename

SearchInputs.tml

12.27. Search Terms Clarification

Filename

SearchTermsClarification.tml

12.28. Shortlist

Filename

ShortList.tml

Short List Manager

12.29. Site Details Component

Filename

SiteDetailsComponent.tml

12.30. Timeline Event Detail

Filename

TimelineEventDetail.tml

12.31. Timetable Events

Filename

TimetableEvents.tml

12.32. Social Media

Filename

SocialMedia.tml

Allows the user to order the preferred buttons for the Add This social media links which are placed against course and static pages.