NetLogo Web API?

[Doug Rocks-Macqueen]

Hi All,

Maybe I am just missing it but I can't seem to find any documentation on an API for NetLogo Web - at least for the JS side of it. Looking through the code and using developer tools in my browser I can sort of piece together bits and pieces like - ProcedurePrims, AgentModel, workspace, etc. Is there any documentation? I can't seem to find any on Git, a slight mention of some changes i.e. Procedure Definitions and Calling https://github.com/NetLogo/Tortoise/wiki/API-Change-Log  but that is about it.

If there is no documentation then even just some help being able to get a JS instance of NetLogo web, when the model is loaded in a browser, if such a thing exists. Or the instance for the the model inter-phase (buttons, sliders, etc.). This is for the standalone HTML export of an individual model, not anything on netlogoweb.org. From there I could probably inspect the class/object and work out the functions, etc. to make it do what I need.

Why it is needed - I am creating some tutorials on how to use NetLogo using JS tour software to take users through it (will be released under CC and OS so everyone is free to use them) and standalone exported NetLogo Models. It works well enough highlighting buttons, etc. It's when I get to a bit more complicated with more interaction e.g. trying to check a users input and compare it against the desired outcome. I have been able to get the CodeMirror instance which has helped for the code but the model inter-phase (buttons, sliders, etc.) is proving to be a bit more tricky. Is there a class for that which can be accessed from another JS script? This can sort of be done by accessing the DOM and checking for changes but it is a bit buggy and I have to account for lots of different use cases so being able to work directly with an API would be great.

Thank you,

Doug

[jeremy...@northwestern.edu]

Hey Doug,

So we don't have an officially documented API for NetLogo Web, unfortunately.  Part of that is up until now we haven't had many outside projects consuming NetLogo Web as a dependency.  Another part is that the API has been changing as we continue to bring NetLogo Web closer to feature parity with NetLogo desktop, especially with extensions, error handling, and internationalization.

To very briefly breakdown the architecture of NetLogo Web:

Tortoise contains the Compiler and Engine for NLW.

• The main entry point for the compiler is the `BrowserCompiler` class.  The compiler turns NetLogo code into JavaScript code.  It depends on the engine to do the work of running the simulation.
  
• The entry point for the engine is the `MiniWorkspace` class.  The compiler takes care of making sure everything the `MiniWorkspace` needs is setup and then passed in at runtime when the JS is executed.
  
• The runtime engine is stand-alone.  It can run models "headlessly" anywhere you run JS; we use Node.js to run models like that for testing, for instance.  If you want to actually run the model, you'll need to execute widgets (especially forever buttons), and then check the `Updater` to see what happened in the model since the last command was run.  As an example, here is how Galapagos runs the event loop for a NetLogo model.  Note that the loop runs continuously, executing widgets in order (where forever buttons will be run) and then updating the UI from those results.  Even if no buttons are pressed, the loop is running.
  

Galapagos contains the model view for NLW (called beak) as well as the pages and content you see on netlogoweb.org.  

• The view is technically standalone (all JavaScript), although at this point is pretty heavily integrated into NLW.
  
• The two most important places to check here are the `tortoise.coffee` file which creates the `BrowserCompiler` instance and turns a loaded nlogo source file into a `SessionLite` instance.  The `SessionLite` is then the top-level piece that sets up and runs the model with the view. 
• Ractive.js is the UI framework we use.  It's very simplistic, but it has just enough to do what we need - events, observables, computed values, and templating. 
  
• The `WidgetController` is also important, as it stores the widget state and UI state as the model is live in Ractive.js.  
• The NetTango Web application does "bundle" NetLogo Web, using NetLogo models as the underlying runtime for its blocks-based programming interface.  It has the `RactiveNetLogoModel` to try to isolate the code for creating and running a NetLogo model as a standalone UI component.  That might be a useful example to look at if you are setting up your own NetLogo Web models.
  

Most information you might be looking for is then found through the `session` or `workspace` globals.  For example, here is some code you might write to get the current global variables of a model:

```

const observer = workspace.world.observer
const globals = observer.varNames().map( (global) => observer.getGlobal(global) )
```

