Remotely Launching an Embedded Gruff and Sending It Commands

## 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:

- Download the actors-extended triples file from the following web page (toward the bottom of the page). This example sends custom commands to Gruff that are based on these particular triples.

      https://franz.com/agraph/gruff/download/

- Create a triple-store called actors-extended in the root directory of an AllegroGraph server, and load those triples into it. (If the triple-store has a different name, then edit this example file to set the variable repoName to the name of the triple-store.)
- Run that AllegroGraph server, typically at default port 10035. (If the Agraph server is running at a different port, then edit this example file to set the variable agServerPort to the port.)
- Run Gruff in server mode with a command line similar to the following. Typically you would run the Gruff that's contained in the AllegroGraph server, in the "gruff" subdirectory. (If Gruff is not going to be running on the same machine as the Agraph server, then first edit this example file to set the variable agServerMachine to the name of the machine where the Agraph server is running.)

    ./gruff -- -b yes -l no -x no -o 9009-9013 -t 0 -m 5 --launcher yes -g log.txt --file-to-publish embedding.html &

On Windows, use "gruff.exe" rather than "gruff".

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.