API Reference v0.3

Welcome to the Breach API reference wiki. This document details the different methods that are available while developing your own modules. We assume that you have read the wiki on creating a new module and understand how to initialise your module.

This reference applies to versions <= v0.3 of breach_core.
The next version v0.4 will be based on exo_browser v0.7 and will see it's API profoundly change over time.

Index

• Core Tabs (source)
  • #tabs_close
  • #tabs_show
  • #tabs_focus
  • #tabs_get
  • #tabs_load_url
  • #tabs_back_or_forward
  • #tabs_reload
  • #tabs_find_next
  • #tabs_find_stop
  • #tabs_devtools
  • #tabs_set_context_menu_builder
  • #tabs_new_tab_url
  • #tabs_state
• Core Modules (source)
  • #modules_add
  • #modules_install
  • #modules_remove
  • #modules_update
  • #modules_run
  • #modules_kill
  • #modules_list
• Core Controls (source)
  • #controls_set
  • #controls_unset
  • #controls_dimension
  • #controls_focus

Modules API Quick Start

To access any of these methods within your module all you need to do is reference the call method like so:

breach.module('core').call('method_name', args, callback);

This will pass any arguments your provide (using the args object) to the method you reference, once completed the callback will be triggered.

The callback will be provided with two arguments (err and res). If no error has occurred err will be undefined and if nothing is returned res will be undefined too.

Here is an example callback:

function(err, res) {
  if (err) return console.log('Error occurred: %s', err);
  
  console.log('The computer says: %s', res);
}

Core Tabs

The core tabs module is in charge of managing all the browser's tabs.

tabs_close

Closes the specified tab.

Parameters

• String id (required) - The tab's ID.
• String next - The tab to switch to once id has been closed.
• Boolean focus - Whether to focus on the next tab.

Examples

