Introduction
The sample-ext-app is an external application that can interact with a Cytomine instance.
It is an almost empty web application to show you how to implement your own business functionnalities by creating an external app without modifying the Cytomine core.
This is just a sample app that could serve as a basis for your own application using Cytomine. It first provides a form where you have to enter your Cytomine public and private keys (you can retrieve them on your Cytomine account page). Next the app lists all available projects. If you click on the image links, you will get the project images. You may click on each image button to open it on the Cytomine application (you must be logged on Cytomine). You can use similar principles to access any data stored in the main Cytomine core server instance (e.g. user annotations,...).
Before reading this article, you should:
- Be familiar with Grails web framework (following a simple tutorial will be enough),
- Be familiar with AngularJS (same as for Grails),
- Install Grails (version 2.3.5, higher should work too),
- Download the sample-ext-app sources
This is SAMPLE WEBAPP. We provide almost no error handling and no test. We provide a very simple authentification mechanism.
Technologies
We use these technologies for the server:
Name | Description | URL |
---|---|---|
Grails | Web framework to build the server | https://grails.org/ |
Cytomine Java Client | A client to easily interact with Cytomine REST API | No URL, the jar is in lib/ folder |
For the client:
Name | Description | URL |
---|---|---|
AngularJS | Web framwork to build the client | https://angularjs.org/ |
Bootstrap | CSS-based design template | http://getbootstrap.com |
ng-table | An external lib to easily build data tables with AngularJS | http://ngmodules.org/modules/ng-table |
Execute
You first need a Grails 2.3.5 installed (higher versions version should be ok after upgrating).
- Move to the app directory (directory containing application.properties file),
- Update the grails.cytomine.host config option from the grails-app/conf/Config.groovy file if necessary (by default: "http://beta.cytomine.be").
Run:
grails run-app
By default, the server listens on port 8080. You should see something like this:
Server running. Browse to http://localhost:8080/index.htmlGo to this link. You should see the form to enter your Cytomine credentials (keys). To get your keys, go to Cytomine, in your account page.
Server
This is a very light Grails server.
Config
All config data are in grails-app/conf/Config.groovy. These config data may be externalized in a real config file (see http://grails.org/doc/latest/guide/single.html#configExternalized). For the sample app, there are hard-coded.
grails.cytomine.host = "http://beta.cytomine.be"
The grails-app/conf/DataSource.groovy file contains config data for the database connection. We keep default value since we don't need a database for the sample app.
Startup
When you run the server (using run-app or running the war in container), Grails launch the grails-app/conf/BootStrap.groovy init method. This method is empty for our sample app.
Request
Each HTTP request is first processed by the grails-app/conf/UrlMappings.groovy. This file contains mapping rules. A mapping rule defines that for an HTTP request on path with a specific verb, the request must trigger a specific controller method.
"/api/project.$fomat"(controller:"cytomine"){ action = [GET: "projects"] }
This rule simply tells that when you do a GET on /api/project.json, you call the method CytomineController.projects() (controller name starts with a lowercase and is written without “Controller” prefix).
We have defined a filter in grails-app/conf/SecurityFilters.groovy. Before each request, we retrieved the cytomine credentials and we init the Cytomine connection. Each request using Cytomine data (e.g. get project lists, get images from project) must have publicKey and privateKey as parameters.
String publicKey = params.get("publicKey") String privateKey = params.get("privateKey") request['cytomine'] = new Cytomine(grailsApplication.config.grails.cytomine.host,publicKey,privateKey,"./")
In grails-app/controllers/be/cytomine/sample.CytomineController, we've defined some methods using the Cytomine connection.
def projects() { render request['cytomine'].getProjects().list as JSON }
This method simply call the getProjects() method from the Cytomine client instance and render the content in JSON as the request response.
To recap, if a GET method is done on /api/project.json with the good credentials (Run http://localhost:8080/api/project.json?privateKey=...&publicKey=... in your browser):
- The url mapping finds the good rule and calls CytomineController.projects() method,
- The filters occurs just before the method call, extract keys from URL params and create a Cytomine instance (stored in request['cytomine']),
- The method projects() uses the Cytomine Client to retrieve your projects. The method getProjects() from the client simply does a GET /api/project.json on the Cytomine instance and returns the result as a list,
- The method returns the project list as a JSON
Web Client
Its a basic AngularJS app. The entry point is the web-app/index.html file. All the routes are defined in web-app/mainapp.js.
URL | Content for <ng-view> | Description |
---|---|---|
By default | views/projects.html | Print projects listing view |
/index.html#/home | views/projects.html | Same as before |
/index.html#/project/:idProject/image | views/images.html | Print the project images view |
The interesting part from the index.html file is:
<div ng-show="publicKey"> <ng-view></ng-view> </div> <div ng-hide="publicKey" ng-include src="'views/keys.html'"></div>
The ng-view adds the content from the mainapp.js mapping (e.g. content from web-app/views/projects.html if /home). This content is shown only if publicKey is set in the AngularJS scope (from mainController.js). If not, we set the content from keys.html (a form to enter public and private keys). Keys are stored using HTML5 local storage.
Views file (html) are link with AngularJS controllers (web-app/controllers). Service files (web-app/services) are used to interact with Cytomine.