Embedding Gruff In a Web Page

Gruff can be embedded in any web page to let readers use Gruff on your web site. This file (embedding.html in the Gruff installation folder) explains how to set up a running example of this. This file also serves as the example web page itself. You can adapt its JavaScript code for use on your own web site.

Gruff needs to be running in a special "launcher" mode on a server machine that the web browser can reach. Then your web page can send a message to the Gruff server that tells it to launch another instance of Gruff for the reader to use in one area of your page.

Simply embedding Gruff allows the reader to use Gruff by itself as usual inside the web page. A more advanced feature is that your web application can also send custom commands to Gruff. For example, your application could derive a set of triples that it wants Gruff to display, and then send those triples to Gruff.

Your web page needs to include an HTML iframe where Gruff will be placed. Your page could start up Gruff when it loads, or it could have a link or button that does that if the reader so desires. The bottom of this example page has widgets and an iframe that demonstrate this. The "Run Gruff Below" button sends a message to the Gruff server that's running on a known machine and port, telling it to launch a personal instance of Gruff. The reply contains the port where that Gruff instance can be reached, and then the button's code tells the iframe to visit the same machine at that port to display Gruff. The drop-down list then sends commands to Gruff at that port to control it externally. See the JavaScript code in this page for details.

There are a few steps for setting up this example:

Once everything is set up, tell a web browser to visit machine:9009/embedding, where machine is the name of the machine where the Gruff server is running, such as hazel.mycompany.com, or simply hazel within a local area network. If Gruff is running on the same machine as the web browser that will display it, then this can be localhost.

That will display this example file in the web browser, using a URL that's created by the --file-to-publish command-line argument. (In a real-world case, your web page would take the place of this demo page, and you would not need to use the --file-to-publish option.)

After visting this page as machine:9009/embedding, the Run Gruff Below button near the bottom of this page will embed Gruff into the page.

Here are the meanings of the command line arguments above:

-b yes Runs Gruff in web browser mode rather than desktop mode.
-l no Avoids automatically displaying Gruff in a local web browser when the server starts up, because users will be connecting from their own web browsers.
-x no Avoids exiting the Gruff server when a client exits. This keeps the server running as multiple clients connect and disconnect (sometimes simultaneously), though it also means that you eventually need to use an operating system tool to end the Gruff server process.
-o 9009-9013 Runs the Gruff server at port 9009, and allows clients to run on ports 9009 through 9013.
-t 0 Starts up Gruff's HTTP server and makes it share Gruff's WebSockets port. This is what listens for commands that your web application sends to Gruff, and is not needed if you are simply embedding Gruff without sending it commands.
-m 5 Allows Gruff to serve as many as five clients at once.
--launcher yes Runs Gruff as a server that will run an instance of Gruff for each web browser client that requests one (up to a limit).
-g log.txt Writes a log file at log.txt in the Gruff folder for monitoring the usage of the server, such as when different users connect and disconnect.
--file-to-publish embedding.html Publishes this example file that lives in the Gruff directory, so that web browsers can connect to it at the machine where the Gruff server is running and at the specified port. One warning: If you exit the Gruff server, modify the file-to-publish, and start the Gruff server again (specifying the same file-to-publish), then visiting machine:9009/embedding again in your browser will likely display the previous version of the file-to-publish, even if you do this in a new browser tab. And it will have the previous behavior as well. This has confused the developer to no end. 8-) You will then need to use your browser's refresh command to force it to load the modified file-to-publish so that you can test your most recent changes.

Here are a couple more options that can be used to make Gruff look more like a part of your own application.

--custom-title "Our Graph Visualizations" Replaces the usual title bar text that mentions Gruff with your custom title.
--disable-menus Removes Gruff's menu bar and disables other interactive gestures, to restrict Gruff activity to the commands that your application sends. (This option does not take an argument.)


The rest of this page demonstrates the functionality that was described above. If you've done that setup (including visiting this page by telling a web browser to visit machine:9009/embedding), then the widgets below should now work.

Press the Run Gruff Below button to ask the Gruff server to run an instance of Gruff for this user. The JavaScript code in this example file will handle the reply from Gruff and display Gruff in the invisible iframe that's below the buttons. Then select the custom commands in the drop-down widget in the order that they are listed.

         

Responses to commands will appear here.