Authoring Sketches on the Desktop
Check out our beta-test site for instructional videos and examples of authored sketches.
For a complete author's manual see the Sketchpad Reference Center.
Exporting Sketches
How to export a Desktop Sketch as a Web Sketch
Tools and Tool Authoring
See Sketchpad Construction Tools -- how to author tools so that they appear in Web Sketches.
Most of the standard WSP tools support the Tool Help feature. (The Tool Help feature provides text hints for most of the standard WSP tools, and provides video hints for many of them.)
Widgets
Five widgets are available, each of which is activated by tapping its icon in the floating Widget Controller and deactivated by a second tap on the same icon. The widgeta allow the user to perform certain actions by tapping objects in the sketch: changing their styles, turning tracing on or off, labeling them, changing their visibility, and deleting them.
To make a widget available in your sketch, check the appropriate checkbox in the WSP Exporter's Export Document dialog box. For each widget you enable, you can enable it for all pages or you can list the pages on which it should appear, separated by commas (for example, "1,3,5"). Alternatively, you can use the sketch document itself to specify which widgets appear on which pages, as described in the Author Preferences section below.
Utility Popup Menu
The Utility popup menu appears below the bottom left corner of a sketch and includes commands that allow the user to manipulate the sketch in some way. The two commands currently available are Download and Upload.
This menu (and its commands) are available only by checking the Include Utility Menu checkbox in the Export Document dialog box.
AutoStart Buttons
An autostart page button is a button that will be automatically pressed every time its sketch page appears, both when the sketch is first loaded and when the user switches to the page. You can set a button to autostart in either of two ways: (a) select the button when you save your source (.gsp) sketch, or (b) label it "autostart: " followed by the desired label of your choice. For instance, you might label a reset button "autostart: Reset." (Note "autostart" by itself is not enough.)
Autostart buttons (whether designated by label or by selection) are pressed automatically whenever a sketch page is loaded. For instance, an autostart button on page 2 of a sketch will be pressed automatically every time the user navigates to that page (not just the first time).
Glide Reflection
Web Sketchpad supports glide reflection similarly to other geometric transformations. A glide-reflected image in WSP is determined by three objects: the source object (also known as the pre-image) and two points that define the mirror/vector. If you think of the glide reflection as the composition of a translation (the glide) and a reflection, these two points determine both the vector for the translation and the mirror for the reflection.
Use GSP to author a sketch or tool that will include a glide reflection when exported to WSP: Construct a reflection using a mirror determined by two points. (The mirror itself can be a segment, ray, or line.) Add the signal _glidereflect_ (including the underscores) to the label of the reflected image. When exported to WSP, the image will be converted to a glide reflection that uses the two mirror-determining points as the mirror/vector of glide reflection.
Use WSP to author a sketch that will include a glide reflection when downloaded to a json file: Construct a reflection using a mirror determined by two points, add the signal _glidereflect_ to the label of the reflected image, and download the sketch to a json file. When the json file is uploaded to WSP, the image object will be a glide-reflected image using the two points that determine the mirror as the mirror/vector of glide reflection. (As of this writing, you cannot use WSP to create a glide-reflect tool.)
DEPRECATED: The earlier technique for creating a glide reflection tool by naming the sketch "WSP Tool: glide reflect"should no longer be used, for two reasons:
- It works only for tools (not for sketches).
- If a tool contains more than one reflection, there is no way to indicate which reflection(s) should become glide reflections.
Case Presentation Button
Case buttons allow you to create a presentation button that presents only one of its parent buttons. The first parent of the Case button must contain a value (e.g., a parameter or calculation), and the remaining parents must be Action Buttons. When the case button is pressed, the value of the first parent serves as an index, determining which of the remaining button parents will be activated. This index must be an integer in the range 1...n, where n is the number of button parents. If the index has any other value the Case button does nothing.
At this time, there is no direct way to create a Case button in GSP. There is, however, a work-around: create a Hide/Show button with the desired parents, and give it a name that starts with "_Case:". Whatever follows the colon will become the label of the Case button. Alternatively, if you add nothing after the colon, the label of the Case button will match the parent button that it will activate. For instance, if the second and third parents are buttons labeled Foo and Bar, the Case button will be labeled "Foo" when the value of the first parent is 1, and "Bar" when the first parent has value of 2.
Just as with Sequence and Simultaneous Presentation buttons, pressing an active Case button stops the action. Along with the auto-labeling feature, this makes it convenient to use a Case button to control a number of hidden buttons; the Case button can display the name of its current target (the parent action button) and can turn that target on or off with a click.
Author Preferences
Certain preferences can be set by sketch authors in the document itself. To set these author preferences, create a page in your document using the Desktop version of Sketchpad, and name the page "WSP Preferences" (without quotes). On this page, any independent captions of the form "preferenceName=preferenceValue" will be exported as author preferences for the document in Web Sketchpad.
We support the author preferences listed below. Some of these (disableScrolling, removeInaccessibleObjects, and the various widget preferences) determine Exporter settings that are also available in the Exporter's "Export Document" dialog box. The remaining author preferences (including the tool preferences) can be set only on the WSP Preferences page of the sketch.
Widget, Tool, and Utility Author Preferences
By default, if you include widgets when you export a sketch, widgets are enabled on each page of your sketch. But you may want only the style widget, or you may want a widget to appear on some sketch pages but not others. You can use the WSP Preferences page of your sketch (described above) to accomplish this. Below are several examples.
Widget, Tool, and Utility Prefs in HTML
Widget and Utility prefs can also be set directly via a script in the host HTML page. This is particularly useful when an HTML page contains multiple websketches distinguished by their id's or .json filenames, because it allows you to set all of the widget and utility preferences in one place.
Page Controller
The page controller makes it easy for a user to move from page to page of a sketch containing multiple pages. To add the page controller to a web page, check the Include Widgets checkbox in the Export Document dialog box. (This option is available only when you export a complete web page.) The page controller incorporates three buttons:
- Tap the left-pointing arrow to switch to the previous page of the sketch.
- Tap the page number to pop up a list of pages. Drag or hover on the list to view and switch pages.
- Tap the right-pointing arrow to switch to the next page of the sketch.
The page controller appears only for sketches that have more than a single page.
- Page Controller Without Widgets
To export a sketch with the page controller but no widgets, you can use either Author Preferences or Widget HTML Preferences. In either case, you need to use the Include Widgets option in the Export Document dialog box.
To use Author Preferences, include the following three captions on the WSP Preferences page of your sketch:
visibilityWidget=none styleWidget=none labelWidget=none
To eliminate the page controller using Widget HTML Preferences, include the following script on your HTML page:
<script type="text/javascript"> WIDGETS.setWidgetPrefs ([{pages: "none"}]);<script>
Multiple Sketches on an Existing Web Page
- To add one or more websketches to an existing web page (whose source is referred to below as index.html”), you must prepare the webpage directory and modify the contents of index.html.
- On the WSP build site, use the Sketch Exporter page to export the desired websketch(es) in Javascript format. The name of each resulting file will be based on the name of the source sketch (for instance, exporting "mysketch.gsp" creates the file “mysketch-json.js”).
- Put your downloaded json.js files into the webpage directory.
- On the WSP build site, use the Download page to download the zip file for the current WSP build.
- Unzip the build and put the resulting js directory into the webpage directory.
- If you’re including widgets, also put the resulting widgets directory into the webpage directory.
- Add the following lines in the <head> portion of the page:
<script charset="utf-8" type="text/javascript" src="./js/jquery-2.1.0.min.js"></script> <script charset="utf-8" type="text/javascript" src="./js/wsp-min.js"></script> <script charset="utf-8" type="text/javascript" src="./js/wsp-runner.js"></script> <style type="text/css”> .sketch_canvas { border: medium solid lightgray; display: inline-block; } </style> - Add the following line in the <body> where you want each websketch to appear, changing the data-var to use the name associated with the downloaded json file. (Don't include the "-json.js" part of teh file name.)
<div class="sketch_canvas" data-var="mysketch" > </div>
-
Add the following lines in the <head> portion of the page:
<script charset="utf-8" type="text/javascript" src="./js/jquery-2.1.0.min.js"></script> <script charset="utf-8" type="text/javascript" src="./js/wsp-min.js"></script> <script charset="utf-8" type="text/javascript" src="./widgets/jquery.tiny-draggable.js"></script> <link rel="stylesheet" type="text/css" href="./widgets/widgets.css" /> <script charset="utf-8" type="text/javascript" src="./widgets/widgets.js"></script> <script charset="utf-8" type="text/javascript" src="./js/wsp-runner.js"></script> <style type="text/css”> .sketch_canvas { border: medium solid lightgray; display: inline-block; } </style> - Add the following lines in the <body> where you want each websketch to appear, changing the data-var to use the name associated with the desired json.js file:
<div class="sketch_container"> <div class="sketch_canvas" data-var="mysketch" > </div> <div style="clear:both;"></div> <div class="util-menu-btn"></div> <!-- only needed if including the utility menu --> <p><!--Any (short!) desired left-justified text goes here--></p> <span class="page_buttons"></span> <!-- only needed if including page controls --> <button class="widget_button">Widgets</button> <!-- only useful if the page includes multiple websketches --> </div>
- You can store the websketches used on your webpage in a directory of their own to avoid cluttering the main webpage directory.
- Inside the webpage directory create a directory for storing the websketches. In this example we name this directory "sketches".
- Put your websketch files, in json.js format, into the sketches directory.
- Use the following form for your sketch_canvas elements. This example assumes the sketch file is "triangle-json.js".
<div class="sketch_canvas" data-var="sketches/triangle" > </div>
- When Web Sketchpad creates a Javascript formatted sketch file, the file is actually a javascript file that defines a javascript variable containing the sketch information. Web Sketchpad uses the name of the variable as part of the file name. If the source file for the exporter was triangle.gsp, the javascript variable will be "triangle" and the sketch filename will be "triangle-json.js".
- If you change the name of the file, the variable name and the file name will no longer match, and the sketch will not load properly.
- If you want to change the name of an existing sketch file, you can either edit the named variable inside the file (ugh! risky!), or use Web Sketchpad to do it for you. To use Web Sketchpad, upload the original file either into the Exporter or into a websketch that has the Utility Menu's Upload and Download commands available. When you subsequently download the file, you can give it a new name and Web Sketchpad will guarantee that the new file name and variable name match.
Per-Page Tools
You can now specify which tools should appear on each page of a websketch.
For instance, if your GSP document has three tool pages named WSP Tool: Point, WSP Tool: Segment, and WSP Tool: Circle, you could make the Point tool appear on all pages, make the Segment tool appear on both pages 2 and 3, and make the Circle tool appear only on page 3. To do so, create a WSP Preferences page in your source sketch (the .gsp document) and enter the following captions:
SegmentTool = 2,3 CircleTool = 3
When you export your sketch, the Segment and Circle tools will appear only on the indicated pages.
Because the Point tool is not listed, it will appear on all pages of the websketch.
Make Your Webpage Respond to Sketch Page Changes
The author of a webpage can now display different information depending on the sketch page the user is displaying. For instance, the sketch container below includes a <div> element above the sketch that will appear only when the user accesses page 2 or page 3 of the corresponding sketch, and another <div> element that appears below the sketch only when the user is on page 3.
<div class="sketch_container">
<div class="page_toggle p_2 p_3">
<p>This text appears only when the user is on page 2 or 3 of the sketch.</p>
</div>
<div class="sketch_canvas" data-url="mysketch.json" > </div>
<div class="page_toggle p_3">
<p>This text appears below the sketch only when the user is on page 3.</p>
</div>
</div>
To use this feature, include widgets on your webpage (even if you don't use the widgets themselves), and locate both the sketch_canvas and page_toggle elements within the same sketch_container <div>.
Use a Link in your Webpage to Change the Page in a Sketch
The author of a webpage can now create a link in the webpage that changes the current page of the related sketch. To be "related" the link must be in the same sketch_container <div> that contains the sketch. For instance, the link below will make the sketch change to page 2:
Go on to <a onclick="PAGENUM.gotoPage(this, 2);">page 2.</a>
To use this feature, include widgets on your webpage (even if you don't use the widgets themselves), and locate both the sketch_canvas and page_toggle elements within the same sketch_container <div>.
You can use this feature in conjunction with the page_toggle feature above to make the sketch and web page interact smoothly. For instance, you can create a web page with a page_toggle element containing text related to page 1 of the sketch, and also containing a link to switch to page 2. Clicking that link will simultaneously switch the sketch to page 2 and change the web page itself to show the page_toggle element related to page 2 of the sketch.
Add a Reset Button
- You can add a Reset button below the sketch (just to the left of the page controller) by specifying the "Reset Button" author preference. You can create this preference on the WSP Preferences page of your sketch by adding the caption "Reset Button = all". To put a Reset button on some pages but not others, list the page numbers instead of "all." For example, use "Reset Button = 1,3,5" to show Reset buttons on pages 1, 3, and 5 of your sketch, but not on pages 2 or 4.
- Alternatively, you can check the "Include Reset Button" checkbox on the Sketch Exporter dialog box. The input box next to the checkbox should be "all" for all pages, or should list the page numbers for which the Reset button should appear (for instance, "2, 4" for Reset Buttons on pages 2 and 4).
- Create a "Reset Sketch" button that does something innocuous. You might make a Hide button that hides an already-hidden point, and name the button "Reset Sketch."
- Add the code shown below to your HTML page:
- It's also possible to ploce a Reset button in the sketch. To do so:
<script type="text/javascript">
$(function() {
$(".sketch_container").on ("PressButton.WSP", function (ev, ctx) {
if (ctx.gobj.label === "Reset Sketch") {
ctx.document.undo('all');
}
});
});
</script>
CORS (Cross-Origin Resource Sharing) Restrictions and Javascript Sketch Format
- Though CORS restrictions help prevent malware from infecting web users, they can make it difficult for teachers who create their own sketch-containing web pages for student use. You may find that a WSP sketch in JSON format doesn't load when you open the page on your own computer, even though the sketch appears correctly when you put that same page on a server. (Such problems are somewhat unpredictable, and vary depending on the browser you are using.)
- One solution is to use the Javascript format for sketches rather than the JSON format. Here are some guidelines for doing so:
- When using the WSP Exporter, choose JSON rather than Webpage, and then choose Javascript. If your original sketch is "mysketch.gsp" the resulting websketch will be "mysketch-json.js".
- The sketch_canvas element in your web page should specify data-var = "mysketch".
<div class="sketch_canvas" data-var="mysketch" >Loading... </div>