breach.module('core').call('tabs_close', {
  id: '881d3dc8c12b8c8a08db935a292d448ceed6c3fc',
  next: '771q4dj2a33b2d1o92kj923f392f291skke2b2kc',
  focus: true
}, function(err) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

---

tabs_show

Switches to the specified tab.

Parameters

• String id (required) - The tab's ID.
• Boolean focus - Whether to focus on the next tab.

Examples

breach.module('core').call('tabs_show', {
  id: '881d3dc8c12b8c8a08db935a292d448ceed6c3fc',
  focus: false
}, function(err) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

---

tabs_focus

Focuses on the specified tab (and makes it visible before if required).

Parameters

• String id (required) - The tab's ID.

Examples

breach.module('core').call('tabs_focus', {
  id: '881d3dc8c12b8c8a08db935a292d448ceed6c3fc'
}, function(err) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

---

tabs_get

Retrieves the specified tab's state. If no arguments are provided all tabs will be returned.

Parameters

• String id - The tab's ID.

Examples

Return specific tab.

breach.module('core').call('tabs_get', {
  id: '881d3dc8c12b8c8a08db935a292d448ceed6c3fc'
}, function(err, res) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

Return all tabs.

breach.module('core').call('tabs_get', {}, function(err, res) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

---

tabs_load_url

Loads the specified URL in the specified tab.

Parameters

• String id (required) - The tab's ID.
• String url (required) - The URL to loead.

Examples

breach.module('core').call('tabs_load_url', {
  id: '881d3dc8c12b8c8a08db935a292d448ceed6c3fc',
  url: 'http://google.com'
}, function(err, res) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

---

tabs_back_or_forward

Go back or forward a specified number of pages.

Parameters

• String id (required) - The tabs' ID.
• Number offset (required) - The number of pages to go back or forward.

Examples

breach.module('core').call('tabs_back_or_forward', {
  id: '881d3dc8c12b8c8a08db935a292d448ceed6c3fc',
  offset: 2
}, function(err) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

---

tabs_reload

Reloads a specified tab.

Parameters

• String id (required) - The tab's ID.

Examples

breach.module('core').call('tabs_reload', {
  id: '881d3dc8c12b8c8a08db935a292d448ceed6c3fc'
}, function(err) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

---

tabs_find_next

Find the next search match in the specified tab.

Parameters

• String id (required) - The tab's ID.
• String text (required) - ...
• Boolean forward - ...
• Boolean case - Whether the search is case-sensitive.
• Boolean next - ...

Examples

breach.module('core').call('tabs_find_next', {
  id: '881d3dc8c12b8c8a08db935a292d448ceed6c3fc',
  text: 'something',
  forward: true,
  case: true,
  next: false
}, function(err, res) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

---

tabs_find_stop

Stop searching for matches in the specified tab.

Parameters

• String id (required) - The tab's ID.
• Function action - ...

Examples

breach.module('core').call('tabs_find_stop', {
  id: '881d3dc8c12b8c8a08db935a292d448ceed6c3fc',
  action: stop_action
}, function(err, res) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

---

tabs_devtools

Returns the devtools URL for the specified tab.

Parameters

• String id (required) - The tab's ID.
• String element_at - ...

Examples

breach.module('core').call('tabs_devtools', {
  id: '881d3dc8c12b8c8a08db935a292d448ceed6c3fc',
  element_at: '...'
}, function(err, res) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

---

tabs_set_context_menu_builder

Registers a context menu handler for the calling module. The procedure specified will get called when the context menu needs to get built. If no procedure is specified, then the module calling is unregistered.

That procedure returns an array of menu items { items: [] }. When an entry is clicked the core module will emit an event tabs:context_menu with event parameters the tab id and the item and src of the item clicked.

Parameters

• String id (required) - The tab's ID.
• String procedure - ...

Examples

breach.module('core').call('tabs_set_context_menu_builder', {
  id: '881d3dc8c12b8c8a08db935a292d448ceed6c3fc',
  procedure: '...'
}, function(err) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

---

tabs_state

Returns the state of the current tab.

Examples

breach.module('core').call('tabs_state', {}, function(err, res) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

Core Modules

The core module exposes Breach API to other modules and maintains the navigation state. The navigation state is tracked and synchronised across devices by the core module. It is also exposed to other modules along with mutators to update the navigation state.

modules_add

Adds the specified module.

Parameters

• String path (required) - The module path name.

Examples

breach.module('core').call('modules_add', {
  path: 'github:breach/mod_strip'
}, function(err, res) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

---

modules_install

Installs the specified module.

Note: You must add the module first.

Parameters

• String path (required) - The module path name.

Examples

breach.module('core').call('modules_install', {
  path: 'github:breach/mod_strip'
}, function(err, res) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

---

modules_remove

Removes the specified module.

Parameters

• String path (required) - The module path name.

Examples

breach.module('core').call('modules_add', {
  path: 'github:breach/mod_strip'
}, function(err, res) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

---

modules_update

Updated the specified module.

Parameters

• String path (required) - The module path name.

Examples

breach.module('core').call('modules_update', {
  path: 'github:breach/mod_strip'
}, function(err, res) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

---

modules_run

Runs the specified module.

Parameters

• String path (required) - The module path name.

Examples

breach.module('core').call('modules_run', {
  path: 'github:breach/mod_strip'
}, function(err, res) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

---

modules_kill

Kills the specified module.

Parameters

• String path (required) - The module path name.

Examples

breach.module('core').call('modules_kill', {
  path: 'github:breach/mod_strip'
}, function(err, res) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

---

modules_list

Lists all the modules added to Breach.

Examples

breach.module('core').call('modules_list', {}, function(err, res) {
  if (err) return console.log('Unexpected Error: %s', err);
  // ...
});

Core Controls

The controls module is in charge of displaying and maintaining the state of browser controls. Controls are visual elements that persist across all parts of the browsing experience.

controls_set

Sets a control for the specific control type.

Parameters

• String type (required) - The control type reference.
• String url (required) - The url where control template is located.
• Number dimension - The size of the control.
• Boolean focus - Whether to focus on the control.

Examples

breach.module('core').call('controls_set', {
  type: 'LEFT',
  url: 'http://127.0.0.1:' + port + '/my_controls',
  dimension: 250,
  focus: false
}, function(err) {
  if (err) return console.log('Unexpected error: %s', err);
  // ...
});

---

controls_unset

Unset the controls for a specific control type.

Parameters

• String type (required) - The control type reference.

Examples

breach.module('core').call('controls_unset', {
  type: 'LEFT'
}, function(err) {
  if (err) return console.log('Unexpected error: %s', err);
  // ...
});

---

controls_dimension

Set the dimensions for the specified control.

Parameters

• String type (required) - The control type reference.
• Number dimension - The size of the control.
• Boolean focus - Whether to focus on the control.

Examples

breach.module('core').call('controls_dimension', {
  type: 'LEFT',
  dimension: 250,
  focus: false
}, function(err) {
  if (err) return console.log('Unexpected error: %s', err);
  // ...
});

---

controls_focus

Focuses control for the specified control type.

Parameters

• String type (required) - The control type reference.

Examples

breach.module('core').call('controls_focus', {
  type: 'LEFT'
}, function(err) {
  if (err) return console.log('Unexpected error: %s', err);
  // ...
});