This tutorial shows you how to set up UmlCanvas for use on your own webpages and guides your through the process of creating your first UmlCanvas diagram.
On our download site you can find all distributions of UmlCanvas. To get up to speed quickly you can just hit the download link below and download the latest end-user distribution.
| Download UmlCanvas-latest.zip |
Once downloaded, unzip it and take a quick look at the contents.
Let's start by firing up your preferred editor and open an HTML page to which you want to add your first UML diagram.
In the distribution we provide you with a compressed all-in-one Javascript file, UmlCanvas.standalone.min.js, which is all you need. Copy this file into your webpage's directory and include it in the <HEAD> section of your page:
<head>
<script src="UmlCanvas.standalone.min.js"></script>
</head>
Your page is now UmlCanvas-enabled.
Time to add the HTML5 Canvas element. Put the following snippet in you HTML document:
<canvas id="myDiagram" width="300" height="200"></canvas>
<script>
UmlCanvas.on( "ready", function() {
var myManager = new UmlCanvas.Manager();
var myModel = myManager.setupModel("myDiagram");
var myDiagram = myModel.addDiagram();
var myClass = new UmlCanvas.Class({ name: "myClass" });
myClass.addAttribute({ name: "firstProperty", type: "String",
visibility: "private" });
myClass.addAttribute({ name: "secondProperty", type: "Integer",
visibility: "protected" });
myClass.addOperation({ name: "anOperation",
arguments: [ { name: "param1", type: "String" },
{ name: "param2", type: "Integer" } ] });
myDiagram.at(60,50).put(myClass);
myManager.startAll();
} );
</script>
Congratulations, you've just created your first UmlCanvas-based UML diagram.
Let's quickly take a look at the Javascript code we've just executed:
UmlCanvas exposes events to which we can react. Because it needs to do some initializations, we need to wait until it's ready. Therefore we wrap our code that creates the diagram in a function, which we pass to the on method:
<script>
UmlCanvas.on( "ready", function() {
// diagram creation code goes here
} );
</script>
Next, we need to create a Manager to manage our diagrams. UmlCanvas can manage multiple diagrams at the same time, so we need some central authority. The Manager then can set up a Model. A Model is a collection of diagrams that can be displayed on one HTML5 Canvas. So in a way, the HTML5 Canvas element is a Model. Once we have this Model, we add a Diagram, to which we can add our classes, properties, operations, etc. When we're ready adding elements to the diagram, we let the manager know and ask it to startAll.
var manager = new UmlCanvas.Manager();
var myModel = manager.setupModel("myDiagram");
var myDiagram = myModel.addDiagram();
// diagram creation code goes here
myManager.startAll();
I'm going to let you in on a little secret: Because these four line are very common, we're also providing a utility method that does all this for you. So you can replace these four lines by one single call to activate one single canvas element for one diagram:
var myDiagram = UmlCanvas.activate("myDiagram");
And then it's time to add the actual diagram information:
var myClass = new UmlCanvas.Class({ name: "myClass" });
myClass.addAttribute({ name: "firstProperty", type: "String",
visibility: "private" });
myClass.addAttribute({ name: "secondProperty", type: "Integer",
visibility: "protected" });
myClass.addOperation({ name: "anOperation",
arguments: [ { name: "param1", type: "String" },
{ name: "param2", type: "Integer" } ] });
myDiagram.at(60,50).put(myClass);
First we instantiate a UmlCanvas.Class, then on that class, we call addAttribute and addOperation to do exactly that. Notice that we always pass the arguments to methods as hashes, because many arguments are optional. The UmlCanvas API goes into greater detail on all these methods and arguments.
Finally we put the class on the diagram at a specific position.
NOTE: if you're using the shorthand activate method, remember to remove the startAll method to avoid getting errors, because you're no longer have a reference to the manager.
Using the Javascript API is not too bad and it allows very fine-grained control of UmlCanvas. Still, for day to day use, UmlCanvas offers a far more attractive way to describe UML diagrams, using a textual UML representation or Domain Specific Language, short DSL.
Go back to your editor and add class="UmlCanvas" to the canvas element:
<canvas id="myDiagram" width="300" height="200" class="UmlCanvas"></canvas>
Next, replace the Javascript part with the following HTML code:
<pre id="myDiagramSource" style="display:none;">
diagram myDiagram {
[@60,50]
class myClass {
+private property firstProperty : String;
+protected property secondProperty : Integer;
operation anOperation {
argument param1 : String;
argument param2 : Integer;
}
}
}
</pre>
Now refresh your HTML page and verify that the result is the same:
That's probably a lot easier on the eye than the Javascript code.
So what just happened? We replaced our Javascript code with a hidden pre element, containing a textual representation of the same diagram. The textual representation is a DSL or Domain Specific Language we have created, called ADL or Abstract Domain Language. We believe it's pretty straightforward and intuitive and hope you agree looking at the example above. You can read the reference on Using ADL.
So how does UmlCanvas do this ? In short: it scans your page for HTML5 canvas tags. If it finds such an element, it will look for a corresponding pre or textarea element with the same id and a suffix Source. If it finds such an element, it will load the ADL code inside it onto the canvas element, which by then is already turned into a real UmlCanvas.
There is a directory with examples included in the distribution that are waiting to be explored. Both the Javascript API and the DSL styles are used and they give you a taste of what is possible.
We invite you to also read the follow-up tutorial, Your First Hosted UmlCanvas which shows you how you can store your diagram in a central location and include that very same diagram in multiple locations.
We also have a document explaining all there is to know about the DSL we use. If you're ready to start creating diagrams using UmlCanvas, you'll want to learn how to use ADL.
|
For Everyone |
For Developers |
Social Modeling |
News & Updates
|
