Intro

This tutorial helps you create a simple application consisting of

  • an HTML page with a yFiles for HTML diagram representing an organization chart with data fetched from an ASP.Net MVC backend
  • an ASP.Net MVC website with a WebAPI representing a REST-ful interface to some data backend. We don’t describe or include any concrete database (access) layer but rather use some pseudo-random data generation to mimic this layer. A discussion of an ORM or webservice underneath the WebAPI is outside the scope of this tutorial.

The application shows an organization chart which upon clicking a node gives more information about the selected person.

What we'll create

The architecture is a simple client-service communication with the browser having an active role in fetching the data via ajax, i.e. the application is a single-page application (SPA). We do not delve however in the many ways one can build up an MVC structure on the client using one of the many JS frameworks out there (Angular in particular). The application is meant to be a jump-start showing how to use ASP.Net MVC together with yFiles.

Setting up the web API

Start by creating an ASP.Net Web Application

Creating the solution

Select the “Empty” project type but do include the “Web API” and “MVC” core references. You can also include unit tests and Azure publishing info if you wish but this is outside the scope of this overview.

Creating the PRoject

The project does not contain anything visible because we selected the empty project. If you would have selected e.g. the “MVC Project” earlier you would have seen plenty of stuff related to login, Bootstrap and more.

Go ahead and add a controller to the “Controller” folder

Creating the Controller

this opens up a selection and you should choose the “Web API 2 Controller – Empty”

Creating the WebAPI Controller

The other types articulate other functionality we don’t wish to go into here. Call the new controller “APIController”. This controller will contain the methods which will serve data via a REST-ful interface.

In a real-world application you would have some data access layer (DAL) or use some ORM (Entity Framework e.g.) to access your backend, but we will serve random data instead. To make the random data more than just arbitrary letters and numbers we’ll make use of the Faker.Net package. It creates random yet meaningful bits like addresses, company names and much more.

Go to the “Manage NuGet Packages” in the solution

Creating the solution

and install “Faker.Net” by searching for it in the “Online” drawer

Installing Faker

Add the following bits of code to the APIController

The Route attribute allows you to specify explicitly the way the web method is being accessed. By default the name of the method defines the REST address but the Route attribute gives more flexibility. You are free to use the default behavior however, all depends on the way you want to design the web API interface and how your overall architecture is designed. In any case, if you wish to use (like we do here) the Route attribute make sure the configuration is commented out like so

Things like CORS are important if you wish to use the webAPI outside the boundary of the ASP.Net website. More about all this can be found in the documentation.

If you press run/debug and browse to the “/API/GetRoot” address you will see that the web method returns the serialized Person object in XML format. The ASP.Net runtime transparently does this in function of what is being requested, XML being the default.

In function of yFiles for HTML we would rather have the data returned in JSON format since XML needs to be explicitly parsed in JavaScript while JSON is the more natural data dialect. This happens automatically as well and can easily be tested out as follows.

Add a new HTML file to the root of the solution, call it “index.html”. Add the following bits to it

 

Fetching WebAPI data

We use jQuery since it eases the client side development but if you venture into a large scale development you should carefully investigate options like Angular, Create, Backbone and the many other frameworks out there. While jQuery is fine for small things it does not enforces a solid client-side architecture and quickly turns your code in an unmaintainable heap. Bigger frameworks will help you to develop unit-tests, create responsive clients and much more.

In any case, if you now run the solution and browse to the HTML page you will see that on clicking the button the data is returned as JSON and can be directly used. The way ASP.Net does this is via the auto-included JSON.Net library (see the VS references). There are many ways this auto-serialization can be customized, see the JSON.Net documentation and the System.ComponentMode.DataAnnotations for more on this topic.

Fetching some data from the WebAPI

Setting up yFiles

The yFiles for HTML documentation gives ample information how to set up your solution but let’s summarize it again here for your convenience and to ensure that it works in the current ASP.Net context.

  • create a folder in VS called “lib” and drop therein the yFiles directory containing all the yFiles for HTML scripts

Creating the solution

  • ensure that the trial or purchased license (yWorks.yFilesHTML.DevelopmentLicense.js) also sits in this folder. Without this file you won’t be able to use the framework.
  • alter the header of the previously created index.html file like so

     

as well as the body so that a DIV tag can hold the yFiles diagramming control;

yFiles for HTML with ASP.Net MVC

 

 

 

This give you a basic presentation where the designDiv will hold the yFiles canvas and the app.js will contain the necessary JavaScript code defining the logic of your application.

In the lib\app.js file add the following basic code which we will elaborate later on. For now it just adds a single shape to the canvas.

The result of all this should be something like the following;

Creating the basic app

which obviously is nothing impressive but gives you a clean start for using yFiles and ASP.Net MVC. Regarding the “require” in the script above, see theasynchronous file and module loading topic in the yFiles documentation.

Fetching data and graph creation

Let’s combine the WebAPI data access and present the data in the diagram. We will create the following;

  • a standard organization chart with data fetched from the WebAPI (delivered by the ASP.Net MVC backend)
  • a side-panel presenting detailed information of a selected node (data taken again from the backend)

While the resulting app still remains fairly basic it does give you a fully functional yFiles frontend with ASP.Net backend which can serve as a jump-start for a more complex application with the same architecture.

Some more HTML and WebAPI

