C class

Controller

Viking Controllers are core to determining what JavaScript is run for a URL. They are made up of one or more actions that are executed on a page load.

By default only the ApplicationController extends Controller. All other controllers extend ApplicationController. This gives you one class to configure things like ensuring a user has logged in.

When a URL is being dispatched the action being run is available at this.action_name.

class PropertiesController extends ApplicationController {
  index() {
    console.log(`You have reached the ${this.action_name} page`);
  }
}

Parameters

All request parameters, whether they come from the query string in the URL or extracted from URL path via the {@link Router} are available through the params object. For example an action that was performed at the URL path /posts?category=All&limit=5 will include {category: 'All', limit: 5} in params.

It's also possible to construct multi-dimensional parameter hashes by specifying keys using brackets, such as:

  • post[name]=david
  • post[address]=spain

The params in this case would include: {post: {name: 'david', address: 'spain'}}

Rendering / Displaying a View

To display and render a view as the primary View in the application you can display it with this.display.

this.display(PropertyView, {record: property});

Redirecting

Redirects are used to move from one action to another. For example redirecting to the login page if the user is not logged in.

this.redirectTo('/login');

Calling display or redirectTo multiple times

An action may only contain a single render or redirect. Attempting to try to do either again in the same action will result in a DoubleRenderError:

login() {
  this.redirectTo('/elsewhere');
  this.display(LoginView); // throws DoubleRenderError
}

If you need to redirect based on a condition either return after redirecting so that display doesn't get called or use an if/else statement.

Constructor

new Controller(application)
application : Application

An instance of an Application.

Instance Properties

P   _aroundActions
P   _responded
P   _skipAroundActions
P   action_name: string | null

The name of the action currently being processed, otherwise null;

P   aroundActions: Array.<AroundActionCallback>

aroundActions are functions or methods that are run around a controller action.

aroundActions are inherited. If you set a around action on ApplicationController it will be run on every controller that inherits from ApplicationController.

If a string is given the function on the controller will be called. If a function is given that function will be called. Both methods and functions will revieve a callback to execute to continue processing the action.

An around filter requiring a user to be logged in ```javascript class ApplicationController extends VikingController { static aroundActions = ['requireAccount'];

requireAccount(callback) { let session = await Session.current();

if (session) {
  callback();
} else {
  this.redirectTo('/login');
}

} }


If you want an aroundAction to only be called on certain actions you can
pass the `only` options:

```javascript
class ApplicationController extends VikingController {
  static aroundActions = [
    ['requireAccount', {only: ['protectedAction']}]
  ];
}

You may also pass the except option for every action except a certain action:

class ApplicationController extends VikingController {
  static aroundActions = [
    ['requireAccount', {except: ['publicPage']}]
  ];
}
P   bindedObjects: Object.<string, Object>

Object containing references to objects this instance is listening to

P   eventListeners: Object.<string, Array>

Object containing all event listeners

P   listenerId: string

Unique identifier for this event bus instance

P   params: Object

All request parameters, weather they come from the query string in the URL or extracted from URL path via the {@link Router}.

P   skipAroundActions: Array.<AroundActionCallback>

skipAroundActions allows extended controllers to skip defined aroundActions that were defined in the ApplicationController:

class LoginController extends ApplicationController {
  static skipAroundActions = [['requireAccount', {only: ['new']}]];
  // ...
}

class LoginController extends ApplicationController {
  static skipAroundActions = [['requireAccount', {except: ['show']}]];
  // ...
}

class PublicController extends ApplicationController {
  static skipAroundActions = ['requireAccount'];
  // ...
}

Instance Methods

F   addEventListener(name, callback, options) → EventBus

Bind an event to a callback function. Passing "*" will bind the callback to all events fired.

If the options.once is true, the event will only be triggered a single time. After the first time the callback is invoked, its listener will be removed. If multiple events are passed in as an array, the handler will fire once for each event, not once for a combination of all events.

Parameters

name : string | Array.<string> | object

Event name(s) or object of event/callback pairs

callback : function | object

Callback function or options object if name is an object

options : object optional

Event options

once : boolean optional

Whether the event should only trigger once

context : object optional

The context to bind the event to

listener : object optional

The listener object

Returns

EventBus

Returns this for chaining

F   addEventListenerFor(obj, name, callback, options) → EventBus

Tell this object to listen to an event in another object, while keeping track of what it's listening to for easier unbinding later.

Parameters

obj : object | NodeList

The object to listen to events on

name : string | Array.<string> | object

Event name(s) or object of event/callback pairs

callback : function | object

Callback function or options object if name is an object

options : object optional

Event options

once : boolean optional

Whether the event should only trigger once

context : object optional

The context to bind the event to

Returns

EventBus

Returns this for chaining

F   dispatch(name)

Dispatches an action on the controller, running all appropriate aroundActions. This method is called by the router when a route matches.

Parameters

name : string

The name of the action to dispatch

F   dispatchEvent(name, args) → EventBus

Trigger one or many events, firing all bound callbacks. Callbacks are passed the same arguments as dispatchEvent is, apart from the event name (unless you're listening on "*", which will cause your callback to receive the true name of the event as the first argument).

Parameters

name : string | Array.<string>

Event name or array of event names

args : *

Arguments to pass to the event handlers

Returns

EventBus

Returns this for chaining

F   display(template, locals, options) → Promise.<(Element|Array.<Element>)>

A helper function to tell the Application to display the given template. This renders the template as the main content of the application.

Parameters

template : function

The template function to render

locals : Object optional

Local variables to pass to the template

options : Object optional

Display options to pass to the application

Returns

Promise.<(Element|Array.<Element>)>
  • Result of Application.display

Examples

this.display(userShow, {user: user})
this.display(loginForm, {}, {layout: false})
F   process(action, args)

Processes an action, setting up the response state and executing the action method.

Parameters

action : string

The name of the action to process

args : *

Arguments to pass to the action

F   redirectTo(path)

A helper function to tell the Application to navigate to the given URL or Path.

Parameters

path : string

The URL or path to navigate to.

F   removeEventListener(name, callback, options) → EventBus

Remove one or many callbacks that match the arguments. If called with no arguments, removes all callbacks for all events.

Parameters

name : string | Array.<string> | object | null optional

Event name(s) or object of event/callback pairs

callback : function | object | null optional

Callback function or options object if name is an object

options : object optional

Event options

once : boolean optional

Match only events set to trigger once

context : object optional

Match only events bound to this context

listener : object optional

Match only events bound by this listener

Returns

EventBus

Returns this for chaining

F   removeEventListenerFor(obj, name, callback, options) → EventBus

Tell this object to stop listening to either specific events or to every object it's currently listening to.

Parameters

obj : object | NodeList optional

The object to stop listening to; if omitted, stops listening to all objects

name : string | Array.<string> | object optional

Event name(s) or object of event/callback pairs

callback : function optional

Callback function to remove

options : object optional

Event options

once : boolean optional

Match only events set to trigger once

context : object optional

Match only events bound to this context

Returns

EventBus

Returns this for chaining

Static Methods