PIXILAB Wiki

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
blocks:app-note:interacting-from-a-custom-web-page [2019-12-03 10:28]
max [Running the Example] 		blocks:app-note:interacting-from-a-custom-web-page [2023-08-01 21:07] (current)
admin [Installation]
Line 1: Line 1:
-====== Interacting with Blocks from a Custom Web Page ======+====== Advanced Interaction from a Custom Web Page ======
  
-This application note shows how your custom web page can talk to a Blocks server in various ways, including:+The application note titled "[[blocks:app-note:basic-interaction-from-a-custom-web-page|Basic Interaction from a Custom Web Page]]" desicribes a simple form of interaction (starting a named task). However, some applications ned a tighter integration, with direct read/write. and rea-ltime access to the inner workings of Blocls. This application note shows how such advanced integration can be accomplished, including:
  
-  * Making a simple HTTP request to Blocks, triggering a custom action on the server and passing a result back to the web page.+  * Making HTTP requests to Blocks, triggering a custom action on the server and passing a result back to the web page.
   * Setting any property in your Blocks system from the web page.   * Setting any property in your Blocks system from the web page.
   * Subscribing to property changes to keep your web page in the loop, regardless of how the property was changed.   * Subscribing to property changes to keep your web page in the loop, regardless of how the property was changed.
Line 13: Line 13:
 ===== Installation ===== ===== Installation =====
  
-Follow these steps to install this example on your own Blocks computer.+You need a computer with a running blocks server and a web browser to run this application note. Here's the {{ :blocks:app-note:custom-web-page:interactingfromcustomwebpage_v2.zip| Blocks root}} for this application note. See the the [[blocks:app-note:start|general setup section]] for details on downloading and installation. Once that general setup is done, follow these steps to run the application note:
  
-  - Install the enclosed {{:blocks:app-note:custom-web-page:pixilab-blocks-root.zip|Blocks root folder}} in your home directory (or use a PIXILAB-Blocks-config.yml file in your home directory to point at this root folder, as described [[blocks:server_configuration_file|here]]). 
   - Start Blocks.   - Start Blocks.
-  - Open the editor using the Admin button.+  - Open the Blocks editor using the Admin button. 
 +  - Log in using the proper credentials (default user name is //admin// and the password is //pixi//).
   - Open a second browser window to the same address as the editor window, but replace /edit/xxx with /spot. This opens a test spot display.   - Open a second browser window to the same address as the editor window, but replace /edit/xxx with /spot. This opens a test spot display.
   - Double-click TheSpot in the editor and reassign it to the ID shown in your separate spot window. This will be your test spot, controlled from the custom app.   - Double-click TheSpot in the editor and reassign it to the ID shown in your separate spot window. This will be your test spot, controlled from the custom app.
Line 86: Line 86:
 </code> </code>
  
-This call returns a pubSubPeer that manages the websocket connection to the server. The constructor call takes an optional callback function, in the example above called //onServerConnectionChange//, which in the example looks like this:+This call returns a pubSubPeer that manages the websocket connection to the server.  
 + 
 +The example shown above assumes that the custom web page is served by the Blocks server. If it is served from some other server, you must add a //second// parameter that is the URL for accessing the websocket endpoint on your Blocks server, like this; 
 + 
 +<code> 
 +const pubSubPeer = new PIXILAB_BLOCKS.PubSubPeer( 
 + onServerConnectionChange, 
 + "ws://<nameOrIp><:nonStandardPort>/rpc/pub-sub" 
 +); 
 +</code> 
 + 
 +Replace <nameOrIp> with the IP number or resolvable name to your Blocks server. If you're running on a non-standard port, append the port number separated by a colon. Hence, if your Blocks server rus on 10.1.0.10 using the standard port, the call would look like this: 
 + 
 +<code> 
 +const pubSubPeer = new PIXILAB_BLOCKS.PubSubPeer( 
 + onServerConnectionChange, 
 + "ws://10.1.0.10/rpc/pub-sub" 
 +); 
 +</code> 
 + 
 +The first parameter of the PubSubPeer constructor call is an optional callback function, in the example above called //onServerConnectionChange//, which in the sample code looks like this:
  
 <code> <code>
Line 112: Line 132:
 === pubSubPeer.add === === pubSubPeer.add ===
  
-This is similar to the //set// function, and takes the same two parameters. However, it may only be used with numeric values. You can use it to increase or decrease (by passing a negative value) a numeric property, such as a volume value. This is often simpler for such incremental adjustments than maintaining a subscription to the value in order to do the calculation on the client side based on the current value and then using the //set// function to change the value.+This is similar to the //set// function, and takes the same two parameters. When used with a numeric property, the value you specify will be added to the current value. Pass a negative value to subtract. When used with a string property, the value will be //appended// (concatenated) to the current string value.  
 + 
 +The //add// methid is often simpler for such incremental adjustments than maintaining a subscription to the value in order to do the calculation on the client side based on the current value and then using the //set// function to change the value.
  
  
Line 120: Line 142:
  
   - The full path to the property to subscribe to (see above).   - The full path to the property to subscribe to (see above).
-  - A callback function that will be called whenever the value of the property changes.+  - An object containing a single function named dataReceived, that will be called whenever the value of the property changes.
  
-The //subscribe// function returns the current value of the property if already known. If not, it returns //undefined// and you'll be notified by the callback function once the value is known.+The //subscribe// function returns the current value of the property if already known. If not, it returns //undefined// and you'll be notified by the dataReceived function being called once the value arrives.
  
 :!: You should pay attention to any initial value returned by the //subscribe// function, treating it the same way as any value change provided through the callback function. See main.js for an example of how this can be accomplished. :!: You should pay attention to any initial value returned by the //subscribe// function, treating it the same way as any value change provided through the callback function. See main.js for an example of how this can be accomplished.
Line 129: Line 151:
 === pubSubPeer.unsubscribe === === pubSubPeer.unsubscribe ===
  
-This function allows you to terminate any value subscription initiated by the //subscribe// fuynction if you're no longer interested in changes of a property. It takes the following parameters:+This function allows you to terminate any value subscription initiated by the //subscribe// function if you're no longer interested in changes of a property. It takes the following parameters:
  
   - The full path to the property to subscribe to (see above).   - The full path to the property to subscribe to (see above).
-  - The same callback function as passed to the //subscribe// function.+  - The very same object as passed to the //subscribe// function.
  
-The main.js example script does not use this function.+The main.js example shows how to use this function, as triggered by the //Unscubscribe// button.
  
  
Line 214: Line 236:
  
 Once these three steps are done, the promise is resolved with the name of the generated image file, now available under /public on the Blocks server. If any error occurs, the promise is instead rejected, passing an error code back as the HTTP POST request's result. Upon receiving the result, the custom web page's //main.js// script proceeds by displaying the resulting image. Note that the //fetch// function, called to make the HTTP request from the client side, also returns a //Promise// object, eventually resolved with the result of the operation once its //then// function is called. Once these three steps are done, the promise is resolved with the name of the generated image file, now available under /public on the Blocks server. If any error occurs, the promise is instead rejected, passing an error code back as the HTTP POST request's result. Upon receiving the result, the custom web page's //main.js// script proceeds by displaying the resulting image. Note that the //fetch// function, called to make the HTTP request from the client side, also returns a //Promise// object, eventually resolved with the result of the operation once its //then// function is called.
 +