How it works

Layouts and pages are javascript files that must export an async function that returns a string of HTML.

A minimal page looks like this, stored in the app/pages folder:

module.exports = async function($){
  $.page.title = 'Hello world'
  return /* html */`
    <h1>Hello World!</h1>

This function returns an HTML string in backticks. These are Javascript template literals. They are a new feature of Javascript ES6 which is what we use to create HTML.

Of course you don't have to use backticks, any string will do, but it is convenient when you want to return HTML. Adding the /* html /* comment in front of the backtick will let your editor know it's HTML and add syntax highlighting.

When you start your app with waveorb serve, or if you're using the nodemon script with npm run serve, everything in the app folder will be loaded into the app object.

The orb object

The page function receives a single object, the orb object $, which contains all of your built in properties and functions:

Anything you add to the orb object $ will be available later. For example, the $.page.title will be available in your layout. Later we will show how it is also used with filters, actions and plugins.

Return values

Middleware, filters and server action functions can all return data. If they return an object, string or false, execution is halted. If they don't return anything or undefined, execution continues.

async function($) {
  // Return object
  return { status: 'OK' }

  // Return a string
  return 'OK'

  // Returns empty string
  return false

  // Continue execution if more to do (default)
  return undefined

  // Throw error to return error message
  throw Error('must be an admin')

  // or return an error like this
  return { error: { message: 'must be admin', name: 'authError' } }

The server will return a 200 SUCCESS status code no matter what happens.

Error messages

Code errors and exceptions will also return a 200, but the response will contain an object with the property error set:

// Error message
{ error: { message: 'Some error', name: 'Error', stack: 'line1...' } }

The only time you will get something else than a 200 is when a page is not found, then you will get a 404 status code and response.