An add-on for using the Internet Computer in your EmberJS app.
- Ember.js v4.4 or above
- Ember CLI v4.4 or above
- Node.js v14 or above
ember install ember-cli-dfinity
<<<<<<< HEAD If you are building the app to run on the Internet Computer, then you must install the dfx-ember-webpack-plugin Webpack plugin into the dfx project so it builds the EmberJS asset canister correctly.
=======
8fa453e (v3.28.6...v4.12.2)
Actors are the primary artifacts (or components) exposed by a canister running on the Internet Computer. The actor has an interface, which represents the publicly accessible methods of the canister. When developing your own Dapp, you will have a candid interface for the actor like the following:
// hello.did
service : {
greet: (text) -> (text);
}
We import this interface definition into the EmberJS application to leverage it using the following command:
ember g dfx:actor hello --declaration
You must run this command from an EmberJS frontend application that is located in
$DFX_ROOT/src
. For example,$DFX_ROOT/src/hello_frontend
.$DFX_ROOT
is the root project directory of the Dapp, and has thedfx.json
file.
This command will create a symbolic link to the JavaScript declaration in
$ROOT/app/declarations
, and then define the actor hello
in $ROOT/app/actors
where $ROOT
is the root directory of the EmberJS frontend application.
There will be times you need to manually define an actor's interface. For example,
your frontend needs to reference a canister that is not local to your project. You
can use the @query
and @update
decorators to manually define an actor.
import { Actor, query, update } from 'ember-cli-dfinity';
export default class HelloActor extends Actor {
@query (['text'], ['text']) // can also write @query('text, 'text')
greet;
};
You use defined actors by injecting them into EmberJS an entity (e.g., controller,
router, service, component, etc.) using the @actor
decorator. For example, the
code below shows how you can inject the hello
actor into an EmberJS controller
and call the greet
method.
import Controller from '@ember/controller';
import { action } from '@ember/object';
import { tracked } from '@glimmer/tracking';
import { actor } from 'ember-cli-dfinity';
export default class IndexController extends Controller {
@tracked
name;
@tracked
greeting;
// Bind the hello actor to the hello variable.
@actor
hello;
@action
async submit(ev) {
// Prevent the default behavior for the submit button.
ev.preventDefault();
// Call the greet() method on the hello actor.
this.greeting = await this.hello.greet(this.name);
}
}
The config/environment.js
file is where you configure how the Dapp connects to the
Internet Computer. The configuration is auto-generated for you during the build
process. This allows the add-on to work out-of-the-box with little configuration
effort on your part. You, however, have the option of overriding the default
configurations via config/environment.js
.
// config/environment.js
module.exports = function (environment) {
let ENV = {
// ...
dfx: {
// Set the default canister name used for all actors. The name is either one of the
// names that appears in canister_ids.json, or in the canisters definition below.
defaultCanister: '',
// Set the default canister id used for all actors. This property takes precedence
// over defaultCanister when both are defined.
defaultCanisterId: '',
canisters: {
// Optional. You can define caninsters not defined in canister_ids.json, or
// override the existing canister ids here.
},
agents: {
// An optional list of agents that can be used by the @actor decorator. The
// add-on will automatically generate this agent list from the networks defined
// in dfx.json. You can override any auto-generate agent here similar to how
// we are overriding the agent for the `local` network.
local: {
// Define other @dfinity/agent options here.
host: 'http://127.0.0.1:8000',
},
},
}
};
// ...
}
See the Contributing guide for details.
This project is licensed under the Apache-2.0.