Configuration
This section describes how to configure the example page, shown below. The upper-region has controls for experimenting with the Tutorial API calls, and the lower region is an <iframe> hosting Posit Workbench.
Allow IFrame
For security reasons, Posit Workbench will not load inside a browser frame (such as an iframe) by default. You can modify this behavior by using the www-frame-origin option. See Frame origin for full details.
To enable the Tutorial API example page to host Posit Workbench on a non-production localhost server, do the following:
/etc/rstudio/rserver.conf
www-frame-origin=http://localhost:8080If the www-frame-origin option is set to same or any instead of a URI, you must add the following setting with the actual URI:
/etc/rstudio/rsession.conf
tutorial-api-client-origin=http://localhost:8080Enable API calls from host page
To enable calling the Tutorial APIs from the hosting page:
/etc/rstudio/rsession.conf
tutorial-api-enabled=1Enable callbacks from RStudio to host page
Workbench may optionally notify the hosting page of certain events using the JavaScript PostMessage mechanism.
The receiver is responsible for parsing, interpreting, and reacting to the value of the callbacks. Any JavaScript running in the context of the IDE iframe could do an arbitrary SendMessage to the parent (in addition to those being generated by the RStudio Pro IDE JavaScript). The host page should ensure the response string is valid JSON, and follows one of the patterns described in Tutorial API Callbacks.
To enable callbacks:
/etc/rstudio/rsession.conf
tutorial-api-parent-notify-enabled=1Disable Posit Workbench home page
The Tutorial API cannot be used to manipulate the Posit Workbench Home Page. To disable the home page:
/etc/rstudio/rserver.conf
server-user-home-page=0The server-user-home-page setting is automatically forced on if Job Launcher sessions are enabled via launcher-sessions-enabled=true in /etc/rstudio/rserver.conf.
Disable multiple session support
Even with the Home Page disabled, a user can still open new sessions via Session / New Session which will open a new IDE instance outside of the host page. To prevent this:
/etc/rstudio/rserver.conf
server-multiple-sessions=0If multiple sessions are disabled, the Home Page is automatically turned off, so not necessary to include both settings.
The server-multiple-sessions setting is automatically forced on when Job Launcher sessions are enabled via launcher-sessions-enabled=true in /etc/rstudio/rserver.conf.
Serve the example page
Serve the folder /usr/lib/rstudio-server/extras/tutorial with a web server. For example, change to that directory in a terminal and run this command:
python2 -m SimpleHTTPServer 8080or
python3 -m http.server 8080Load http://localhost:8080/demo.htm in a web browser and you should see the page shown earlier.