From ac693b3f1f49be874d674c13004a69a084f5d62e Mon Sep 17 00:00:00 2001 From: jmoenig Date: Mon, 2 Aug 2021 16:44:00 +0200 Subject: [PATCH] extensions: updated documentation --- HISTORY.md | 3 +++ snap.html | 2 +- src/extensions.js | 40 +++++++++++++++++++++++++++++----------- 3 files changed, 33 insertions(+), 12 deletions(-) diff --git a/HISTORY.md b/HISTORY.md index 7c59c729..08df9690 100755 --- a/HISTORY.md +++ b/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 diff --git a/snap.html b/snap.html index 2144010e..8ed09fe3 100755 --- a/snap.html +++ b/snap.html @@ -28,7 +28,7 @@ - + diff --git a/src/extensions.js b/src/extensions.js index 9fd26d2c..3834e5dc 100644 --- a/src/extensions.js +++ b/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