Hosted Groupworld API
The hosted version of Groupworld includes a control panel which lets you easily configure your rooms, manage users, and control the server configuration.
URL Format
HTML5 Room Options
Methods
Diagnostics
Webpage Integration
TutorCruncher Integration
URL Format
The following base URL is used for the Groupworld conference room:
http://www.groupworld.net/mp/parse.cgi?filename=nc
Users using Chrome, Firefox and Edge are automatically redirected to the HTML5 client.
Or you can use the following URL for the HTML5 client (https is required for screen sharing and video):
https://www.groupworld.net/mp/parse.cgi?filename=ncjs
To display the math tools above the whiteboard, use this URL instead (or, use the show_math API option to use a button for the math features):
http://www.groupworld.net/mp/parse.cgi?filename=math
Users using Chrome and Firefox are automatically redirected to the HTML5 client.
Or to use the HTML5 client with math features:
http://www.groupworld.net/mp/parse.cgi?filename=mathjs
You can also embed the room into an iframe (see the control panel for sample iframe code), or copy the HTML code into your own web page for more control over integration.
URL Parameters
| inst_id | Your Groupworld installation id. REQUIRED |
| instance | The Groupworld room to use. Each room can have a separate group of users connected. Rooms are automatically created on-the-fly as soon as anyone connects to that room.REQUIRED |
| username | The username of the user |
| password | The password of the user (if you have configured usernames and passwords for your users in the control panel) |
| width | Optional width of the room in pixels. Use 100% to fill entire web page |
| height | Optional height of the room in pixels. Use 100% to fill entire web page |
| show_room_name | Set to true to display the room name at the top of the page |
| show_timer | Set to true to display a timer at the top of the page |
| timer_two_users | Set to true to only start the timer once at least two users are in the room. You must also set show_timer to true |
| janus | Set to true to use Janus Gateway for multi-party WebRTC with more than 2 users (if this is enabled, audio/video will be routed through our Janus media server rather than peer-to-peer). Note that the maximum number of users transmitting audio/video in a Janus room defaults to 6. Set new_videostrip.MAX_JANUS_WINDOWS if you wish to increase this |
| hide_playback | Set to true to hide the playback link below the room |
| newui | Set to false to use the classic user interface |
| no_pan_zoom | Set to true to disable all panning (scrolling) and zooming for the current user, including mouse-wheel scrolling |
| no_mousewheel_scroll | Set to true to disable mousewheel scrolling/zooming for the current user |
| hide_pages | Set to true to hide the page chooser at the bottom of the whiteboard for the current user |
| diag | Set to true to enable extended diagnostics in the server logfile, giving information about audio/video status, javascript errors, etc. |
| selftest | Set to true to perform a self-test before allowing the user to enter the room (but user can optionally quit the self-test). |
Simple URL Format
A simpler format for the conference room URLs is as follows:
https://www.groupworld.net/room/<installation id>/<room name>
e.g.:
https://www.groupworld.net/room/1/demo
URL parameters can be added, e.g.:
https://www.groupworld.net/room/1/demo?hide_playback=true
Or use the following URL format if you want to display the math tools at the top of the whiteboard:
https://www.groupworld.net/math/<installation id>/<room name>
Recording Playback
The following base URL is used to display the recordings for a particular room:
http://www.groupworld.net/mp/saved_sessions.cgi
Playback URL Parameters
| groupworld_id | Your Groupworld installation id. REQUIRED |
| instance | The Groupworld room (NOTE: this must match the instance that was used for the original session).REQUIRED |
| dir | Optional directory. |
| xml | Set to true to output data in xml format. |
| hide_title | Set to true to hide the title and filename at the top of the page |
| username | Optional username of the user |
| password | Optional password of the user (if you have configured usernames and passwords for your users in the control panel) |
| width | Optional width of the room in pixels. Use 100% to fill entire web page |
| height | Optional height of the room in pixels. Use 100% to fill entire web page |
Displaying Number of Users Connected
You can use the following URL to display the current number of users connected (across all your rooms). Place it inside an iframe to embed in your web page:
http://www.groupworld.net/mp/gwusers.cgi?inst_id=1
(replace 1 with your Groupworld installation ID, and add &brief=true to just print the number of users).
HTML5 Room Configuration
The hosted version of Groupworld provides a control panel, allowing you to create custom configurations for each room. In addition, the HTML5 client allows you to set these options via javascript. Note that you must set these options before calling groupworld.htmlgen(). Also, you must copy the HTML code into your own web page (you can't use the iframe). Bear in mind that if you configure a room via the control panel, those options will override any that you set using javascript calls. Also note that true and false values in the options[] arrays must be set as strings inside quotes.
Conference room options
Video-strip (audio/video) options
Whiteboard options
Chat options
Screen sharing options
Desmos options
Shared text editor options
| groupworld.htmlgen(width,height) | Generate the Groupworld HTML code, setting the room to a given size (use 100% to fill remaining space) |
| groupworld.startup(username, password, base, object, flags) | Connect to the Groupworld server with optional username and password. See example HTML code for an explanation of parameters. |
| groupworld.domain_lock_any_room | Set to true to allow users to enter any room if the domain_lock server option is set (otherwise users can only connect to rooms that have been manually created in the room editor) |
| new_whiteboard.logout_callback() | Logs off Groupworld and closes the network connection. |
| new_conference.options["multi_column"] | Set to "true" to have multiple video window columns (NOTE: you must also increase max_video_windows or max_janus_video_windows) |
| new_conference.options["video_on_right"] | Set to "true" to display the video windows to the right of the whiteboard |
| new_conference.options["chat_on_right"] | Set to "true" to create a chat window to the right of the whiteboard |
| new_conference.options["vertical"] | Set to "false" to display the video windows horizontally instead of vertically |
| new_conference.options["presenter_username"] | Optionally set this to the username of the presenter user. Only the presenter can transmit audio/video and draw on the whiteboard (but presenters can temporarily grant presenter status to another user via the "Grant Presenter" button, or via buttons in the video windows). If Janus and/or WebRTC has been enabled then all users can transmit audio/video by default, but not draw on the whiteboard unless the presenter enables it. It is recommended that you enable Janus Gateway when using presenter mode with more than 2 users, for better audio/video quality. Note that you must also set new_videostrip.options["presenter_username"] and new_whiteboard.options["presenter_username"]. The presenter username is not case sensitive |
| new_conference.options["presenter_check_left"] | If set to "true", the presenter_username is compared to the start of the user's name, e.g. if presenter_username="teacher" then users with name "teacher_bob" or "teacher_jane" would be given presenter status |
| new_conference.options["must_have_presenter"] | If set to "true" then users can only log in when a presenter is logged in (and users are kicked off when the presenter logs out) |
| new_conference.options["large_video"] | Set to "true" to enable large video windows |
| new_conference.options["video_width"] | Optionally set the video width in pixels (NOTE: you must also set this option in the new_videostrip object). It is recommended that you set the use_webrtc option to true when using large video windows |
| new_conference.options["video_height"] | Optionally set the video height in pixels (you must also set this option in the new_videostrip object) |
| new_conference.options["demo_time"] | If set, users are logged off after this number of seconds. (Used to create a demonstration room) |
| new_conference.options["default_framerate"] | Default video framerate (defaults to "variable", which means framerate increases when user is speaking). Increasing video framerate will result in increased bandwidth (see bandwidth usage). This option does not apply if using WebRTC |
| new_conference.options["recording_dir"] | Sets the directory used to store recordings when using automatic recording of every session (defaults to "recordings") |
| new_conference.options["use_instance_recording_dir"] | Set to "true" to append the instance name to the recording dir (e.g. "recordings/room1") when automatically recording every session |
| new_conference.options["recording_filename"] | Sets the filename used to store recordings when automatically recording every session (only takes effect if record_by_date is set to "false") |
| new_conference.options["ask_record"] | Set to "true" to ask user if they want to record the session (when automatically recording every session) |
| new_conference.options["record_session"] | Set to "true" to automatically record all sessions |
| new_conference.options["record_session_2_users"] | Set to "true" to automatically record all sessions once two users have logged in (make sure you set record_session to false) |
| new_conference.options["record_by_date"] | Set to "false" to record using instance name as filename instead of current date (when automatically recording every session) |
| new_conference.options["hide_videostrip"] | Set to "true" to hide entire video/audio strip |
| new_conference.options["keepalive"] | Set to "true" to send "keepalive" packets to the server and exit if we don't receive a response within a specified time (20 seconds). Can be useful in detecting lost connection more quickly if users have a bad internet connection |
| new_conference.options["start_time"] | Optional start time for the session. Users will not be permitted to log in before this time. Note that the time is client-side time. Append a 'Z' to the time to use UTC time, otherwise the user's local timezone will be used. (format: "HH:MM" or "YYYY-MM-DD HH:MM") |
| new_conference.options["end_time"] | Optional end time for the session. Users will not be logged off after this time. Note that the time is client-side time. Append a 'Z' to the time to use UTC time, otherwise the user's local timezone will be used. (format: "HH:MM" or "YYYY-MM-DD HH:MM") |
| new_conference.options["authorized_users"] | Optional comma separated list of users who are authorized to enter this room |
| new_videostrip.options["min_video_windows"] | Mininum video windows to display (not including user's own preview video window), even if there is insufficient room to display. Default 1 |
| new_videostrip.options["video_width"] | Optionally set the video width in pixels (NOTE: you must also set this option in the new_conference object) |
| new_videostrip.options["video_height"] | Optionally set the video height in pixels (you must also set this option in the new_conference object) |
| new_videostrip.options["max_video_windows"] | Maximum video windows to display (not including user's own preview video window). Default 2 |
| new_videostrip.options["presenter_username"] | See new_conference.options["presenter_username"] for details |
| new_videostrip.options["invisible_user"] | Optionally set this to the username of a user who will be invisible to other users. Note that you should also set new_whiteboard.options["invisible_user"] and chat.options["invisible_user"] options |
| new_videostrip.options["presenter_check_left"] | See new_conference.options["presenter_username"] for details |
| new_videostrip.options["picture_in_picture"] | Set to "true" to display small preview video inside other user's video window (for 2 users in room) |
| new_videostrip.options["chat_under_video"] | Set to "true" to display chat window underneath video windows |
| new_videostrip.options["hide_video"] | Set to "true" to disable video. See also new_conference.options["hide_videostrip"] |
| new_videostrip.options["hide_audio"] | Set to "true" to disable audio |
| new_videostrip.options["large_presenter_window"] | Set to "true" to have a large video window for the presenter (when the presenter_username option is used) and up to 4 small windows for the non-presenter users. You must have large_video set to "true" |
| new_videostrip.options["presenter_audio_all"] | Set to "true" to transmit audio for all users in presenter mode by default. Only applies when Janus Gateway is not being used |
| new_videostrip.options["janus_only_publish_presenter"] | Set to "true" to make it so that only the presenter's audio and video are transmitted when using Janus Gateway (if you want a large number of users with only one person transmitting audio/video and other users just receiving, i.e. one-to-many). The presenter has a "grant presenter" button allowing them to temporarily grant audio, video and whiteboard permissions to individual users |
| new_videostrip.options["non_presenter_av_control"] | Set to "true" to allow non-presenter users control over their own microphone and webcam when using Janus (normally only the presenter has control over everyone's webcam and microphone permissions) |
| new_videostrip.options["non_presenter_fullscreen_control"] | Set to "true" to display the full-screen icon for non-presenter users when using Janus. (Normally only the presenter sees the fullscreen icons, and it displays the selected user's video in fullscreen for all users). When this option is used, non-presenter users can see other users' video in fullscreen, but it does not affect other users |
| new_videostrip.options["dont_start_av"] | Set to "true" to prevent audio and video being enabled when the user logs in. You can call new_videostrip.start_av() to enable audio/video |
| new_videostrip.options["sync_fullscreen"] | Set to "true" to syncronize fullscreen video between users, so that when one user enters full-screen, the other user is also automatically entered into fullscreen video |
| new_videostrip.options["hide_audio_controls"] | Hides the audio controls (volume controls and auto-record box) |
| new_videostrip.options["multi_presenter"] | Set to "true" to allow multiple temporary presenter users when using the Grant Presenter button |
| new_videostrip.options["use_webrtc"] | Set to "true" to use WebRTC for high quality streaming video and audio. Note that WebRTC is only used when exactly two users are logged in, and only for the HTML5 client |
| new_videostrip.options["webrtc_video_width"] | Optionally set the preferred video capture width. Use this to set the maximum video size if you intend calling set_video_size() method in the future (otherwise video will be captured at the initial, lower resolution). This does not affect the size of the video windows as displayed in the user interface |
| new_videostrip.options["webrtc_video_height"] | Optionally set the preferred video capture height |
| new_videostrip.options["video_talking_user"] | Set to "true" to only display the video for the user who is currently talking |
| new_videostrip.options["auto_record"] | Set to "false" to make "auto transmit voice" off by default (so user's microphone is not transmitting by default) |
| new_videostrip.options["video_quality"] | Sets the jpeg quality of video frames, from 0 to 100 (default 65). Note that this has no effect when Janus or WebRTC is active (except for recordings). Also note that increasing quality will result in increased bandwidth |
| new_videostrip.options["show_auto_record"] | Set to "false" to hide the "Auto Transmit Voice" button |
| new_videostrip.options["warn_no_audio"] | Set to "false" to hide the warning that normally appears after 30 seconds if the browser has not been given permission to access the user's microphone |
| new_videostrip.options["video_off_by_default"] | Set to "true" to turn off video by default. Users can click on the icon in their video window to enable it |
| new_videostrip.options["audio_off_by_default"] | Set to "true" to turn off audio by default. Users can click on the icon in their video window to enable it |
| new_videostrip.LOW_VIDEO_FRAMERATE | When using the default "variable" framerate, this sets the framerate to use when the user is not speaking if WebRTC is not being used. Default 4.0 |
| new_videostrip.HIGH_VIDEO_FRAMERATE | When using the default "variable" framerate, this sets the framerate to use when the user is speaking if WebRTC is not being used. Default 8.0 |
| new_videostrip.WEBRTC_VIDEO_FRAMERATE | Sets the framerate used for video frames transmitted to server when WebRTC is being used. This is only used for recordings (as the main audio/video is transmitted peer-to-peer using WebRTC). Default is 4.0 |
| new_videostrip.MAX_JANUS_WINDOWS | When Janus Gateway has been enabled, this option sets the maximum number of Janus windows (not including the current user). Default is 5 |
| new_videostrip.JANUS_BITRATE | Sets the bitrate when using Janus Gateway (default 256000) |
| new_videostrip.JANUS_CODEC | Sets the codec when using Janus Gateway (default 'h264'). You can also use vp8 or vp9 |
| new_videostrip.max_video_bw | Optionally set the maximum WebRTC video bandwidth (in kilobits per second). Default is to let WebRTC automatically adjust bandwidth |
| new_videostrip.max_audio_bw | Optionally set the maximum WebRTC audio bandwidth (in kilobits per second). Default is to let WebRTC automatically adjust bandwidth |
| new_whiteboard.mouse_wheel_scroll | Set to false to disable mouse-wheel scrolling) |
| new_whiteboard.show_hover | Set to true to display username of user who drew item when hovering over drawing items) |
| new_whiteboard.load_all_pdf_pages | Set to false to prevent populating the page number dropdown with all pages of uploaded pdf/docx/pptx/odt file) |
| new_whiteboard.whiteboard_background_colour | The default whiteboard background colour (default "rgba(255,255,255,1.0)") |
| new_whiteboard.tool_background_colour | The default tools background colour (the space above and to the right of the whiteboard), in the classic user interface (default "rgb(230,230,230)") |
| new_whiteboard.options["default_size"] | The default text/pen size, from 1-10 (default 1) |
| new_whiteboard.options["default_tool"] | The default tool (31 = ellipse, 32 = filled ellipse, 33 = rectangles, 34 = filled rectangles, 35 = lines, 36 = freehand, 37 = text, 38 = flood fill, 39 = laser pointer, 40 = pan, 41 = ink dropper, 45 = eraser, 46 = select, 47 = lines with arrows, 50 = polygon, 51 = filled polygon, 73 = highlighter, 74 = dotted line, 103 = transparent ellipse, 104 = transparent rectangle, 105 = transparent polygon, 106 = smooth freehand line) |
| new_whiteboard.options["default_background"] | If set to the filename of an image that has been uploaded, will automatically load this image when the user connects if the whiteboard is blank |
| new_whiteboard.options["eraser_size"] | The default eraser size, from 1-255 (default 10) |
| new_whiteboard.options["use_scrollbars"] | Set to "false" to disable scrollbars |
| new_whiteboard.options["multiline_text_input"] | Set to "true" to enable a multi-line text input box for the whiteboard. (Include jquery UI in your HTML code to make the text input box draggable) |
| new_whiteboard.options["show_tools_at_top"] | Set to "true" to display the tool/colour/size selector at the top of the whiteboard |
| new_whiteboard.options["always_redraw_gridlines"] | Set to "true" to always redraw gridlines after user draws on the whiteboard |
| new_whiteboard.options["gridlines_per_page"] | Set to "true" to store the gridlines separately for each page (so you can have gridlines on and off in different pages) |
| new_whiteboard.options["zoom_and_pages_at_bottom"] | Set to "true" to display the zoom slider and page numbers in a separate bar underneath the whiteboard |
| new_whiteboard.options["display_num_users"] | Set to "false" to hide the "x other users" at the top of the whiteboard |
| new_whiteboard.options["presenter_username"] | See new_conference.options["presenter_username"] for details |
| new_whiteboard.options["non_presenter_access"] | Set to "true" to allow non-presenter users write access to the whiteboard by default |
| new_whiteboard.options["invisible_user"] | See new_videostrip.options["invisible_user"] for details |
| new_whiteboard.options["presenter_check_left"] | See new_conference.options["presenter_username"] for details |
| new_whiteboard.options["multi_user_pan"] | Set to "false" to disable synchronization of pan/zoom operations between users |
| new_whiteboard.options["draw_visible_area"] | Set to "true" to draw the visible screen areas of other users as a light blue outline |
| new_whiteboard.options["sync_pan_top_left"] | Set to "true" to make it so that the multi_user_pan option synchronizes the top-left of all users' whiteboard area (rather than the centre) |
| new_whiteboard.options["hide_zoom"] | Set to "true" to hide the pan/zoom icons |
| new_whiteboard.options["auto_zoom"] | Set to "true" to automatically zoom when another user draws outside the current visible area of the whiteboard, or when the whiteboard is resized |
| new_whiteboard.options["retain_zoom"] | Set to "true" to keep the existing pan/zoom level when moving to a new page or clearing the page |
| new_whiteboard.options["show_tour"] | Set to "true" to always display the tour screen (otherwise it only displays the first time a user connects) |
| new_whiteboard.options["show_math"] | Set to "true" to display the math tools icon. (If you prefer having all the math tools at the top of the page, use the https://www.groupworld.net/math/<installation id>/<room name> URL format) |
| new_whiteboard.options["show_trash"] | Set to "true" to display the trash icon on the main whiteboard window, at the bottom-left (in addition to displaying it at the top) |
| new_whiteboard.options["hide_invite"] | Set to "true" to hide the invite button |
| new_whiteboard.options["hide_help_button"] | Set to "true" to hide the help button |
| new_whiteboard.options["show_eraser"] | Set to "true" to display the eraser icon on the main whiteboard interface |
| new_whiteboard.options["upload_images_to_board"] | Set to "false" to not automatically display uploaded images/documents on the whiteboard |
| new_whiteboard.options["slideshow"] | Set to "true" to enable "slideshow" mode, where Prev/Next buttons cycle between all uploaded images. Ignored if multi_page is not set to "false" |
| new_whiteboard.options["multi_page"] | Set to "false" to disable multi-page functionality |
| new_whiteboard.options["constant_thickness"] | Set to "true" if you want lines/text to appear the same thickness/font-size irrespective of zoom level |
| new_whiteboard.options["centre_in_window"] | Set to "true" to centre jpg/png images in window |
| new_whiteboard.options["scale_to_fit"] | Set to "true" to scale down images to fit in whiteboard (to make both width and height fit), but only if image is larger than whiteboard |
| new_whiteboard.options["scale_to_fit_width"] | Set to "true" to scale images to fit to the width of the whiteboard (whether smaller or larger than the width) |
| new_whiteboard.options["show_filestore"] | Set to "true" to display the Filestore button, allowing users to upload/download files to a filestore on the server |
| new_whiteboard.options["ovals_from_centre"] | Set to "true" to draw ellipses from the centre rather than from the top-left corner |
| new_whiteboard.options["show_load"] | Set to "false" to hide the Load button |
| new_whiteboard.options["hide_flood_fill"] | Set to "true" to hide the Flood fill tool |
| new_whiteboard.options["show_insert_page"] | Set to "true" to display the Insert Page button |
| new_whiteboard.options["show_save"] | Set to "false" to hide the Save button |
| new_whiteboard.options["show_upload"] | Set to "false" to hide the Upload button |
| new_whiteboard.options["show_icons"] | Set to "true" to display the Icon Library button |
| new_whiteboard.options["show_share_video"] | Set to "true" to display the Share Video button |
| new_whiteboard.options["show_text_editor"] | Set to "true" to display the shared code/text editor button |
| new_whiteboard.options["show_disable_drawing"] | Set to "true" to display the Disable Drawing button. The user must have "disable interaction" permission set in the control panel |
| new_whiteboard.options["show_deskshare"] | Set to "true" to display the Desktop Sharing button |
| new_whiteboard.options["show_record"] | Set to "true" to display the Record button, if you want to give users the option to manually start recording a session |
| new_whiteboard.options["recording_dir"] | sets the directory used to store recordings, when user presses the Record button (defaults to "recordings") |
| new_whiteboard.options["show_poll"] | Set to "true" to display the Poll button |
| new_whiteboard.options["show_chat"] | Set to "false" to hide the Chat button |
| new_whiteboard.options["show_send_url"] | Set to "true" to display the Send URL button, to allow users to send a web page to other users |
| new_whiteboard.options["show_logout"] | Set to "true" to display the Logout button |
| new_whiteboard.options["show_breakout"] | Set to "true" to display the Breakout Room button, allowing users to invite other users into a separate breakout room |
| new_whiteboard.options["dont_clear_upload_doc"] | Set to "true" to prevent clearing all pages when uploading a document (instead it will be uploaded started at the next free page) |
| new_whiteboard.options["auto_open_upload_dialog"] | Set to "false" to prevent automatically opening the file chooser when the upload dialog box is opened |
| new_whiteboard.options["dont_clear_upload_pic"] | Set to "true" to prevent clearing the current page when an image is uploaded |
| new_whiteboard.options["movable_images"] | Set to "true" to allow uploaded images to be moved/deleted/resized/rotated using the select tool (normally only drag+dropped images can be manipulated) |
| new_whiteboard.options["keep_background_on_clear"] | Set to "true" to keep the current background image when clearing the current page. Not compatible with the movable_images option |
| new_whiteboard.options["display_drawing_user"] | Set to "false" to prevent displaying the drawing user's name beside their drawing actions |
| new_whiteboard.options["display_pointer_username"] | Set to "true" to display username next to pointer if display_drawing_user is enabled. Normally the drawing username is not displayed for the pointer tool |
| new_whiteboard.options["send_text_chars"] | Set to "false" to prevent sending each individual character as user is typing it (when using the text tool) |
| new_whiteboard.options["logo"] | Optional URL of a logo to be displayed in top-right corner of conference room menu bar |
| new_whiteboard.options["show_movement_pointer"] | Set to "true" to always display a laser pointer showing the position of the other user's mouse cursor |
| new_whiteboard.options["dot_pointer"] | Set to "true" to make the pointer tool display as a red dot instead of a crosshair |
| new_whiteboard.options["arrow_pointer"] | Set to "true" to make the pointer tool display as an arrow instead of a crosshair |
| new_whiteboard.options["no_pan_left_above"] | Set to "true" to prevent the user from being able to pan (scroll) above or to the left of the origin of the whiteboard (0,0) |
| new_whiteboard.options["limit_pan"] | Set to "true" to prevent the user from being able to pan (scroll) more than half the whiteboard width/height beyond the current whiteboard contents |
| new_whiteboard.options["persistent_ruler_protractor"] | Set to "true" to make the ruler and protractor remain on the whiteboard after lifting the mouse button. Instead, the ruler and protractor are removed from the whiteboard by clicking the protractor or ruler icon again |
| new_whiteboard.options["bezier_curves"] | Set to "true" to draw continuous freehand lines using bezier curves, for smoother freehand drawing |
| new_whiteboard.HELP_URL | Sets the URL of the help button |
| new_whiteboard.NEWUI_HELP_URL | Sets the URL of the help page |
| new_whiteboard.TOPBAR_HEIGHT | Sets the height in pixels of the top menu bar along the top of the whiteboard (default 38) |
| new_whiteboard.newui | Set to false to use the old user interface |
| new_whiteboard.newui_topbar | Set to false to remove the top menu bar (and have a hamburger menu icon instead) |
| new_whiteboard.use_background_canvas | Set to true to make the eraser just erase drawing marks but keep the background intact. |
| new_whiteboard.constructed | (Read-only). Will be set to true once the new_whiteboard object is fully constructed, and the API is ready to be used. |
| new_whiteboard.save_dir | Optionally set this to the directory to use for loading/saving/uploading files for the room. Defaults to the room name with "wb1" at the end. |
| chat.options["invisible_user"] | See new_videostrip.options["invisible_user"] for details |
| chat.options["chat_input_on_top"] | Set to true to move the chat input box to the top of the chat window |
| chat.options["put_up_hand"] | Set to "true" to add a hand button to the chat window. Non-presenter users (or users who don't have disable interaction permission) will see the hand button. When clicked, it sends a text notification to all admin/presenter users, and beeps |
| chat.options["show_chat_names"] | Set to "false" to not display usernames in the text chat (this is separate from the user list) |
| chat.options["popup_chat"] | Set to "true" to use a separate popup chat window, instead of one that overlaps the whiteboard |
| chat.options["allow_private_chat"] | Set to "false" to disable private chat / whispers. Exceptions: presenters can still use private chat, and users can still send private chats to the presenter |
| chat.options["store_chat"] | Set to "true" to store all chat, so that the entire chat history is displayed when a new user logs in |
| chat.options["log_chat"] | Set to "true" to log all chat to a file on the server (will be stored in the chatlogs/ directory) |
| chat.options["notify_logins"] | Set to "true" to notify all presenter (or users with disable interaction permission) admin users when anyone logs in |
| chat.options["presenter_username"] | If set, only the presenter can see the user list. See new_conference.options["presenter_username"] for details |
| chat.options["presenter_check_left"] | see new_conference.options["presenter_username"] for details |
| chat.options["presenter_chat_only"] | Set to "true" to make it so that only the presenter can send chat text |
| chat.options["presenter_userlist_only"] | Set to "false" to let everyone see the userlist in presenter mode (by default only the presenter can see everyone, and other users can only see the presenter) |
| chat.options["allow_file_transfer"] | Set to "true" to display a Send File button, allowing users to transmit files to each other |
| deskshare.updates_per_sec | Optionally set the screen sharing framerate (default is 2.0 frames per second) |
| deskshare.show_user_own_win | Set to true (without quotes) to make it so that users see their own shared screen/window inside the whiteboard (as other users do) |
| desmos.api_key | Sets the Desmos API key (required to use Desmos) |
| txted.using_redips | Set to false to make the shared text editor fill the entire whiteboard |
| tunnel.ask_reconnect | Set to true to ask user if they want to reconnect when they get disconnected from the server |
Methods
The following methods can be used to interact with Groupworld:
| groupworld.upload_file(filename, file, callback) | Uploads a file to the server. The filename is relative to the top-level filestore directory, the file itself should be a string containing the binary data (not base64 encoded), and the callback is called after uploading (you will probably want to call load_pic in your callback). You can pass new_whiteboard.upload_complete as the callback function, which waits for the first page of the image or document to be generated by the server, and loads it onto the whiteboard |
| new_whiteboard.save_as(filename) | Saves the current picture to the server, or downloads to the browser as pdf or image. By default the image is saved to the server in the custom Groupworld format, and can be loaded using the load_pic API. To save as image or pdf, just add .png, .jpg or .pdf to the filename (this will save to the browser instead of to the server) |
| new_whiteboard.load_pic(filename, x, y) | Loads a saved whiteboard state, or a jpg/png image from the server onto the whiteboard at the given co-ordinates (ignored if loading a saved whiteboard). By default the image is loaded from the current whiteboard's directory (new_whiteboard.save_dir, which defaults to the room name with "wb1" appended) unless the filename starts with a "/" |
| new_whiteboard.tool_callback(true, new_tool) | Changes the current drawing tool. Values: 31=ellipse, 32=filled ellipse, 33=rect, 34=filled rect, 35=line, 36=freehand, 37=text, 38=fill, 39=pointer, 40=pan, 41=eye dropper, 45=eraser, 46=select, 47=line with arrows, 50=polygon, 51=filled polygon, 73=highlighter, 74=dotted line, |
| new_whiteboard.colour_callback(true, new_colour) | Changes the current drawing colour. Values: 11=white, 12=red, 13=green, 14=blue, 15=pink, 16=yellow, 17=black, 18=grey, 19=magenta, 20=cyan, 21=brown |
| new_whiteboard.size_callback(true, new_size) | Changes the current line/font size. Values: 1=smallest, 10=largest |
| new_whiteboard.set_zoom(new_zoom) | Changes the current zoom (1.0 = 100%) |
| new_whiteboard.reset_pan_zoom() | Resets the current zoom to 100% and pans to the centre of the whiteboard |
| new_whiteboard.zoom_in() | Zooms in by a factor of 2.0 |
| new_whiteboard.zoom_out() | Zooms out by a factor of 2.0 |
| new_whiteboard.undo() | Undos the last drawing action |
| new_whiteboard.redo() | Redos the last drawing action |
| new_whiteboard.copy() | Copies the selected items to the clipboard |
| new_whiteboard.cut() | Cuts the selected items to the clipboard |
| new_whiteboard.paste() | Pastes from the clipboard |
| new_whiteboard.clear_selection() | Clears the current selection |
| new_whiteboard.load_callback() | Brings up the Load window |
| new_whiteboard.save_callback() | Brings up the Save window |
| new_whiteboard.upload_callback() | Brings up the Upload window |
| new_whiteboard.clear_callback() | Clears the current page, after confirming with user |
| new_whiteboard.clear_all_callback() | Clears all pages, after confirming with user |
| new_whiteboard.clear_all() | Clears all pages, without confirmation |
| new_whiteboard.set_page(new_page, send_to_server) | Changes the current page. Pass true as the second parameter to transmit the set-page to the server (otherwise it will only be visible by the current user) |
| new_whiteboard.insert_page(true) | Inserts a new blank page at the current position |
| new_videostrip.toggle_mute_microphone(is_on) | Mutes or unmutes the microphone (pass in false to mute) |
| new_videostrip.stop_av() | Stops audio/video |
| new_videostrip.start_av() | Starts audio/video again (after calling stop_av()) |
| new_videostrip.toggle_mute_speaker(is_on) | Mutes or unmutes the loudspeakers (pass in false to mute) |
| new_videostrip.toggle_video(is_on) | Enables or disbles transmission of the user's video (pass in false to disable) |
| new_videostrip.set_video_size(width, height) | Changes the size of the video windows, resizing the user interface as required (NOTE: this option can only be used after the Groupworld conference room has been fully constructed. If you want to set the default size of the video, use the video_width and video_height options instead) |
Webpage Integration
The simplest way of integrating Groupworld rooms into your web pages is to simply copy the iframe code provided in your control panel.
However, if you want to use the javascript API, you will need to copy the HTML code out of the iframe into your web page. You can then use the API to control room features. Additional features you can control by editing the HTML code include:
- Set the user's username by editing the following line of code:
var username = '';
- Set the room name by editing the following line of code:
var object = 'new_conference:newconf';
(the room name is the string after the colon. DO NOT change new_conference).
- Control who can enter the room by setting the authorized_users API option.
- Control what times the room is active by setting the start_time and end_time API options.
- Ensure that your HTML code can only be hosted from your domain by
setting the domain_lock option in the "Server Configuration" of your
control panel.
- You can also optionally create your own scheduling system (using php/mysql, ASP or similar server-side scripting) on your website, authenticate the user yourself, and then generate the Groupworld HTML code if the user is authorized to enter the room. See our example open source tutor scheduler.
Diagnostics
You can optionally capture diagnostics include room logins, WebRTC status, javascript errors, uploaded files, etc. Set:
groupworld.diag = true;
By default the diagnostics are logged to filestore/groupworld_client_log, but you can override groupworld.log_diag to capture the messages:
groupworld.log_diag = function(msg) {}
With the hosted Groupworld, you can simply add
&diag=true
to the room URL, and the diagnostics can be viewed in the server logfile.
Replacing Groupworld icons
We use Font Awesome for most of the user interface icons. You can replace any FA icon by using CSS such as the following (replace /images/tick.png with the url of your replacement icon, which ideally should be svg):
.fa-paste { background-size: contain; height: 30px; width: 30px; margin-bottom: 0px !important; margin-top: -5px !important; position: relative; top: 6px; background-repeat: no-repeat; background-image: url('/images/tick.png') }
.fa-paste:before { content: ""; }
To replace regular icons (non font awesome), you would simply use something like this:
#gridlines { content: url('/images/tick.png') }
Embedding the Groupworld self-test page
The Groupworld self-test wizard allows users to test their microphone and camera before entering the Groupworld room. You can embed the self-test page in your own web page by using the following code:
<iframe allow="microphone; camera" width=640 height=500 src="https://www.groupworld.net/mp/parse.cgi?filename=selftest.html" style="border: 0"></iframe>
On-the-fly Room Creation
If you have copied the Groupworld HTML code into your own web page, you can create new rooms automatically simply by changing the room name in the HTML code (see Webpage Integration section above). Note, however, that some of the default options are different from the default room parameters you get when you manually create room in the hosted Groupworld control panel. (This is because we have changed the default room parameters over the years, but we never change the actual defaults in the javascript code). Here are the default parameters we use when creating a new room:
new_whiteboard.newui = true; new_whiteboard.options['default_size'] = 3; new_whiteboard.options['eraser_size'] = 15; new_whiteboard.options['show_share_video'] = 'true'; new_videostrip.options['show_auto_record'] = 'false'; new_videostrip.options['use_webrtc'] = 'true'; new_whiteboard.options['multi_user_pan'] = 'false'; new_whiteboard.options['auto_zoom'] = 'true'; new_conference.options['use_instance_recording_dir'] = 'true'; new_whiteboard.options['use_scrollbars'] = 'false';
TutorCruncher Integration
Groupworld can be integrated with TutorCruncher, giving access to scheduling and payment processing. For details of how to integrate with TutorCruncher, see our video.
After integration, when a user clicks on the whiteboard in TutorCruncher, they will be directed to a Groupworld room with the name of the room set to the TutorCruncher appointment name, and the user's username is passed in to Groupworld from TutorCruncher.
When TutorCruncher is integrated with Groupworld, the integration URL is set to https://www.groupworld.net/mp/tutorcruncher.cgi in the SSO integration settings in TutorCruncher. You can add the following parameters to this url to change the integration behaviour:
| redir | You can optionally set redir=true to redirect users to a Groupworld room link. (By default users are just sent to a tutorcruncher.cgi link, with a token, so they cannot see the room url or their username in the url) |
| append_role | You can optionally set append_role=true to prepend the TutorCruncher role (Admin, Contractor, Client, etc.) to the username, which then allows a presenter user to be set for your TutorCruncher rooms |
Android ChromeWebView
If using an Android ChromeWebView, you may need to call:
webview.getSettings().setMediaPlaybackRequiresUserGesture(false)
in order to enable audio/video.
Home | Contact | Privacy