One thing I should add based on your described use case: there is a pull request in flight now to add UI events and basic data queries to NetLogo Web.  This would allow you to quite easily do things like listen for certain button presses and respond to them in whatever way you choose.  You can also run arbitrary NetLogo reporters to get data from the model, or get metadata about the model, too.

I hope to continue to expand the API of the events and query as time permits.  I'm also looking to make UI customization more easy to customize for embedding scenarios (disable authoring, disable just code tab, etc).  

I hope that's helpful!  And at some point (perhaps once the extension API is complete and error handling is more solid) I can use this as a basis for some real API docs.

Let me know if you have specific questions and I'll try to answer as I'm able.

-Jeremy

[Doug Rocks-Macqueen]

Thank you Jeremy,

That is quite helpful. I had been poking around the coffee scripts but was having trouble figuring out how it all connected together, especially SessionLite. I also saw that pull request which looks like it would be very helpful - though might be a little too late for when I need to get something out by. Might be able to use it in a version 2 of the tutorials (need to have something by the beginning of April).

For anyone who might be interested in doing something similar, it is possible to get the instances of Ractive and CodeMirror used by a standalone model:

const ractiveInstance = Ractive.getContext('#netlogo-model-container'),

         codeMirrorInstance = document.querySelector('.CodeMirror').CodeMirror;

With that you can see the observers of the Ractive instance and change them as you see fit. Same with CodeMirror. Between these two instances I have been able to check and manipulate the interphase as I need. Though my use case is pretty basic - adding or removing some widgets and code based on the different levels of a tutorial.

One quick followup question Jeremy -how did you all "gray" out areas of CodeMirror on the Beginner's Interactive NetLogo Dictionary. An example of what I mean on the or primative - https://ccl.northwestern.edu/netlogo/bind/primitive/or.html. I could see that being quite helpful for some of what I am doing.

Doug

--
You received this message because you are subscribed to a topic in the Google Groups "netlogo-devel" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/netlogo-devel/zKGEOZyG8aA/unsubscribe.
To unsubscribe from this group and all its topics, send an email to netlogo-deve...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/netlogo-devel/1b2418b7-e4db-4d99-8c90-04117b97f774n%40googlegroups.com.

[jeremy...@northwestern.edu]

One quick followup question Jeremy -how did you all "gray" out areas of CodeMirror on the Beginner's Interactive NetLogo Dictionary. An example of what I mean on the or primative - https://ccl.northwestern.edu/netlogo/bind/primitive/or.html. I could see that being quite helpful for some of what I am doing.

So the code for that is in `primitive.html` and it's pretty basic - it searches for matching non-comment lines that contain the primitive being described and marks anything else as disabled with a CSS class.   It then adds a popup alert when people modify those disabled lines.  That popup is the actual "disabling" mechanism, blocking the edits.

I should also point out that we've got big changes coming to the code editor sometime soon, including upgrading to CodeMirror 6, which will unfortunately likely break the work you're doing.  But of course you can always still with an older version of the codebase for your work.

I hope you're able to share what you build when you're done.  I'd love to see it.

-Jeremy

[John Chen]

I would caution against working too much over the current CodeMirror 5 editor in NLW - we are now working on a CM6 version of the editor, with a much more open API for external calls incl. features that allow you to examine the code in detail. 

The CM6 WIP is also open-sourced as a standalone repository so you might want to look at it as well.

--
You received this message because you are subscribed to the Google Groups "netlogo-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email to netlogo-deve...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/netlogo-devel/84f223ed-a54a-4c42-9096-9b86f70cd2den%40googlegroups.com.

[Doug Rocks-Macqueen]

Thank you both.

I had meant to ask about CodeMirror 6 but forgot so really glad you mentioned it. Given time constraints, the first version of the tutorials will likely be with CodeMirror5 - it is very minor what I am going:

 - this is the code you should add,

- here is a demo of it being "typed" into the code command (what I need the CodeMirror instance for),

- now you try.

but 6 will break it with how they change handling lines so later I will just have to make some changes. But changing of a 'demo' function shouldn't be too bad, between CodeMirror 5 and 6 (famous last words)

Thank you,

Doug

To view this discussion on the web visit https://groups.google.com/d/msgid/netlogo-devel/CAJ_UcvzkH_wsG%2BnFnm6hur7AcovA1WR8oTDCF5it9OTVb%3D-9bw%40mail.gmail.com.