Skip to content

Commit

Permalink
updating the readme.md to the essentials
Browse files Browse the repository at this point in the history
  • Loading branch information
@jorishermans
jorishermans committed May 8, 2015
1 parent 5609645 commit 9baa560
Show file tree
Hide file tree
Showing 2 changed files with 340 additions and 211 deletions.
269 changes: 58 additions & 211 deletions readme.md
View file
Expand Up @@ -8,244 +8,91 @@ With this framework communication between client and server becomes easy, withou

Look at our wiki for more [info](https://github.com/ForceUniverse/dart-force/wiki) or this info below.

#### Walkthrough ####

##### Client side #####

Import the client side library for dart force.

import 'package:force/force_browser.dart';

First create a client.

ForceClient forceClient = new ForceClient();
forceClient.connect();

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};
forceClient.initProfileInfo(profileInfo);

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) {

@Receiver("play")
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');

##### Authentication #####

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.

#### Logging ####

You can easily boostrap logging.
#### Introduction ####

server.setupConsoleLog();
Dart Force is a Realtime web framework for [Dart](http://www.dartlang.org). We will make it easy for you to create realtime applications with it in [Dart](http://www.dartlang.org), like a chat, interactive dashboard, multiplayer games, ...

#### Other Annotations ####
#### How does it work? ####

In the @Receivable classes you can also use:
##### Serverside #####

@NewConnection : when a new socket connection is established
First of all you need a server to handle incoming messages and dispatch or handle this messages correctly.

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

@ClosedConnection : when a socket connection is been closed

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

#### Server 2 Server Communication ####
```dart
import "package:force/force_serverside.dart";
With the implementation of ServerSockets it is possible to use a ForceClient on the server.
ForceServer fs = new ForceServer();
This allows you todo server 2 server communication.
main() {
fs.server.use("/", (req, model) => "dartforcetodo");
On the Force Server you implements:
fs.start().then((_) {
fs.on("add", (vme, sender) {
fs.send("update", vme.json);
});
});
}
```

Connector connector = new ServerSocketConnector();
fs.addConnector(connector);

connector.start();
##### Clientside #####

On the other server where you want to sent messages to the Force Server you use:
The client can listen to messages:

ForceClient fc = new ForceClient();

fc.on("update", (fme, sender) {
print("todo: ${fme.json["todo"]}");
});
```dart
ForceClient fc;
void main() {
fc = new ForceClient();
fc.connect();
fc.onConnected.listen((e) {
fc.on("update", (fme, sender) {
querySelector("#list").appendHtml("<div>${fme.json["todo"]}</div>");
});
});
}
```

Under the hood it will establish a connection to the server socket.
You can also send messages:
```dart
InputElement input = querySelector("#input");
var data = {"todo": input.value};
fc.send("add", data);
```

It is a little bit inspired by [socket.io](http://socket.io) for the communication flow.

#### Quick starter guide ####

This guide can help you to get you started! [Getting started](https://github.com/ForceUniverse/dart-force/wiki/Getting-started)

* Reference
* [Long polling](https://github.com/ForceUniverse/dart-force/wiki/Long-polling)
* [Communication flow](https://github.com/ForceUniverse/dart-force/wiki/Communication-flow)
* [Profile management](https://github.com/ForceUniverse/dart-force/wiki/Profile-management)
* [Annotations](https://github.com/ForceUniverse/dart-force/wiki/Annotations)
* [ForceMVC: Serverside routing, similar too spring mvc](https://github.com/ForceUniverse/dart-force/wiki/ForceMVC%3A-Serverside-routing)
* [Authentication](https://github.com/ForceUniverse/dart-force/wiki/Authentication)
* [Google AppEngine](https://github.com/ForceUniverse/dart-force/wiki/Google-AppEngine)
* [Connectors](https://github.com/ForceUniverse/dart-force/wiki/Connectors)
* [Custom protocols](https://github.com/ForceUniverse/dart-force/wiki/Custom-protocols)
* [Clientside DB API](https://github.com/ForceUniverse/dart-force/wiki/Clientside-DB-API)
* [Server 2 Server Communication](https://github.com/ForceUniverse/dart-force/wiki/server-2-server)

#### 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.
Following the next steps will make it easier for you to develop, this allows you to adapt clientside files and immidiatly see results without doing a pub build.

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

#### GAE ####

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.

```dart
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](https://www.dartlang.org/cloud/)

### Notes to Contributors ###

Expand Down

0 comments on commit 9baa560

Please sign in to comment.