First add a few extra div panels to the index.html so that upon clicking a diagram node we’ll fetch additional data and present it in this panel;

yFiles for HTML with ASP.Net MVC

 

 

 

Details
First name:
Last name:

Second, augment the Person object we created earlier with an identifier and add a PersonAddress class which will hold the extra data we capture when clicking on a diagram node;

On the level of the WebAPI we add a few more methods

The Cache object used above is just a simple way to make sure that whenever we access a Person the same data is returned (within the same server session at least). For example, the Cache.GetPerson method amounts to

In a real-world situation you would replace the Cache with an internal data access or a service-oriented (SOA) mechanism.

The JavaScript application

On the level of JavaScript we need to add more structure to keep things ordered and the yFiles class framework helps tremendously here.

Let’s add a NodeModel which will hold the model or data bound to a diagram node;

You could mirror the Person class from ASP.Net (adding separate methods for FirstName, LastName etc.) but we wish to keep things simple here.

In a similar way, we’ll add a simple LinkModel holding the relational information

At this point we should note that we won’t make use of the yFiles GraphSource which offers a data-binding highway between data and nodes (an MVVM paradigm, if you prefer). The choice really depends on the overall type of application you wish to develop and the architecture. Our approach here is somewhat more conservative and allows us to highlight a few standard yFiles techniques which are somewhat ‘hidden’ in the GraphSource class.

In order to make the NodeModel and LinkModel accessible you need to export them from the OrgChart namespace

The behavior of the yFiles graph control can be fine-tuned GraphEditorInputMode and we’ll disable, among other things, the creation of new nodes upon clicking the canvas;

This behavior should be set immediately after creating the graph control in the App constructor. We’ll also add snapping and some node defaults;

The design template above is a bit special in the sense that it sits between HTML and JavaScript. You need to define the visual template inside the HTML like so

See the styling and templates topic in the documentation for the many ways in which you can customize the appearance of nodes and links.

The all-crucial AddNode method is really a wrap around the yFiles createNode method with additionally binding the NodeModel to the tag

The tag binds the model to the diagram node and we use some utility methods to go from the node object to the model

In the code you will find a similar method for the link. To connect two nodes we wrap the createEdge method

which allows us to refer to the Id of the underlying model rather than to a yFiles node instance.

Finally, after the graph is altered or created we want to layout the graph and, here again, yFiles offers a wealth of possibilities and customizations. We’ll use the hierarchical layout we delivers a tree-like result but also works if the graph is not a true tree (i.e. there are cycles in the graph);

At this point all is in place to create and effectively do what we initially set out to do. So, let fetch the GetRoot from the WebAPI as we did earlier and add a diagram node for it

The reason that we define that is because of the closure and the fact that the then promise runs asynchronously in its own context. Using this inside the then-function would not access the App class.

If you run the application and browse to the index.html page you should see something similar to this (the name is randomly generated and likely different on restarting the server process);

Showing server-side data

Displaying a hierarchy

Obviously we want more than just a single node and need to fetch a hierarchy from the WebAPI and there are various ways one can implement this. The easiest way is probably as follows, define server-side objects;

which captures the set of nodes and the set of links separately. Another way would be to use and adjacency list or alike. Since we don’t have a real relational structure in the backend we’ll have to construct a random tree. Here as well, there are plenty of tricks and we’ll use the following

This basically adds random nodes to previously created nodes and ensuring that the degree of the parent-node and the total node-count are not surpassed. Note that the web method has a few optional parameters and you can play with it for different results.

On the JavaScript side we need little chances to display this hierarchy. We simply loop over the returned nodes and links;

The resulting diagram is something like the picture below.

Showing server-side hierarchy

Now, for the final bit related to clicking the nodes and showing the details in the side-panel.

Upon click the node we’ll use once more a (combined) async ajax call

the only yFiles note here if the conversion of the node object to the underlying NodeModel via the GetItem method. From the point on that you have a reference to the id you can fetch the data and handle things in a standard jQuery fashion

Upon clicking a node you will now see something like this

Showing node details

A note about architecture and security

The application we developed so far is a basic client-server setup with the client having an active role in fetching all the data. That is, data is never pushed to the browser. In a push scenario one would initially do some data access prior to sending the HTML rather than letting AJAX do the work. This would however mean that the data is contained in the HTML and not dynamically updated (through user interactions). For each interaction the server would get the data and send it along with a new page. While this scenario has the advantage that there is not data-hotline (and thus potential security issues) between the browser and the WebAPI it does compromise the user-experience.

The created WebAPI serves data to the active client but can also be used by any other type of client. That is, you can bind a Java or .Net desktop client to it, there is nothing particularly browser-oriented about the WebAPI. It serves XML, JSON or other serialization types in function of what is requested.

The WebAPI can be hosted separately from the page-serving server but you should be aware in this case of default security mechanisms in place which typically prevent so-called cross-site scripting (XSS) and cross-origin resource sharing (CORS).

The data in our case are just some pseudo-random bits but in a real-world scenario you would put some data access layer underneath the WebAPI. This could be an ORM (Entity Framework or Hibernate e.g.) or access to another internal service. In addition, one would normally also have an authentication mechanism in place prior to accessing the application. ASP.Net offers plenty of good stuff to bind to OAuth or OpenID. On an enterprise level, one would bind the application to some active directory authentication or single-sign on.

References