CodeParadise

CodeParadise is the name of a framework and future platform. CodeParadise as framework allows developing web applications and Node.js applications in Smalltalk.

• Web applications are typically developed using WebComponents. WebComponents are written using HTML/CSS and Smalltalk. A web application has a server side and a client side environment which interact using websockets. Applications can be built using a Model View Presenter design.
• Node.js applications can typically use node:fs and node:http modules to create server and/or standaline applications. All code is written in Smalltalk by wrapping the Node.js modules.

The framework enables remote Smalltalk code execution in a JavaScript environment. This means you can run Smalltalk inside the web browser or inside a Node.js application and not be concerned with any JavaScript. A regular (but tiny) Smalltalk image runs on SqueakJS VM and replaces the use of JavaScript. This tiny image runs the same bytecode as a regular Pharo/Squeak/Cuis image, so no transpilation taking place. JavaScript callbacks and Promises are supported by using Smalltalk Blocks and 'proxied' objects. For web applications a VM plugin is present with Classes which wrap the browser DOM functionality. All DOM manipulation is done through Smalltalk code. Did I mention, no more use of JavaScript ;-). For more detail read the implementation docs.

A few online videos:

• to-do list tutorial walk through video - 47:47 minutes
• creating a Node.js application video - 10:22 minutes
• Zettelkasten example application video - 1:37 minutes
• short demo of debugger video - 1:07 minutes
• UK Smalltalk UG May 2022 demo - CodeParadise used in Expressive Systems by Object Guild
• UK Smalltalk UG August 2020 demo - CodeParadise
• short introduction video - 12:47 minutes (outdated)
• first two components link and button - 2:18 minutes (outdated)
• animated checkbox - 25 seconds (outdated)

See introduction for a more thorough explanation of CodeParadise as the future platform.

Getting started

Currently CodeParadise can only be used in a Pharo environment (P8 until P12 are supported). In the future other platforms like Cuis might be supported as well.

Getting started requires a few simple steps:

• Load CodeParadise
• Start HTTP and WebSocket server
• Start your browsers (or Node.js)!

Load CodeParadise

Loading CodeParadise can be done using:

Metacello new
  repository: 'github://ErikOnBike/CodeParadise';
  baseline: 'CodeParadise';
  load.

Depending on your image version it should also load the ClientEnvironment. If you run on a Pharo 8 or 9 environment, it should load the "pharo8" branch and otherwise just the "master" branch.

If you plan on developing Node.js applications please clone or copy the CP-Node repo. It only contains 2 'required' files cp-node.js and client-environment.image which you might copy as well.

Start HTTP and WebSocket Server

Thanks to Tim there is a menu 'Paradise' now in Pharo's menubar which allows starting the environment. First select 'Reset' from the 'Paradise' menu and then open one of the existing web applications through 'Open'. Some more explanation follows below for manually starting and stopping servers and applications.

Start your browsers

If all went well you should be able to fire up a number of browser tabs/pages and start using the example applications. Profit warning: the examples are still very limited, but should allow some insight in what is possible and allow you to play with it yourself.

The example applications can be reached using the following URLs:

• Introduction Presentation http://localhost:8080/static/app.html?presentation
• Building your first app http://localhost:8080/static/app.html?building-my-first-app [NEW]
• Shoelace Examples http://localhost:8080/static/app.html?Shoelace-Examples
• ChartJS Examples http://localhost:8080/static/app.html?ChartJS-Examples
• Counter Example http://localhost:8080/static/app.html?counter
• DOM Examples http://localhost:8080/static/app.html?DOM-Examples
• Component Examples http://localhost:8080/static/app.html?Component-Examples

A bigger example application is under development. It is a Zettelkasten application.

• Source code: repo (you will have to load it manually into CodeParadise)
• Short demonstration: video

Start your Node.js application

To start a Node.js application, execute the following from a CP-Node directory:

APP="http-server-example" SERVER_URL="ws://localhost:8080/io" node cp-node.js client-environment.image

(replace the APP environment variable with the identifier of your preferred application)

Manually starting and stopping

Besides the Paradise menu, you can also start and stop the ApplicationServer manually. The ApplicationServer provides a HTTP server (using Zinc HTTP Components) for a number of static files. You can use any other web server for this if you prefer.

The ApplicationServer also provides a WebSocket server (again using Zinc HTTP Components) for the interactive communication between ClientEnvironment and ServerEnvironment.

To start a server allowing incoming HTTP and WebSockets the following code has to be executed:

