How it works

In the browser, a minimal page looks like this, stored in app/pages/hello.js:

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

Access this page at /hello.js in your browser. The app/pages directory is your app's web root.

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 in development using npm run dev, 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:

• $.app - Your entire app as an object
• $.params - Parameters you sent from the client
• $.query - Query parameters from the URL
• $.files - Uploaded files as an array
• $.req - Request object, a NodeJS http.ServerResponse instance
• $.res - Response object, a NodeJS http.ClientRequest instance
• $.socket - Socket object from the ws project
• $.server - Underlying server instance
• $.tools - Built in tools you may need
• $.lang - The request language like en or no, two character ISO code.
• $.link - Link translation function
• $.t - Language translation function
• $.env - Environment variable substitution
• $.redirect - Redirect request

Anything you add to the orb object $, either during the request or with plugins, 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

On the server, middleware, filters and actions return data. If they return an object, string or false, execution is halted and the result is sent back to your page in the browser. If they don't return anything (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.