force 0.6.3

  • Installing
  • Versions
  • 1

Dart Force Framework


A realtime web framework for dart.

With this framework communication between client and server becomes easy, without any boilerplate code.

Look at our wiki for more info or this info below.


Client side

Import the client side library for dart force.

import 'package:force/force_browser.dart';

First create a client.

 ForceClient forceClient = new ForceClient();

Listen on the connection, when it is established.

 forceClient.onConnected.listen((e) {

Listen on the connection, when it is been broken.

 forceClient.onDisconnected.listen((e) {

Listen on messages with the request of text.

 forceClient.on("text", (e, sender) {

You can also send messages to the server.

forceClient.send('text', data);

When you are in the need to reply on a message, you can use the 'reply' method of sender.

forceClient.on("text", (e, sender) {
	sender.reply("received", ok_data);
Server Side

Import Serverside code for dart force.

import 'package:force/force_serverside.dart';

Instantiate a forceserver.

ForceServer fs = new ForceServer( port: 9223, startPage: 'start.html' );

Other optional properties that are possible on ForceServer:

wsPath: is the websocket path of the server host: is the domain name of your application, by default to localhost port: is the adres port of the application buildPath: is the build path of the application by default this is ../build/web/ startPage: the startpage of the application, the html name that the app needs to use as default root page staticDir: is the public directory where you can put your stylesheets and images

Listen on messages of type text and react upon that.

fs.on('text', (e, sendable) { 
    var json = e.json;
    var line = json['line'];
    sendable.send('text', { 'line': line });

You can also serve files from the server part.

fs.start().then((_) {
    fs.serve("/client.dart").listen((request) { 
      fs.serveFile("../web/client.dart", request);

You can listen when a new Socket connection is been created.

fs.onSocket.listen((SocketEvent se) {
	// socket event

Other features

Profile info & client to client communication

Adding profile data on a connection, this will make it easy to send a message to a certain profile group or sending messages to an individual, without knowing his websocket id.

On the client you can set the current browser user his profile data as follow.

 var profileInfo = { 'name' : chatName};

On the server you can send something to a profile or a profile group by the following method in sendable.

sendable.sendToProfile('name', name, 'private', message);

You can also listen to profileChanges by using the following method on the forceServer.

fs.onProfileChanged().listen((e) => print("$e"));

Now you can send directly from the client to another client, the server notice the message type and forward it directly to the corresponding client. No coding on server required todo this!

Just add the following code in your client side code.

forceClient.sendToProfile(key, value, request, data);
Long polling

You can easily use long polling as follow!

forceClient = new ForceClient(usePolling: true, heartbeat: 200);

Serverside Classes with Receiver method annotations

On the server you can use @Receiver on a method to define that this is a receiver method. It is the same as forceServer.on("play", (e, sendable) {

void onGamePlay(ForceMessageEvent vme, Sender sender) {

You can register this class with the register method of a ForceServer object.

forceServer.register(new GameReceiver());

You can also annotate a class with the @Receivable annotation, so the system can pick up this class and automatically register these classes.

Dart Force mvc access

You have access to the force mvc webserver if you do the following:

forceServer.server.on(url, controllerHandler, method: 'GET');

You can now add the annotation @Authentication to a receiver class.

You can also do the following.

forceServer.on("examplerequest", (e, sendable) {
   // do something
}, roles: ["ADMIN", "BASIC"]); 

An authentication in force is following a strategy. You can set a strategy by extending the class SecurityStrategy.

class SessionStrategy extends SecurityStrategy {
  bool checkAuthorization(HttpRequest req) {
    HttpSession session = req.session;
    return (session["user"]!=null);
  Uri getRedirectUri(HttpRequest req) {
    var referer = req.uri.toString();
    return Uri.parse("/login/?referer=$referer");

And then add this strategy to the webserver.

forceServer.server.strategy = new SessionStrategy();

When you are not authorized, the system sends the following message back: "unauthorized" with the data you send over the system. So you can also listen to the message "unauthorized" in your client, then you can inform the user he need to login.


You can easily boostrap logging.


Other Annotations

In the @Receivable classes you can also use:

@NewConnection : when a new socket connection is established

void connection(socketId, Socket socket) {
	print("new connection created for $socketId");

@ClosedConnection : when a socket connection is been closed

void closedConnection(socketId, Socket socket) {
	print("connection closed for $socketId");

Server 2 Server Communication

With the implementation of ServerSockets it is possible to use a ForceClient on the server.

This allows you todo server 2 server communication.

On the Force Server you implements:

Connector connector = new ServerSocketConnector();


On the other server where you want to sent messages to the Force Server you use:

ForceClient fc = new ForceClient();

fc.on("update", (fme, sender) {
      print("todo: ${fme.json["todo"]}");

Under the hood it will establish a connection to the server socket.

Development trick

Following the next steps will make it easier for you to develop, this allows you to adapt clientside files and immidiatly see results with doing a pub build.

pub serve web --hostname --port 7777 &&
export DART_PUB_SERVE="http://localhost:7777" &&
pub run bin/server.dart


You can now easily run your Force apps on a Google App Engine infrastructure by the following code! The rest is the same as a normal dart force app.

  ForceServer forceServer = new ForceServer();
  runAppEngine(forceServer.requestHandler).then((_) {
      // Server running. and you can do all the stuff you want!

You don't need to start ForceServer anymore, start of the server will be done by AppEngine!

More info about GAE overall

Notes to Contributors

Fork Dart Force

If you'd like to contribute back to the core, you can fork this repository and send us a pull request, when it is ready.

If you are new to Git or GitHub, please read this guide first.


Follow us on twitter


Follow us on google+

or join our G+ Community

Screencast tutorial

Screencast todo tutorial about the dart force realtime functionality on youtube

Join our discussion group

Google group


Links to some examples that I made with this framework.

chat - source code

polymer example - source code


This file contains highlights of what changes on each version of the force package.

Pub version 0.6.3

  • add onChange listener on viewCollection
  • change logic of keep alives to native keep alive implementation of a websocket

Pub version 0.6.2+2

  • add some logging about the keep alive

Pub version 0.6.2 & 0.6.2+1

  • keep a state of message when the client is offline, when it is back online we send these messages to the server
  • add a ping / pong protocol
  • add a keep alive timer, that send every x seconds ping signals to the clients

Pub version 0.6.1

  • add options possibility of cargo into the db client api of force
  • easier transform your clientside objects with serialize function
  • upgrade to forcemvc 0.7.0 and wired 0.4.3

Pub version 0.6.0

  • designing clientside db api
  • ForceClient: BC BREAK - port should be int instead of String
  • adding protocols wiring into force, having 2 clean api's next to eachother, db & communication api.
  • improvements on forceclient

Pub version 0.5.7

  • adapting the start method so it is compliant with the latest ForceMVC release! Future start({FallbackStart fallback})

Pub version 0.5.6+1

  • exporting underlying packages!

Pub version 0.5.6

  • Add 'reply' method to sender
  • It works in IE9
  • Upgrade to the latest ForceMVC implementations

Pub version 0.5.5

  • Server to server communication, based upon ServerSockets
  • Introducing connectors

Pub version 0.5.4

  • Prepare code for use on appengine

Pub version 0.5.3

  • Add new annotation @ClosedConnection and event stream for closedConnection
  • Add more documentation in the code

Pub version 0.5.2

fix dependencies on 'wired'

Pub version 0.5.1 & pub version 0.5.1+1

introduce @NewConnection send a message 'ack' to the new client on connection

Pub version 0.5.0+1

Improve internal working.

Pub version 0.5.0

Remove parentheses from annotations. Upgrade to latest forcemvc version (0.5.0+1). Expanding functionality for authentication with roles, like in forcemvc. Adding broadcast functionality

Pub version 0.4.2+1

Moving this framework to an organisation repo in github

Pub version 0.4.2

When a new Socket is been created a new SocketEvent will be added.

Pub version 0.4.1+1

Small changes in the Force class, renaming of the handle method.

Pub version 0.4.1

Making the force logic abstract, independent of the serverside http logic.

Pub version 0.4.0+2

Adding more tests for polling implementation, small improvements to the polling implementation.

Pub version 0.4.0 & 0.4.0+1

Make it possible to add @Autowired and @Value into the classes with @Receivable annotations.

Pub version 0.3.7

Making the setup of a project easier by creating a logging function.

Pub version 0.3.6

Add authentication rules into the framework.

Pub version 0.3.5

New structure! Look at the examples.

Pub version 0.3.4

Add host and port parameters to force client.

Pub version 0.3.3+10

Update dependency forcemvc.

Pub version 0.3.3+9

Improve the working of the polling mechanics into the right direction.

Pub version 0.3.3+8

Updating uuid package dependencies

Pub version 0.3.3+7

Adding option for static folder of force mvc, staticDir.

Pub version 0.3.3+6

Updating dependencies.

Pub version 0.3.3+5

Solving issue with startpage rendering!

Pub version 0.3.3+4

Updated this buildPath: '../build/web' to get it working in Dart 1.2

Pub version 0.3.3+2 & 0.3.3+3

Updating dependencies.

Pub version 0.3.3+1

Changing force_serveable with serve(name) with typing it with String.

Pub version 0.3.3

Introducing @Receivable so you can annotate a class that has receiver methods.

Pub version 0.3.2+4

Updating dependencies and force mirrors code.

Pub version 0.3.2+2

Solving the initialization of the client socket.

Pub version 0.3.2

Solving issue #12 and more toolable way to handle connecting. So now you need to implement onConnected and onDisconnected.

Pub version 0.3.1+3

You have access to the webserver through server property of the force server implementation.

Pub version 0.3.1+2

Update to the new force mvc package, update polling server code.

Pub version 0.3.1+1

Iterate over all the annotations at a method until you found the Receiver annotation.

Pub version 0.3.1

Extract webServer code and put it into forcemvc package

Pub version 0.3.0+5 & 0.3.0+6

Some small changes in logging and an update to the documentation.

Pub version 0.3.0+4

Adding a generateId method to the forceclient class. So you can use this unique id in the client to start something, for example a gamesession!

Pub version 0.3.0+3

Added an optional parameter url to forceclient so you can set the url to another hosted force server endpoint. Added an optional parameter heartbeat, to specify in milliseconds the heartbeat duration.

Pub version 0.3.0+2

Refactor the code so it uses a factory instead of a static method to choose the socket implementation clientside. Fixed an small issue when sending characters through polling and receiving it again.

Pub version 0.3.0+1

Sending the old property values in the profile changed event. So you can use the old value and look at the new value in profileInfo field.

Pub version 0.3.0

Adding socket abstraction to the dart force framework and add also the long polling mechanism as an alternative for websockets.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  force: ^0.6.3

2. Install it

You can install packages from the command line:

with pub:

$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:force/cargo/cargo_holder.dart';
import 'package:force/cargo/cargo_holder_client.dart';
import 'package:force/cargo/cargo_holder_server.dart';
import 'package:force/cargo/cargo_package.dart';
import 'package:force/cargo/cargo_package_dispatcher.dart';
import 'package:force/cargo/cargo_protocol.dart';
import 'package:force/cargo/data_changeable.dart';
import 'package:force/cargo/view_collection.dart';
import 'package:force/client/browser_messenger.dart';
import 'package:force/client/connect_event.dart';
import 'package:force/client/force_client.dart';
import 'package:force/clientsocket/abstract_socket.dart';
import 'package:force/clientsocket/polling_socket.dart';
import 'package:force/clientsocket/websocket_wrapper.dart';
import 'package:force/common/basic_sendable.dart';
import 'package:force/common/basic_sender.dart';
import 'package:force/common/client_context.dart';
import 'package:force/common/client_sendable.dart';
import 'package:force/common/package.dart';
import 'package:force/common/protocol.dart';
import 'package:force/connectors/connector.dart';
import 'package:force/connectors/server_socket_connector.dart';
import 'package:force/force_browser.dart';
import 'package:force/force_common.dart';
import 'package:force/force_serverside.dart';
import 'package:force/message/base_message.dart';
import 'package:force/message/message_dispatcher.dart';
import 'package:force/message/message_package.dart';
import 'package:force/message/message_security.dart';
import 'package:force/message/message_type.dart';
import 'package:force/message/messages_construct_helper.dart';
import 'package:force/pingpong/pingpong_dispatcher.dart';
import 'package:force/pingpong/pingpong_package.dart';
import 'package:force/pingpong/pingpong_protocol.dart';
import 'package:force/server/force.dart';
import 'package:force/server/force_context.dart';
import 'package:force/server/force_server.dart';
import 'package:force/server/force_typedefs.dart';
import 'package:force/server/metadata.dart';
import 'package:force/server/polling_server.dart';
import 'package:force/server/profile_event.dart';
import 'package:force/server/serveable.dart';
import 'package:force/server/server_protocol.dart';
import 'package:force/server/socket_event.dart';
import 'package:force/serverclient/force_client.dart';
import 'package:force/serverclient/server_messenger.dart';
import 'package:force/serversocket/abstract_socket.dart';
import 'package:force/serversocket/polling_socket.dart';
import 'package:force/serversocket/server_socket.dart';
import 'package:force/serversocket/stream_socket.dart';
import 'package:force/serversocket/websocket_wrapper.dart';
Version Uploaded Documentation Archive
0.7.1 Jul 16, 2016 Go to the documentation of force 0.7.1 Download force 0.7.1 archive
0.7.0 Apr 14, 2016 Go to the documentation of force 0.7.0 Download force 0.7.0 archive
0.6.5+1 Jun 19, 2015 Go to the documentation of force 0.6.5+1 Download force 0.6.5+1 archive
0.6.5 Jun 7, 2015 Go to the documentation of force 0.6.5 Download force 0.6.5 archive
0.6.4 May 8, 2015 Go to the documentation of force 0.6.4 Download force 0.6.4 archive
0.6.3+4 Apr 24, 2015 Go to the documentation of force 0.6.3+4 Download force 0.6.3+4 archive
0.6.3+3 Apr 19, 2015 Go to the documentation of force 0.6.3+3 Download force 0.6.3+3 archive
0.6.3+2 Apr 13, 2015 Go to the documentation of force 0.6.3+2 Download force 0.6.3+2 archive
0.6.3+1 Apr 13, 2015 Go to the documentation of force 0.6.3+1 Download force 0.6.3+1 archive
0.6.3 Apr 6, 2015 Go to the documentation of force 0.6.3 Download force 0.6.3 archive

All 105 versions...

Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

This package version is not analyzed, because it is more than two years old. Check the latest stable version for its analysis.

Maintenance issues and suggestions

Running dartdoc failed. (-10 points)

Make sure dartdoc runs without any issues.