Adapt the world's representation

The world's representation

The first step to adapt an existing PLM's universe to webPLM is to implement the new world's representation. In order to represent a world, we implemented the following workflow:

• The server convert and send the world's data to the client
• The client initializes its local model according to the received data
• The client draws the world representation from its local model

Convert the world's model into a unified format

The first step is to add conversion methods to transmit the world's data to the client. The unified format we have chosen is JSON. Remember that the client only need to draw the world, so don't put everything into the JSON result but only what is needed

• In https://github.com/BuggleInc/webPLM/tree/master/app/json/world, add <universe>WorldToJson
  • This object will implement methods to generate a JsonObject representing the world's state
  • You may want to look at Playframework's documentation about JSON to learn how to generate a JsonObject
• According to the universe, the entity may also contains needed data.
  • In this case, we also need to add in https://github.com/BuggleInc/webPLM/tree/master/app/json/entity the <universeEntity>ToJson object
  • As before, this object will implement methods to generate a JsonObject representing the entity
• In https://github.com/BuggleInc/webPLM/blob/master/app/json/world/WorldToJson.scala#L32-L59, add the case corresponding to the new supported universe

Implement the simplified model

We now need to implement the simplified client's model of the world:

• In https://github.com/BuggleInc/webPLM/tree/master/public/app/models/universe, create the <universe> directory
• Add <universe>world.factory.js into this directory
  • This file will contain the world's simplified model
  • The model's constructor will use the received json as parameter
  • The methods getEntity(), clone() and setState() are needed for now
  • You can copy TurtleWorld.setState() to implement the later

Implement the drawing method

• In the universe's directory, add <universe>worldview.factory.js
  • This service has to provide the method draw()
  • To implement draw(), you can use:
    • Canvas API
    • The DOM using HTML elements and CSS

Add the new universe to supported universes

Regenerate the PLM's jar file

We may need to add the lesson which use this new universe. In this case, we need to:

• Add the lesson to the list of enabled lessons
  • Just put its name into the list
• Update the PLM's jar used by webPLM
  • How to do is described in Setting up developer environment#modifying-the-webplm

Add new script files to the HTML

We need to reference in the HTML to make the new data models available. Just add the scripts to index.scala.html.

Handle the new type of world in ExerciseController

First, inject the new models in the controller by adding them to the directive $inject (exercise.controller.js#L8-L24) and to the constructor (exercise.controller.js#L26-L39). Be sure to respect the same order in both otherwise some nasty bugs are bound to appear!

All we need to do now is to edit https://github.com/BuggleInc/webPLM/blob/master/public/app/exercise/exercise.controller.js#L239-L259 to add the new universe's case. You need to set:

• exercise.tabs, the tabs which will allow the user to switch from the working world to the objective one
  • name is the label of the tab
  • worldKind is the kind of world which will be displayed. Two values are available:
    • current, the user's working copy
    • answer, the objective world
  • tabNumber, the tab's index
  • __, the function draw() used to represent this world
• exercise.drawFnct, the initial function draw() to use
• exercise.animationPlayerNeeded, if the component allowing to switch between state should be shown or not
• world, thedrawFnct world's model

And finally we need to initialize the drawing service used with draw():

• initCanvas(drawFnct);
• initDrawWithDOM(drawFnct);

Congratulations, the world will (or at least should) now be correctly displayed! To continue to adapt the universe to webPLM, you may want to take a look at Adapt the world's evolution.