The interstellar-core
module is part of the Interstellar Module System.
It provides the lowest level functionality: a core JS wrapper.
Quick start to developing in the Interstellar eco-system:
- Read
Getting started
doc.- Install
interstellar-workspace
.- Contribute to our open-source modules or develop your own.
Module
App
Inject
annotationController
annotationProvider
annotationService
annotationWidget
annotationIntent
None.
Module is a wrapper around Angular.js module. Every Interstellar module is a Module
object and Angular.js module. Module
provides several methods to help configure a module. It also provides autoloading support for controllers, templates, services, directives and other components.
import {Module} from "interstellar-core";
export const mod = new Module('interstellar-example');
mod.use(interstellarSomeModule.name);
mod.controllers = require.context("./controllers", true);
mod.directives = require.context("./directives", true);
mod.services = require.context("./services", true);
mod.templates = require.context("raw!./templates", true)
mod.define();
App
class extends Module
class and provides helper methods for the final Interstellar application that use other modules. It provides additional functionality like ui-router
. The second parameter in a constructor is a configuration JSON.
import {App, mod as interstellarCore} from "interstellar-core";
import {mod as interstellarStellarWallet} from "interstellar-stellar-wallet";
import {mod as interstellarNetwork} from "interstellar-network";
import {mod as interstellarSettings} from "interstellar-settings";
import {mod as interstellarStellarApi} from "interstellar-stellar-api";
let config = require('./config.json');
export const app = new App("interstellar-stellar-client", config);
app.use(interstellarCore.name);
app.use(interstellarStellarWallet.name);
app.use(interstellarNetwork.name);
app.use(interstellarSettings.name);
app.use(interstellarStellarApi.name);
app.templates = require.context("raw!./templates", true);
app.controllers = require.context("./controllers", true);
app.routes = ($stateProvider) => {
$stateProvider.state('login', {
url: "/login",
templateUrl: "interstellar-stellar-client/login"
});
$stateProvider.state('dashboard', {
url: "/dashboard",
templateUrl: "interstellar-stellar-client/dashboard",
requireSession: true
});
// ...
};
// Callbacks to execute in `config` block.
app.config(configureServices);
// Callbacks to execute in `run` block.
app.run(registerBroadcastReceivers);
app.bootstrap();
Decorator class to inject dependencies to your controllers or services using AngularJS injector subsystem:
import {Inject} from 'interstellar-core';
@Inject("interstellar-sessions.Sessions", "interstellar-network.Server")
class ReceiveWidgetController {
constructor(Sessions, Server) {
this.Server = Server;
this.Sessions = Sessions;
}
}
Decorator class to annotate your controllers.
import {Controller, Inject} from 'interstellar-core';
@Controller("HeaderController")
@Inject("interstellar-sessions.Sessions", "interstellar-network.Server")
export default class HeaderController {
constructor(Sessions, Server) {
this.Server = Server;
this.Sessions = Sessions;
}
// ...
}
Heads up! Annotated class must be exported as
default
.
Decorator class to annotate your providers.
import {Provider} from 'interstellar-core';
@Provider("Config")
export default class ConfigProvider {
constructor() {
this.appConfig = {};
this.modulesConfig = {};
}
// ...
}
Heads up! Annotated class must be exported as
default
.
Decorator class to annotate your services.
import {Service} from 'interstellar-core';
@Service('IntentBroadcast')
export default class IntentBroadcastService {
constructor() {
this.receivers = {};
}
// ...
}
Heads up! Annotated class must be exported as
default
.
Decorator class to annotate your widgets' controllers.
This annotation requires 3 arguments:
- directive name,
- controller name,
- template name.
import {Widget, Inject} from 'interstellar-core';
@Widget("balance", "BalanceWidgetController", "interstellar-network-widgets/balance-widget")
@Inject("$scope", "interstellar-sessions.Sessions", "interstellar-network.AccountObservable", "interstellar-network.Server")
export default class BalanceWidgetController {
constructor($scope, Sessions, AccountObservable, Server) {
if (!Sessions.hasDefault()) {
console.error('No session. This widget should be used with active session.');
return;
}
// ...
}
// ...
}
Heads up! Annotated class must be exported as
default
.
Modules in Interstellar communicate by broadcasting Intent
objects using Android-inspired intent system. Modules can:
- Broadcast Intents to trigger some events in other modules,
- Register Broadcast Receivers to listen to Intents sent by other modules.
Every Intent has a type which must be one of standard intent types:
SEND_TRANSACTION
- User wants to send a transaction.SHOW_DASHBOARD
- User wants to see a dashboard.LOGOUT
- User wants to logout.
Intent
can also contain additional data helpful for a Broadcast Receiver. For example, SEND_TRANSACTION
Intent can contain destination address.
// Sending Broadcast
IntentBroadcast.sendBroadcast(
new Intent(
Intent.TYPES.SEND_TRANSACTION,
{destination: this.destination}
)
);
// Receiving Broadcast
IntentBroadcast.registerReceiver(Intent.TYPES.SEND_TRANSACTION, intent => {
widget.set('destinationAddress', intent.data.destination);
});
interstellar-core.IntentBroadcast
service is responsible for delivering Intent
s to correct Broadcast Receivers. It has two methods:
sendBroadcast(intent)
- to broadcast anIntent
,registerReceiver(type, broadcastReceiver)
- to register Broadcast Receiver of specific type.
The Config service provides the system through which the client can retrieve configuration flags. It provides a get(configName)
to which clients can retrieve values.
Conceptually, an application's configuration presents itself as a simple nested json object.
interstellar-core.Config
provider has 2 methods that App
and Module
s can use to define configuration values:
All config values added by modules are treated as default values that can be overwritten by the App
config. For example, let's say interstellar-network
module adds following config JSON using addModuleConfig
:
{
"horizon": {
"secure": true,
"hostname": "horizon-testnet.stellar.org",
"port": 443
}
}
To overwrite this module's configuration, an app needs to add following config JSON using addAppConfig
:
{
"modules": {
"interstellar-network": {
"horizon": {
"secure": false,
"hostname": "horizon.example.com",
"port": 80
}
}
}
}
Once you have an instance of the config service (using normal angular DI mechanisms), you may access any previously loaded configuration using a "dot separated" accessor string. For example, say the App
configuration data is the json object below:
{
"horizon": {
"secure": true,
"hostname": "horizon-testnet.stellar.org",
"port": 443
}
}
You can retrieve the address for the horizon with:
let hostname = Config.get("horizon.hostname");
Getting configuration values in Module
is a little different. During configuration phase all modules' configurations are appended to modules
object in the main config JSON. For example, let's say interstellar-network
module adds following configuration:
{
"horizon": {
"secure": true,
"hostname": "horizon-testnet.stellar.org",
"port": 443
}
}
Now, you can retrieve the address for the horizon with:
let hostname = Config.get("modules.interstellar-network.horizon.hostname");
In the spirit of failing fast, consumers of the config service can apply type restrictions to config variables, such that an exception will be thrown at the point of retrieval if the result is of the wrong type. For example, given a config object of {"foo": "bar"}
, executing the statement Config.getNumber("foo")
will throw an exception because the result ("bar") is a string.