Getting Started with “yFiles for HTML” for Programmers


Hello everyone this is Sebastian Müller from yWorks. I’m the technical lead here at yWorks and I would like to introduce you
to yFiles for HTML – our Javascript/HTML5 solution for diagramming in the
browser. First we start by going to our home page and choose the right product
which in this case is yFiles for HTML – – then click this nice orange button
over here to evaluate the program well, please enter your data and click the send button and you will receive an e-mail that will have a link included which allows
you to download the software. I’ve done this already. Here it is. You’ll get a zip file. Just extract it. and the first thing you should navigate your browser to is the README HTML file Here is the contents. It gives you a short
introduction to what’s inside the package: demos, tutorials, and of course
documentation and the library what you can do with it and how to contact us in case of any questions. Here you’ll find the extensive
source code applications. They can be run directly from the file system fully
interactive no server required any anyhow also there’s a link to the documentation
of course and the Getting Started chapter. The documentation contains an extensive Developer’s Guide with lots
lots of chapters and the full list of API’s available in yFiles. But let’s
see what’s in the package: Our recommendation for working with yFiles for HTML is using a modern IDE like WebStorm. WebStorm is available from
from JetBrains. It’s an extensive JavaScript IDE that you can evaluate and download from their home page.
I’ve have done this already: And here it is. Once WebStorm starts
up choose “Open”, navigate to the place where you extracted the evaluation version.
Click “ok” and wait for WebStorm to begin and parse all the files. There’s a lot of files inside the
directory and some of them aren’t necessarily important for WebStorm, so
we should tell WebStorm to ignore them for now. So the only things we are in interested
at the moment are the “demos” and “tutorials”. We select the other
directories and mark them as “excluded”. This makes me WebStorm ignore the files
inside those directories. There are very large javascript files inside and we
don’t need it to parse those files There’s a lot of demos inside this
directory structures there’s the full source code for those files included
there’s always an index HTML and the sources – the JavaScript sources. Now, the best thing about West but storm is the code completion. You get automatic code
completion and API documentation but you to configure WebStorm for this
accordingly. I’m going to show that to you. Go to the settings – libraries – here is the
“libraries” and we define a new library. Click on “add” – call it “yFiles for HTML”. It’s a custom library and it
has a definition file. It’s inside the “ide-support” directory called “yfiles-api.js”. That’s it! We can define it as “global” so we have it available for
other projects, too. Make sure it’s enabled and once we’ve hit ok WebStorm is going
to index that file and can now provide code completion for us so if we look at code
we’ll get documentation. Complete. Linked with all
information that’s available and of course completion. Now off to our first project!
I’m going to create a new directory: “myfirstapp” and I’m going to insert an HTML file – the “index” file, let’s call it “My First yFiles App” and now, what we need to do is first load the
CSS that is specific to yFiles. It’s a CSS file – stylesheet and it’s located in the “lib” directory
where everything is located now if I run the file I get an empty
screen. Of course, that’s boring so I also need to load the yFiles library. It’s
a javascript library and in this example we’re going to use and implementation of
the AMD loader “require.js” to load the files. So first thing we do is add the
loader itself: There’s an implementation part of the package: it’s called “require.js” and later on when the site is loaded we will tell the require implementation
where to find the libraries – so we need to specify the base URL relative to this file which is in the “lib”
directory. For this we’re going to step out one step out and
back into “lib”. This is where all the yFiles is located. Then we’re going
to tell it to require the complete yFiles package which is called “complete”. And to get to get this run we need to
include the license file. It’s part of the package so that’s in “resources” “demos” “resources” “license.js” and once it’s loaded – just log something. So it’s going to be in an empty page that loads the yFiles library and the
license file and let’s see what happens! Nothing – which is OK. Let’s take a look at the output of the console: We got “success”, so all of the library files have been
loaded already so now to get started yFiles is an HTML5 component and it
requires space on your HTMLpage and we do that by specifying a “div” element. We
give it a name “graphControl” and give it some a size so it’s a 600 pixels wide and 400 pixels height, give it some background so that we can see it. “lightgrey” is nice and now if we start the page with see a gray div over here but of course it’s not yet a graph control. It’s just the name of the “div” that is “graphControl”. So instead of logging some useless “success” over here we are now going
to actually create the graph control component so let’s declare a variable
see where it is. It’s in “yfiles.canvas.GraphControl” watch the completion and
it’s actually and the “div” called “graphControl”. Now that’s all! See what happens! Doesn’t look too much different but -well-
there is a watermark for the license, but if I click it nothing happens while
but as you can see if I turn the mouse wheel there’s some scroll bars over here so it’s it’s working already,
but still boring. Let’s see what we can do with the graph control. The graph control hosts a graph and with the graph I can tell it to create a
node. Let’s remember that node and I want to interact with it with the note, too, or with the graph so let’s tell it to use an input mode which handles user input to
actually edit the graph: “GraphEditorInputMode” … that’s basically it! See what happens: This is the node we created programmatically – I can zoom to it. But now, that I added the input mode I can select the
node, resize it, add more nodes to that, add connections, bends, move them around,
select, delete, etc. Cool! Now the best thing about yFiles is automatic layout. Let’s add this, too, to our example. We’ll add a simple button over here, “onclick” just execute our method “layout”. Call it “layout” – we need to define it that method somewhere. Since I’m just using the global “layout” over here and I’m in “function” scope I’m going to assign it to the global namespace and once we are in that
method, I can say “graphControl” and there’s this nice method “morphLayout”; I’m going to choose a layout algorithm: In this case I choose “organic”. I need to specify how
fast to morph it so I need to specify that duration and there’s “yfiles.system.TimeSpan” – 3 seconds and then we have an optional callback once it’s done just
ignore that for now we don’t need it and see what happens There is the button;now add the graph. Use the “duplicate” action to create a bigger graph.
Let’s see what happens: yeah, some nice animation – here it is! so of course there’s a huge API with yFiles and of course you’re going to make mistakes even though you have
code completion that tells you what parameters to pass, what types to use, you
are going to have to debug. For this there’s a great script that you should
always add to your application at the very first script that you should add for
debugging purposes. And let’s do that. The script – we add the source: it’s also in
“ide-support” and it’s called “yfiles-typeinfo.js”. and it adds runtime
type information and type checking to the application. So let’s see what
happens with this script enabled I can open the
console in the browser type “yfiles.debug” and “yfiles.debug” searches for a
“div” in the DOM named “graphControl”. It should be spelled like
this and this is just utility function that puts the graph control into global variables
called “gc” and the graph in “g”. So if I say “graph.clear()” I’m going to directly
manipulate the page. Now what do you do get by the runtime type information
script? For example if I make a mistake like I have…. say have two nodes first
node, createNode, second node. Great! You know that’s all fine now if I create
an edge for example and I forget the second parameter- of course this
always needs two parameters- let’s just try what happens… I got an exception that tells me there’s an
argument error: I should have passed it two arguments that have one. OK that’s nice,
but there’s more to that I can actually write “yfiles.help” which is a
utility function which allows me to see signatures and parameter information right
inside the browser console. There’s one usage where I can just pass it an instance or an object like for example
“yfiles.help” let’s give me more information about “createEdge” now it tells me it’s
an instance method on “yfiles.graph.IGraph” it’s called “createEdge”, takes two
parameters type “INode” and returns and “IEdge” and there’s also a link to the
documentation I can just click it over here and it loads in this case the
online information where i can get the full information about “createEdge”: so I
need to pass two nodes, ah, OK great! So let’s see what happens. Add the second one over here- let’s just
move them apart- so this is “n1” and “n2” – call the method I get the edge and no
errors being displayed anymore. Of course there’s a lot more you can do so be sure to check out the complete set of demo: back to the “README” to check out the complete set of demos: It’s a huge list and the source code tutorials especially
the Getting Started tutorial. It’s a number of steps that will introduce you to the
functionality of the API. Also be sure to take a look at the “Getting Started”
chapter in the developer’s guide. It shows how to set up your developer tools,
creating your first application and working with graphs. Thanks for watching! Enjoy your
evaluation and get back to our support team if you run into any issues!

Leave a Reply

Your email address will not be published. Required fields are marked *