-
Notifications
You must be signed in to change notification settings - Fork 45
NetTango Builder
The goal of the NetTango Builder is to make it easy to create stand-alone HTML pages that combine the NetTango block system and a NetLogo model to allow coding with NetLogo using blocks.
The intended workflow is:
- Choose a NetLogo model from the models library or import your own and update it for a block-based interaction.
- Create one or more block workspaces that will hold your domain-specific block definitions.
- Create blocks inside each your workspaces to allow interaction with the model.
- A critical part here is defining procedure blocks. These will be the bridges between the NetLogo model and the NetTango blocks.
- Update the NetLogo model code to use the procedure blocks you have added to NetTango.
- Test and tweak until it's ready.
- You then have two options to share you work:
- Export as an HTML page, post it somewhere, and use! It's totally self-contained.
- Export the NetTango project file, post it somewhere, and hot-link to it!
For a detailed breakdown of the process, check out this in-depth NetTango Ants tutorial or this older NetTango Builder tutorial.
-
Files - opens the file operations menu:
- Clear Model and Spaces - everything will be gone, and you'll have a blank slate to start from. Note, if you hit this on accident (even though it confirms), you can reload the page and you'll be back at the last point before you saved or exported.
- Import NetLogo model - imports a NetLogo model file to use as the base for the project.
- Choose NetLogo library model - selects a NetLogo library model to use as the base for the project.
- Import NetTango project - imports a file created with the Export NetTango project button.
- Export NetTango project - exports the NetLogo model and NetTango workspaces into a text file so you can do whatever you'd like with it - keep it in a better storage area, share it with someone else, use it on a different computer. You can also post it online and hot-link to it for use without exporting the static HTML file. Also saves your work to local storage.
- Export standalone HTML file - creates a standalone HTML page that contains the NetLogo model, the NetTango spaces, and the visual tweaks ready to use. Also saves your work to local storage.
- Preview standalone HTML page - opens the current model in play mode display, so you can see how it will appear once exported.
- Undo - Undoes the last change to the project.
- Redo - Redoes the last undone change to the project.
- Options... - opens the options for the model, including visual style options for the NetLogo model and block colors
- Add New Block Space - adds a new, separate block workspace. Multiple block workspaces can be used to separate logical content - Sheep from Wolves, Setup from Actions, whatever is appropriate to the model.
- Help - Links to this document and the NetTango tutorial.
There is an Add Block button that will let you add a NetTango block definition to a workspace (hit Add New Block Space to get a workspace if you don't have any). Because block definitions are a little complicated, we've included a bunch of pre-sets that should make things easier. The "Basics" are the least-specific, so will require the most input to be usable. The others should be more specific and ready-to-go with minimal edits, but they're also good starting points if you have a similar code block in mind.
In the Options... form, there are a bunch of pre-built visual tweaks you can apply.
The checkbox options are hopefully self-explanatory by name, and checking the box means they'll be applied to the exported HTML file. In the NetTango Builder, some of these do not hide elements as they would in the NetTango Player - since you may want to edit code in the code tab or unlock authoring mode while setting up your model. Instead they provide a visual cue that they will be invisible in the result by getting "grayer" while you're building.
You can also set block color and font globally for your blocks. These styles will apply to any block that doesn't have its own style settings. You can also click the Remove existing styles from all blocks to clear any styles on blocks in your model, and they'll go back to using the global block styles instead.
There is also an option to add CSS you'd like included in the exported HTML in the Extra CSS to include text area. This requires knowing how to find the right HTML classes to apply the CSS to using the web developer console, but it's not too hard.
If there is some feature not yet available or a change that's not possible in the NetTango Builder, you may be able to handle it by directly editing the NetTango block workspace JSON. Each block workspace contains the exact Block Definition JSON that is used by NetTango; it's updated as you work. For a manual edit, I recommend copying the JSON into a nice text editor, modifying it there, and then pasting the results back in. Then hit the Apply JSON to Space button and you should see the updates applied.
Hit the Load WSP Testing Defaults button at the bottom to load up a pre-made version of Wolf-Sheep Predation for NetTango. It includes some example blocks to give you an idea of how things work. Make sure to check how the procedures are defined and used in the code tab of the model.
The simplest way to share a NetTango Builder model is to use the Files > Export standalone HTML file button to save a standalone HTML file with the model and all needed code to run. You can post that HTML file on a web site and include it in other web pages. The upsides to using this method are that it's very simple and the model will always continue work as-is (barring any web browser changes). The downside to this method is that the exported pages are typically very large, since they include all the code need to run both NetLogo Web and NetTango. If you're going to be presenting many NetTango models, this can be slow even with fast internet connections.
The other way to share a NetTango Builder model is by hot-linking to the NetTango JSON file that you exported with the Files > Export NetTango JSON file menu item. You can then post this file on a website, and link the NetLogo Web site to it in order to run it. The NetTango model files are relatively small, and the NetLogo Web and NetTango code is typically cached by web browsers, which greatly reduces time to get things compiled and running.
- To share for editing, use
https://netlogoweb.org/nettango-builder?netTangoModel=$LINK_TO_YOUR_MODEL - To share in play mode without editing features, use
https://netlogoweb.org/nettango-player?playMode=true&netTangoModel=$LINK_TO_YOUR_MODEL.
Here is an example linking to the final model from the tutorial:
- For editing: http://netlogoweb.org/nettango-builder?netTangoModel=https://raw.githubusercontent.com/wiki/NetLogo/Galapagos/resources/Slime-tutorial_final.ntjson
- For playing: http://netlogoweb.org/nettango-player?playMode=true&netTangoModel=https://raw.githubusercontent.com/wiki/NetLogo/Galapagos/resources/Slime-tutorial_final.ntjson
Whatever site you host your NetTango model at must allow cross-origin resource sharing. More tips for setting this up for your model host are in the the docs for sharing models on NetLogo Web.
The development workflow for the NetTango Builder is similar to working on Galapagos in general. The Builder contains the UI code for creating and changing blocks, and submitting them to the NetTango core library. That library contains the code to create the drag-and-drop block workspaces, as well as to generate the NetLogo code from any program chains in a workspace.
If you need to make changes to the core NetTango library, you can see the directions in the nettango-package.sh script for how to quickly test your work out in Galapagos.
To enable debug mode in the production or staging environments for the NetTango Builder, simply open a web console and enter netTango.setDebugMode(true). This will log to the devel console the generated NetLogo code and attribute variable updates to see how the code is being rewritten directly. Debug mode is enabled by default when working with a local development environment.
The NetTango Builder is not yet a production-quality application, and numerous improvements are already envisioned. This list is not comprehensive and there are many more suggestions we're tracking, but it is presented to give an idea of the larger items the team is already thinking about.
- More interactivity for editing blocks such as dragging them to different locations in the block menu.
- Some direct support for creating and updating variables with blocks, both global and local.
- Better support for the expression editor, allow it to do more interest things including interacting with variables.
- Add a way to include sounds for block actions.