-
Notifications
You must be signed in to change notification settings - Fork 2
ILS Library with graasp.eu
This javascript library provides APIs to developers, allowing apps to access info and data in the ILS they are running in.
An ILS contains by default five phases: Orientation, Conceptualisation, Investigation, Conclusion, Discussion, in addition to a Vault space, and an About space intended for ILS management by teachers. Each phase could contain a few apps, and the Vault is used for data exchange between apps. For instance, one app could save a data file in the Vault, and another app could read this file from the Vault. This library will allow apps to exchange data via the APIs.
#### getCurrentUser(callback: function(result: string): void): string Gets the nickname of the current student, and returns it in the callback.
callback: function(result: string):void a callback function to handle the returned result
result: a String object containing the nickname of the user of the user
Result example on success (for old and new Graasp):
"Mario"
Result example on failure:
{
"error": "cannot find the nickname"
}
Returns the parent space of the widget in the callback.
callback(result): a callback function to handle the returned result
result: a JSON object containing the parent space properties
Result example on success:
{
id: "54607f87c276f5e27d84b04a",
parentId: "54607f87c276f5e27d84b043",
profileUrl: "http://localhost:8000/spaces/54607f87c276f5e27d84b04a",
updated: "2014-11-10T09:10:16.673Z",
created: "2014-11-10T09:04:07.474Z",
description: "Welcome to the Orientation phase. You can describe here what students have to do in the Orientation phase.",
displayName: "Orientation",
metadata: {type: "Orientation"},
ObjectparentId: "54607f87c276f5e27d84b043",
parentType: "@space",
profileUrl: "http://graasp.eu/spaces/54607f87c276f5e27d84b04a",
spaceType: "folder",
visibilityLevel: "public"
}
Result example on failure:
{
"error": "cannot get the parent"
}
- A new parameter has been included: created
- objectId is no longer included. Nevertheless the same information can be obtained using the already existing id.
- The format for ids has been modified: from numeric to alphanumeric
- The format for the profileUrl has been modified: from http://server/#item=space_spaceId to http://server/spaces/spaceId
- spacetype has been replaced by spaceType
- The values available for spaceType are: 'ils' or 'folder' ('group' is not supported anymore)
- The values available for metadata.type are: 'ils', 'Orientation', 'Conceptualisation', 'Investigation', 'Conclusion', 'Discussion', 'About', 'Vault' If a user changes the title of a phase, it will not be reflected in the "metadata.type". In case of new phases, no "metadata.type" will be provided.
- The values available for visibilityLevel are: 'public' or 'private' ('hidden' not supported)
Deletes resource in Vault of current ILS.
callback(result): a callback function to handle the returned result
result: a boolean object reflecting the success or failure of resource deletion
Result example on success:
true
Result example on failure:
{
"error": "Couldn't remove resource"
}
Checks whether a resource exists in the Vault of current ILS or not.
callback(result): a callback function to handle the returned result
result: a boolean reflecting whether the resource is found or not in Vault of current ILS
Result example on success:
true
Result example on failure:
false
Returns metadata of resource
callback(result): a callback function to handle the returned result
result: a JSON object containing the metadata of the specified resource
Result example on success:
{
"actor": {
"objectType": "person",
"id": "e1b8948f-321e-78ca-d883-80500aae71b5",
"displayName": "anonymized"
},
"target": {
"objectType": "conceptMap",
"id": "4b8f69e3-2914-3a1a-454e-f4c157734bd1",
"displayName": "my first concept map"
},
"generator": {
"objectType": "application",
"url": "http://www.golabz.eu/content/go-lab-concept-mapper",
"id": "c9933ad6-dd4a-6f71-ce84-fb1676ea3aac",
"displayName": "ut.tools.conceptmapper"
},
"provider": {
"objectType": "ils",
"url": "http://graasp.epfl.ch/metawidget/1/b387b6f",
"id": "10548c30-72bd-0bb3-33d1-9c748266de45",
"displayName": "Black body experiments"
}
}
Result example on failure:
{
"error": "The resource has no metadata"
}
updateResource(resourceId: string, content: object, metadata: object, callback: function(result: object): void): object
Updates an existing resource in the Vault, and returns the updated resource.
callback(result): a callback function to handle the returned result
result: a JSON object containing the updated resource's properties
Result example on success:
{
content: "",
id: "5460812ec276f5e27d84b295",
parentId: "54607f87c276f5e27d84b091",
updated: "2014-11-11T12:45:22.261Z",
created: "2014-11-10T09:11:10.914Z",
description: "",
displayName: "test",
parentId: "54607f87c276f5e27d84b091",
updated: "2014-11-11T12:45:22.261Z",
url: "http://graasp.eu/resources/5460812ec276f5e27d84b295",
visibilityLevel: "private"
}
Result example on failure:
{
"error" : "Couldn't update resource"
}
Returns the current Ils in the callback.
callback(result): a callback function to handle the returned result
result: a JSON object containing the ILS space properties
Result example on success:
{
"created": "2014-10-21T16:21:40.295Z",
"description": "some text",
"displayName": "ils_example",
"id": "544688141b3e3f00004156c7",
"ilsRef":
{
__v: 0,
_id: "544688142e2c55fc49b625e8",
lang: "en",
modified: "2014-10-21T16:21:40.339Z",
spaceRef: "544688141b3e3f00004156c7",
userRef: "5405e215da3a95cf9050eaf1"
},
"metadata": {"type":"ils"},
"parentId": "5405e1ada5ecce255b4a7222",
"parentType": "@space",
"profileUrl": "http://graasp.eu/spaces/544688141b3e3f00004156c7",
"spaceType": "ils",
"updated": "2014-10-21T16:21:40.503Z",
"visibilityLevel": "public"
}
Result example on failure:
{
"error": "cannot get the Ils"
}
- New parameters have been included: created and ilsRef (the last one to be reviewed)
- objectId is no longer included. Nevertheless the same information can be obtained using the already existing id.
- The format for ids has been modified: from numeric to alphanumeric
- The format for the profileUrl has been modified: from http://server/#item=space_spaceId to http://server/spaces/spaceId
- spacetype has been replaced by spaceType
- The values available for spaceType are: 'ils' (since we are obtaining the parameters of an ILS)
- The values available for metadata.type are: 'ils', 'Orientation', 'Conceptualisation', 'Investigation', 'Conclusion', 'Discussion', 'About', 'Vault' If a user changes the title of a phase, it will not be reflected in the "metadata.type". In case of new phases, no "metadata.type" will be provided.
- The values available for visibilityLevel are: 'public' or 'private' ('hidden' not supported)
Returns the type of the current phase.
callback(result): a callback function to handle the returned result
result: a String object containing the name of the phase the app is running in
Result example on success (for both old and new Graasp):
"Orientation"
Result example on failure:
{
"error": "cannot get the parent inquiry phase"
}
Returns the Vault space of the current Ils in the callback.
callback(result): a callback function to handle the returned result
result: a JSON object containing the Vault space properties
Result example on success:
{
"created": "2014-10-21T16:21:40.499Z",
"description": "Description given by the user",
"displayName": "Vault",
"id": "544688141b3e3f0000415709",
"metadata": {"type":"Vault"},
"parentId": "544688141b3e3f00004156c7",
"parentType": "@space",
"profileUrl": "http://graasp.eu/spaces/544688141b3e3f0000415709",
"spaceType": "folder",
"updated": "2014-10-21T16:21:40.503Z",
"visibilityLevel": "private"
}
Result example on failure:
{
"error": "cannot get the vault"
}
- New parameters have been included: created and content
- objectId is no longer included. Nevertheless the same information can be obtained using the already existing id.
- data is no longer included. Nevertheless the same information can be obtained using content.
- The format for ids has been modified: from numeric to alfanumeric
- The format for the profileUrl has been modified: from http://server/#item=space_spaceId to http://server/spaces/spaceId
- spacetype has been replaced by spaceType
- The values available for spaceType are: 'ils' (since we are obtaining the parameters of an ILS)
- The values available for metadata.type are: 'ils', 'Orientation', 'Conceptualisation', 'Investigation', 'Conclusion', 'Discussion', 'About', 'Vault' If a user changes the title of a phase, it will not be reflected in the "metadata.type". In case of new phases, no "metadata.type" will be provided.
- The values available for visibilityLevel are: 'public' or 'private' ('hidden' not supported)
Returns all the resources in the Vault in the callback.
callback(result): a callback function to handle the returned result
result: an array of JSON objects, each JSON object containing properties of the respective resource in the Vault
Result example on success:
[
{
"created: "2014-10-21T17:30:50.737Z",
"description: "Text given by the user",
"displayName: "file1.pdf",
"id: "5446984a1b3e3f0000415be7",
"parentId: "544688141b3e3f0000415709",
"thumbnailUrl: "http://graasp.eu/pictures/5446984a1b3e3f0000415be7/medium_05d10ea50e54dd663fa9c22431deac46785d4326.jpg",
"updated: "2014-10-21T17:30:50.856Z",
"url: "http://graasp.eu/resources/5446984a1b3e3f0000415be7",
"visibilityLevel: "private"
},
{
"created: "2014-10-21T17:30:50.788Z",
"description: "Text given by the user",
"displayName: "file2.txt",
"id: "5446984a1b3e3f0000415beb",
"parentId: "544688141b3e3f0000415709",
"thumbnailUrl: ""http://graasp.eu/pictures/5446984a1b3e3f0000415beb/medium_aec0cfaca23086c925b36e38a3e3e84e5970592b.jpg"",
"updated: "2014-10-21T17:30:50.856Z",
"url: "http://graasp.eu/resources/5446984a1b3e3f0000415beb",
"visibilityLevel: "private"
}
]
Result example on failure:
{
"error": "cannot get the resources in the vault"
}
- New parameters have been included: created, description, visibilityLevel
- name is no longer included. Nevertheless the same information can be obtained using the already existing displayName.
- objectId is no longer included. Nevertheless the same information can be obtained using the already existing id.
- parentType in no longer included.
- The format for ids has been modified: from numeric to alphanumeric
- profileUrl has been replaced by url
- The format for the url has been modified: from "http://server/#item=asset_assetId" to "http://graasp.eu/resources/resourceId"
- The values available for visibilityLevel are: 'public' or 'private'
- No information is (yet) received regarding mimeType, metadata, data, and attachment
Returns the resource with the resourceId in the callback.
callback(result): a callback function to handle the returned result
result: a JSON object containing the properties of the resource references by resourceId
Result example on success:
{
"content": "",
"created": "2014-11-03T00:17:20.585Z",
"description": "",
"displayName": "test",
"id": "5456c9900c3acd201d083a70",
"metadata": {
"actor": {
* "displayName": "Chus",
* "id": "542f65a1ac1bb5a4b3af1452",
* "image": ,
* "objectType: "User",
* "url: "http://localhost:9091/users/542f65a1ac1bb5a4b3af1452"
}
"provider": {
* "displayName": "ils_lib",
* "id": "54567a3e0c3acd201d08378b",
* "url": "http://localhost:8000/spaces/54567a3e0c3acd201d08378b
}
"target": {
* "displayName": "test",
* "id": "5456cfce0c3acd201d083c42",
* "objectType": "Resource"
}
"mimeType": "application/octet-stream",
"parentId": "54567a3f0c3acd201d0837d1",
"updated": "2014-11-03T00:17:20.591Z",
"url": "http://localhost:8000/resources/5456c9900c3acd201d083a70",
"visibilityLevel": "public"
}
Result example on failure:
{
"error": "cannot get the resource"
}
createResource(resourceName: string, content: object, callback: function(result: object): void): object
Create a resource in the Vault, and returns the new resource just created.
resourceName example:
"example file"
content should be any JSON, see example below:
{
"concepts": [
{
"x": 297,
"y": 188,
"content": "energy",
"id": "7f800d79-cd66-2167-724c-6c1cda7abc5e",
"type": "ut_tools_conceptmapper_conceptSelector",
"colorClass": "ut_tools_conceptmapper_blue"
},
{
"x": 652,
"y": 238,
"content": "thermodynamic temperature",
"id": "a1ad6ace-c722-ffa9-f58e-b4169acdb4e3",
"type": "ut_tools_conceptmapper_conceptSelector",
"colorClass": "ut_tools_conceptmapper_blue"
}
],
"relations": [
{
"source": "7f800d79-cd66-2167-724c-6c1cda7abc5e",
"target": "a1ad6ace-c722-ffa9-f58e-b4169acdb4e3",
"id": "con_71",
"content": "influences"
}
]
}
callback(result): a callback function to handle the returned result
result: a JSON object representing the creating resource in the Vault
Result example on success:
{
content: "",
id: "546205da394af34a73631b59",
parentId: "54607f87c276f5e27d84b091",
updated: "2014-11-11T12:49:31.011Z",
created: "2014-11-11T12:49:30.989Z"…},
description: "",
displayName: "test",
parentId: "54607f87c276f5e27d84b091",
url: "http://graasp.eu/resources/546205da394af34a73631b59",
visibilityLevel: "private"
}
Result example on failure:
{
"error": "cannot create resource in the vault"
}
### How to Use This library relies on Jquery, so Jquery should be included in the widget headers before the use of this library. Below is an example of how to use the getIls API. For more information on how to use this library, please refer to the the demo widget: https://github.com/go-lab/ils/blob/master/demo/vault_demo_graaspeu.xml
//include jquery library in your widget source
<script type="text/javascript" src="http://graasp.epfl.ch/gadget/libs/jquery-1.8.0.min.js"></script>
//include the ILS library in your widget source
<script type="text/javascript" src="http://graasp.epfl.ch/ils_lib/main/ils_graaspeu.js"></script>
//example of calling the getCurrentUser api
ils.getCurrentUser(function(current_user){
// write your code here to use the current_user
// this line simply prints the current user's nickname
console.log(current_user);
});
//example of calling the getIls api
ils.getIls(function(ils_space){
// write your code here to use the ils_space
// this line simply prints the ILS space JSON representation
console.log(ils_space);
});
//example of calling readResource api
ils.readResource("5460812ec276f5e27d84b295", function(resource){
// write your code here to use the resource
// this line simply prints the returned resource's JSON representation
console.log(resource);
});
//example of calling createResource api
var example_content = {
"concepts": [
{
"x": 297,
"y": 188,
"content": "energy",
"id": "7f800d79-cd66-2167-724c-6c1cda7abc5e",
"type": "ut_tools_conceptmapper_conceptSelector",
"colorClass": "ut_tools_conceptmapper_blue"
},
{
"x": 652,
"y": 238,
"content": "thermodynamic temperature",
"id": "a1ad6ace-c722-ffa9-f58e-b4169acdb4e3",
"type": "ut_tools_conceptmapper_conceptSelector",
"colorClass": "ut_tools_conceptmapper_blue"
}
],
"relations": [
{
"source": "7f800d79-cd66-2167-724c-6c1cda7abc5e",
"target": "a1ad6ace-c722-ffa9-f58e-b4169acdb4e3",
"id": "con_71",
"content": "influences"
}
]
};
// create a resource in the Vault
ils.createResource("test", example_content, function(resource){
// write your code here to use the resource
// this line simply prints the created resource's JSON representation
console.log(resource);
});