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 <https://github.com/NetLogo/Tortoise/blob/master/compiler/js/src/main/scala/BrowserCompiler.scala>. 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 <https://github.com/NetLogo/Tortoise/blob/master/engine/src/main/coffee/engine/workspace.coffee>. 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 <https://github.com/NetLogo/Galapagos/blob/master/app/assets/javascripts/beak/session-lite.coffee#L94-L116>. 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 <https://github.com/NetLogo/Galapagos/blob/master/app/assets/javascripts/beak/tortoise.coffee> which creates the `BrowserCompiler` instance and turns a loaded nlogo source file into a `SessionLite` instance. The `SessionLite` <https://github.com/NetLogo/Galapagos/blob/master/app/assets/javascripts/beak/session-lite.coffee>is then the top-level piece that sets up and runs the model with the view. - Ractive.js <https://ractive.js.org/>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` <https://github.com/NetLogo/Galapagos/blob/master/app/assets/javascripts/beak/widgets/widget-controller.coffee>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` <https://github.com/NetLogo/Galapagos/blob/master/app/assets/javascripts/nettango/netlogo-model.coffee>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 <https://github.com/NetLogo/Galapagos/pull/411>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 On Tuesday, February 14, 2023 at 3:02:45 PM UTC-6 Doug Rocks-Macqueen wrote: > 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 > -- 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-devel+unsubscr...@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.