"Configure the usage of ZnWebSocket as MessageChannel"
CpMessageChannel environmentImplementation: CpZincWebSocketChannel.

"Register the example applications"
CpIntroductionPresentationWebApplication register.
CpMyFirstAppPresentationWebApplication register.
CpShoelaceExamplesWebApplication register.
CpChartJSExamplesWebApplication register.
CpCounterApplication register.
CpDomExamplesWebApplication register.
CpComponentExamplesWebApplication register.

"Start the HTTP and WeSocket servers (use the path where you stored the ClientEnvironment)"
CpApplicationServerStarter startUsingConfig: {
	#portNumber -> 8080 .
	#staticFilesDirectoryName -> (IceRepository directoryNamed: 'html' in: 'CP-ClientEnvironment').
	#clientErrorHandler -> self
} asDictionary.

"If you serve the static files using your own HTTP server, you can start the WebSocket server using:"
"CpApplicationServer newOnPort: 8080 path: '/io'."

The WebSocket server is listening on path /io by default (see example above). If you change this, please also update app.html (in the client environment) in which the path is hardcoded.

When you are done or want to reset the environment, the following code can be executed:

"Stop all server instances and applications"
ZnServer allSubInstances do: [ :each | (each port = 8080 and: [ each isRunning]) ifTrue: [ each stop ] ].
CpServerApplication allSubInstances do: [ :each | each stop ].
CpApplicationServer allInstances do: [ :each | each stop ].

"Unregister applications"
CpIntroductionPresentationWebApplication unregister.
CpMyFirstAppPresentationWebApplication unregister.
CpShoelaceExamplesWebApplication unregister.
CpChartJSExamplesWebApplication unregister.
CpCounterApplication unregister.
CpDomExamplesWebApplication unregister.
CpComponentExamplesWebApplication unregister.

"Garbage collect works better in triples ;-)"
Smalltalk garbageCollect.
Smalltalk garbageCollect.
Smalltalk garbageCollect.

Tips and troubleshooting

Tip: The server image keeps all sessions in memory at the moment (they never expire yet). So once in a while use the reset code above to clean up the sessions. Remember the sessions will also be saved in the image. So closing and reopening your image should bring you back the session and you can continu where you left off.

Resource not found

If you encounter any problems with connecting to the server, please check that no other web server is running on the port you are using/trying to use. If you have started a web server pointing to the wrong client environment, please first stop that instance. Otherwise you will keep on serving files from an empty or non-existing directory. Use the reset as described above to stop the server. You might want to check if all ZnServer instances are really stopped. Then create a new instance of the server.

Unknown classes

Once you have a client running and change code, the client environment might not know a class you are using. Please add this class by using the #beLoaded method (see existing senders to understand its usage). You might need to manually install it in a running environment (you have to find the corresponding server environment and use #addClass: to add it). Or reload the page in your browser. In some cases this is not enough, because of the order in which classes are installed. In such case you have to close the tab/page and open a new browser tab/page. In a future version this should not be necessary anymore.

Possible usage

The remote code execution capabilities of CodeParadise can be used to create WebApplications, Node.js applications, remote worker instances, mobile applications, etc.

To create WebApplications MVP (Model View Presenter) is implemented in the Presentation Example. It is based on WebComponents and more specifically it uses the HTML templates technology. The idea is to create a full set of components/widgets to create full featured web applications. All under the control of a Smalltalk application.

For mobile applications for example, the following could be done:

• load a ClientEnvironment with all application code (can be done dynamically and include all kinds of tests)
• execute code to remove the ClientEnvironment's Communicator (disconnecting it from the ServerEnvironment) and test code
• save the ClientEnvironment image (only supported for Pharo 10 and up)
• use the saved image stand-alone in a mobile application (combine with SqueakJS VM into single package)

Compatibility

The means of installing (Compiled) code in the ClientEnvironment is by sending the relevant bytecode. The current implementation assumes that both the ServerEnvironment and the ClientEnvironment share the same bytecode set. Since the ClientEnvironment is running on SqueakJS VM, only bytecode sets supported by SqueakJS VM are usable. Currently Pharo 8 up to 12 (and including) are supported. Active development is on P11 and at some point support for P8 and P9 will be dropped because of the non-standard process of creating the tiny Smalltalk image which runs in the browser. From P10 onwards this is standardized using TinyBootstrap.

There is no explicit list of supported browsers at the moment. Please use a recent browser version. If you have trouble using (the pre-Chrome based) Microsoft Edge, please consider switching to Chrome, Firefox or one of the derivatives.