extensions: updated documentation

HISTORY.md

@@ -29,6 +29,9 @@
     * German
     * Chinese, thanks, Simon!
 
+### 2021-08-02
+* extensions: updated documentation
+
 ### 2021-08-01
 * gui: fixed saving projects with their names
 * store: fixed deserializing global settings per scene in multi-scene projects

snap.html

@@ -28,7 +28,7 @@
         <script src="src/sketch.js?version=2021-07-05"></script>
         <script src="src/video.js?version=2019-06-27"></script>
         <script src="src/maps.js?version=2021-06-15"></script>
-        <script src="src/extensions.js?version=2021-07-20"></script>
+        <script src="src/extensions.js?version=2021-08-02"></script>
         <script src="src/xml.js?version=2021-07-05"></script>
         <script src="src/store.js?version=2021-08-01"></script>
         <script src="src/locale.js?version=2021-07-12"></script>

src/extensions.js

@@ -33,7 +33,7 @@ Color, Process, contains*/
 
 /*jshint esversion: 11*/
 
-modules.extensions = '2021-July-20';
+modules.extensions = '2021-August-2';
 
 // Global stuff
 
@@ -107,8 +107,9 @@ var SnapExtensions = {
 
     function semantics
     ------------------
-    - "this" refers to the current input-slot at call-time
-    - to get a handle on the current block use "this.parentThatIsA(BlockMorph")
+    - "this" refers to the current input-slot at call-time (when the menu is
+      requested by the user by clicking on the down-arrow symbol)
+    - to get a handle on the current block use "this.parentThatIsA(BlockMorph)"
     - likewise to get a handle on the current sprite use
       "this.parentThatIsA(IDE_Morph).currentSprite"
     - if you want the menu of one input slot to depend on the contents of
@@ -122,10 +123,19 @@ var SnapExtensions = {
     ============================
     You can provide extensions for your custom hardware or for arbitrary APIs
     or extend Snap! with JavaScript libraries from other parties. You can
-    load additional JavaScript files using the "src_load(url)" extension
-    primitive inside Snap, which you can find using Snap's search bar in the
-    IDE. The loading primitive will wait until the source file has fully loaded
-    and its defined functions are ready to be called.
+    load additional JavaScript files using the
+    
+        src_load(url)
+    
+    extension primitive inside Snap, which you can find using Snap's search bar
+    in the IDE. The loading primitive will wait until the source file has fully
+    loaded and its defined functions are ready to be called.
+    Snap remembers the external extensions that have been already loaded and
+    will ignore any subsequent calls to load the same external extension again.
+    This lets you lazily initialize your extension by simply adding a
+    "src_load(url)" command for your external JS file before calling any of its
+    added functions.
+    
     
     adding primitives to SnapExtensions
     -----------------------------------
@@ -139,16 +149,24 @@ var SnapExtensions = {
     Running the "src_load(url)" primitive will throw an error unless you first
     check the "Enable JavaScript extensions" setting in Snap's preferences menu,
     or if your JavaScript extension comes from a list of trusted hosts.
-    While you develop your JavaScript extension it's recommended to turn the
-    "Enable JavaScript extensions" setting on to load the extension once, and
+    While you develop your JavaScript extension it's recommended to turn on the
+    "Enable JavaScript extensions" setting to load the extension once, and
     then to turn it off again, so you can make sure your custom blocks are not
     using any "JS Function" blocks (because those will be caught if the
     preference is turned off).
     When you're ready to publish your extension you can contact us to allow-list
     the url hosting your JS file, or you can send me a Github pull-request to
     include it in the main Snap branch.
-    
-    Whatever you do, please use these extension capabilities sensibly.
+    We recommend submitting your extensions to the main Snap! Github repository
+    so they can be made available in the offline versions (source download
+    and PWA).
+    External extensions are a powerful tools to change, override and generally
+    mold Snap into anything you want, so please use these capabilities sensibly.
+    We look forward to your innovations and don't plan to restrict the scope of
+    what extensions are allowed to modify. For security reasons we do ask you to
+    refrain from exposing any form of JS eval(), including "new Function()" to
+    end users (if you want to use eval() internally in your extension we'll
+    frown on you but not reject your contribution).
 */
 
 // Primitives