UmlCanvas and its server counterpart Hosted UmlCanvas are great tools to put your UML diagrams online and share them with other people. But as with any new tool in your toolbox, beginning to use it is the hardest part.
This tutorial will walk you through the steps required to create and share your first UmlCanvas online. No downloads, nor special tools or registration of any kind are required. All you need is the same browser you are using now to read this tutorial.
So you have everything you need, let's get started.
It all starts with a topic you want to turn into a UML diagram. For this tutorial we'll take a simple UML diagram illustrating how you, UmlCanvas and Hosted UmlCanvas are related.
A UmlCanvas has an ID, a Name, a Description and of course the ADL Source code to render the UML diagram. It also is related to an Author. An Author has a Name and an Email address. Finally, Hosted UmlCanvas, contains a lot of UmlCanvas diagrams. There is more to it, but let's start with these basic properties.
Classes als have operations that allow us to access and modify the properties of the actual objects. UmlCanvas will allow us to Show in diffferent formats: as an HTML page, as a Script, JSON or simply as ADL. Hosted UmlCanvas allows us to Edit, Store and Retrieve a UmlCanvas.
Okay, that should do it, let's turn these requirements into a UmlCanvas diagram right now.
UmlCanvas is a Javascript library, which you can add to your HTML pages to render UmlCanvas-based UML diagrams on them. Any UmlCanvas-based diagram is also a complete editor in itself. So you can start editing any UmlCanvas-based diagram on the web.
But, we've also set up a blank editor for you. You can access it at http://hosted.umlcanvas.org/start. Just open the link in a new browser window or tab:
UmlCanvas currently allows you to use a textual representation of UML to describe the diagram. It is called Abstract Domain Language or ADL. We have a reference page on Using ADL and we will add more tutorial-style articles soon. Check the Documentation section to learn more about it.
The editor page you have now in front of you consists of two parts: the actual UmlCanvas on the left and the UmlCanvas Inspector on the right. By default, the Inspector shows you the Editor, which is a text field in which you can enter your ADL code.
The Inspector has a few other tabs you can access: the Properties form, a Console and an About box. We will introduce these as we go along.
The first thing we need to do is set up the actual diagram. To do this, copy the following piece of ADL code in the editor:
diagram myFirstUmlCanvas {
}
If you copied and pasted it directly in the Editor, you will have the impression that nothing happened. From the outside this is correct. You just defined a diagram with nothing on it. If you typed the code manually, you will have received feedback from the Inspector:
Below the Editor textfield is another textfield in which the Inspector will give you live feedback as you type. We know it currently might be a bit cryptic, but we're working on that to make it more and more useable. For now, as long as the error textfield is empty, you know you wrote valid ADL.
Without going into all the details, let's quickly introduce the basic concepts of ADL.
ADL is a hierarchical textual format consisting of so called constructs. Every construct has the same format:
[constructType] [constructName] {
}
First we have a constructType. In our example, we've used the diagram constructType. Next we give the construct a name, in our case it was MyFirstUmlCanvas. Next we can add child-constructs, which we enclose between curly braces { ... }. Child-constructs can again have children and so on.
And there you go. You know already enough about ADL to continue this tutorial.
Time to add the first class. Add the following piece of ADL construct as a child to the original diagram construct:
class UmlCanvas;
If you typed in the ADL code above, you will again notice the error feedback, until you add the final semi-colon (";"). Here we see another ADL concept. If a construct has no children, we could add opening and closing curly braces ("{ }"), but we can also simply use a semi-colon.
Now, in the meantime, on the lefthand side, UmlCanvas has rendered something:
Your first UmlCanvas-based class. Sweet, but the class is sitting there in the top-left corner and we have a big UmlCanvas to fill. So let's position the class somewhat more towards the middle. The UmlCanvas class will be the main element of our diagram. To do so, we add the following piece of ADL code in front of the class construct : [@165,120]. The resulting ADL code looks like this:
diagram myFirstUmlCanvas {
[@165,120]
class UmlCanvas;
}
And our class will be positioned at 165 pixels from the left and 120 pixels from the top. The [@ ... ] notation, is called an annotation in ADL and allows us to instruct the construct to behave in a certain way. If we pass it two numbers, divided by a comma, the construct will position itself at that location:
Now, although this is a nice way to layout our diagram, it surely isn't the most productive way. The ability to visually interact with UML diagrams is one of the major advantages of desktop CASE tools. Can't we do the same with UmlCanvas? Yes, of course, you can!
Go back to your editor and add +dynamic in front of the diagram construct. Nothing seems to have happened. Now, go to the UmlCanvas diagram and click on the class. Four light blue dots will appear around the class. Now, move and drag the class around and see how the ADL code in the editor is updated.
So, what did we just do? +dynamic is another way to modify the behavior of a construct. This feature is called a modifier and it comes in two flavors: +[modifierName] and +[modifierName]=[modifierValue]. The first, like the one we used in our example, is a short-cut for +dynamic=true and is called a switch modifier. It actually turns on an aspect of the diagram construct, which in this case turns the diagram in a dynamic and interactive element.
So now, you can position your class the way you like.
The goal of this tutorial was to get your first UmlCanvas diagram online, so let's move forward and add the remaining ADL code to complete the diagram. Here is the entire code in one go:
Diagram myFirstUmlCanvas +dynamic {
[@150,60]
class UmlCanvas {
Attribute ID : String;
Attribute name : String;
Attribute source : String;
Operation show {
Argument format : Format;
}
}
[@30,75]
class Author {
Attribute name : String;
Attribute email : String;
}
[@143,185]
class HostedUmlCanvas {
Operation edit {
Argument umlCanvas : UmlCanvas;
}
Operation store {
Argument umlCanvas : UmlCanvas;
}
Operation show {
Argument umlCanvas : UmlCanvas;
}
}
[@275,57]
enumeration Format +abstract {
Attribute HTML;
Attribute Script;
Attribute Gadget;
Attribute JSON;
Attribute ADL;
}
dependency UmlCanvasFormat {
client UmlCanvas : UmlCanvas;
supplier Format : Format;
}
association hostedUmlCanvas {
role hostedUmlCanvas : HostedUmlCanvas +composite;
role umlCanvas : UmlCanvas +navigable;
}
association author {
role umlCanvas : UmlCanvas +shared;
role author : Author;
}
}
And take a look at the result:
We're not going to discuss every newly introduced construct or modifier. With the basic understanding you have by now, most of them should be pretty clear.
And now it's time to share your diagram. Right above the editor textfield you find a toolbar with icons:
One of those icons should look familiar: a save icon. Go ahead, press it.
The inspector will jump to the second tab, containing properties. And by that red color, we know we should have entered something there.
If you want to save your diagram to Hosted UmlCanvas, you need to provide a minimal set of properties. So let's just do that:
Okay, let's hit the save toolbar button once more ...
We have been redirected to the Hosted UmlCanvas site and we are presented with our own diagram. We can now commit our work. Just press the button at the bottom.
And there you are. You diagram has been added to the diagrams hosted at Hosted UmlCanvas. Because you have submitted your diagram as an anonymous user, Hosted UmlCanvas has generated a unique identifier for your diagram: http://hosted.umlcanvas.org/cPIa7q3TM7. If you visit the link, Hosted UmlCanvas generates a HTML page with your diagram on it. This is the public page of your diagram:
On the right hand side, you are offered a few options to share this diagram. You can simply copy the code in the textfield behind the titles and paste them in the corresponding context. From the top to the bottom:
The HTML option allows you to embed the diagram in any HTML-based resource without any other dependencies. It's an all in one package. The code you can copy from here looks like this:
<script type="text/javascript"
src="http://hosted.umlcanvas.org/cPIa7q3TM7:script"></script>
<noscript>
<a target="_blank" href="http://hosted.umlcanvas.org/cPIa7q3TM7">Jump to the diagram...</a>
</noscript>
You can include this in any HTML-based context. If it allows the execution of Javascript, it will render the diagram, else it will show a link to the diagram page on Hosted UmlCanvas.
Google Wave is also an HTML resource, but it offers even more possibilities. You can also include your diagram in any wave. Just choose to include a gadget and enter the following URL : http://hosted.umlcanvas.org/cPIa7q3TM7:gadget
If you want to use the diagram information as a developer, we offer two formats to incorporate diagrams in your applications: JSON, the JavaScript Object Notation and our own ADL. the Abstract Domain Language.
The diagram you just created was created as an anonymous user. Hosted UmlCanvas generated an ID for you, which in itself is okay. But there is another drawback to anonymous diagrams: we only keep them for 24 hours on our servers, so while you can use the link to the diagram to send it to other people by mail, it will be gone after 24 hours.
To overcome these restrictions, you can request a free account. An account allows you to specify your own diagram ID and will keep the diagram online after the initial 24 hours. In the future more features and advantages will be added to registered accounts, so if you are ready to use UmlCanvas and Hosted UmlCanvas, you might want to Sign Up.
Happy diagramming ...
|
For Everyone |
For Developers |
Social Modeling |
News & Updates
|
