Feature & doc updates for v1.04

dwilding · Jul 16, 2024 · f5a5096 · f5a5096
1 parent 41676ce
commit f5a5096
Show file tree

Hide file tree

Showing 15 changed files with 155 additions and 58 deletions.
diff --git a/.gitignore b/.gitignore
@@ -3,7 +3,9 @@ local/LICENSE_openpgp
 local/static
 local/__pycache__
 local/Frogtab_backup.json
-frogtab_local_*
+snapcraft
+frogtab_*.zip
+frogtab_*.snap
 server/public/*
 !server/public/open
 server/packages/*

diff --git a/README.md b/README.md
@@ -8,6 +8,7 @@ In this README:
 
   - [Technical overview of Frogtab](#technical-overview-of-frogtab)
   - [How your personal link works](#how-your-personal-link-works)
+  - [Customizing the placeholder text of your personal link](#customizing-the-placeholder-text-of-your-personal-link)
   - [Using your personal link from JavaScript](#using-your-personal-link-from-javascript)
   - [Self-hosting Frogtab](#self-hosting-frogtab)
   - [Acknowledgments](#acknowledgments)
@@ -65,6 +66,17 @@ the frogtab.com server creates a personal link that you can use to send tasks to
 
     See `verifyUserAndAppendMessages()` in [main.js](app/main.js).
 
+## Customizing the placeholder text of your personal link
+
+By default, the placeholder text of your personal link is "Send to your inbox…".
+You can override the default placeholder text to help you identify the device that you're sending tasks to.
+
+To override the default placeholder text, add `/{text}` to the end of your personal link, where `{text}` is your preferred placeholder text.
+Make sure that any special characters in the placeholder text are correctly [percent-encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding) in your personal link.
+For example, to use "Send to Linux desktop…" as the placeholder text, add `/Send%20to%20Linux%20desktop%E2%80%A6` to the end of your personal link.
+
+To override the default placeholder text and automatically use the correct encoding, open your personal link in your browser, then enter `setPlaceholder("Custom placeholder text")` in the web console.
+
 ## Using your personal link from JavaScript
 
 After registering your device, you can use the JavaScript SDK to send messages to your device:
@@ -90,7 +102,7 @@ send("Hello Frogtab!").then(success => {
 });
 ```
 
-Replace `USER ID GOES HERE` by the ID from the URL of your personal link.
+Replace `USER ID GOES HERE` by the ID from your personal link.
 
 To learn more, see [this blog post](https://maybecoding.bearblog.dev/adding-a-private-feedback-box-to-bear/).
 
@@ -133,7 +145,7 @@ This database stores device credentials and the queue of encrypted tasks.
 Frogtab is licensed under the MIT License.
 For details, see [LICENSE](LICENSE).
 
-Frogtab uses OpenPGP.js for PGP encryption and decryption.
+Frogtab uses OpenPGP.js for PGP encryption.
+The source code of OpenPGP.js is available at https://github.com/openpgpjs/openpgpjs.
 OpenPGP.js is licensed under the GNU Lesser General Public License.
-For details, see [LICENSE_openpgp](LICENSE_openpgp).
-The source code of OpenPGP.js is available at https://github.com/openpgpjs/openpgpjs.
+For details, see [LICENSE_openpgp](LICENSE_openpgp).
diff --git a/app/achievements.html b/app/achievements.html
@@ -10,7 +10,7 @@
     <link rel="apple-touch-icon" sizes="180x180" href="favicons/icon-180-apple.png">
     <link rel="manifest" href="manifest.webmanifest">
     <link rel="stylesheet" href="simple.min.css?sha1=24725a1eaf66103ed47a6d30f82c9273a50334c1">
-    <link rel="stylesheet" href="simple-customizations.css?sha1=51841d44b30c46cb6a3b9b4fea851fdfeff06b2d">
+    <link rel="stylesheet" href="simple-customizations.css?sha1=0bb2de2dbacefa4f4c8ede18700f56ad4fa48fea">
   </head>
   <body>
     <header>

diff --git a/app/help.html b/app/help.html
@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html lang="en" data-server-base="https://frogtab.com/" data-registration="short" data-vibe="" data-save="browser" data-theme="system">
+<html lang="en" data-server-base="https://frogtab.com/" data-registration="short" data-save="browser" data-theme="system">
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
@@ -10,7 +10,7 @@
     <link rel="apple-touch-icon" sizes="180x180" href="favicons/icon-180-apple.png">
     <link rel="manifest" href="manifest.webmanifest">
     <link rel="stylesheet" href="simple.min.css?sha1=24725a1eaf66103ed47a6d30f82c9273a50334c1">
-    <link rel="stylesheet" href="simple-customizations.css?sha1=51841d44b30c46cb6a3b9b4fea851fdfeff06b2d">
+    <link rel="stylesheet" href="simple-customizations.css?sha1=0bb2de2dbacefa4f4c8ede18700f56ad4fa48fea">
   </head>
   <body>
     <header>
@@ -133,7 +133,7 @@ <h2 id="registering-for-a-personal-link">Registering for a personal link</h2>
         </div>
         <div id="case-unregistered">
           <p>
-            You have not registered this device.<span class="long-registration-only"> To register this device, please share your experience of using Frogtab - thank you!</span>
+            You have not registered this device<span class="short-registration-only"> with <span class="server-hostname"></span></span>.<span class="long-registration-only"> To register this device, please share your experience of using Frogtab - thank you!</span>
           </p>
           <div class="long-registration-only">
             <input id="comment" style="width: 100%" type="text" placeholder="Your experience…">
@@ -152,7 +152,7 @@ <h2 id="registering-for-a-personal-link">Registering for a personal link</h2>
         </div>
         <div id="case-registered">
           <p>
-            You have registered this device.
+            You have registered this device<span class="short-registration-only"> with <span class="server-hostname"></span></span>.
           </p>
           <div>
             <a href="#" target="_blank" id="link" class="button">Open My Personal Link</a>
@@ -576,17 +576,13 @@ <h2 id="exporting-your-data">Exporting your data</h2>
       <div class="notice display service-save-only">
         <div class="display">
           <p>
-            The Flask app supports automatic backups. Select a backup method:
+            To enable automatic backups, select a backup method:
           </p>
           <div>
             <select id="save-method">
               <option value="none" selected>None</option>
             </select>
           </div>
-          <p>
-            You can add your own backup methods by modifying the Flask app.
-            To learn more, see the README file.
-          </p>
         </div>
       </div>
       <p>
@@ -709,12 +705,7 @@ <h2 id="privacy-implications-of-registering">Privacy implications of registering
         ]);
       }
       function getPersonalLink() {
-        let personalLink = `${serverBase}send#${localStorage.getItem("user.userID")}`;
-        const vibe = document.documentElement.getAttribute("data-vibe");
-        if (vibe != "") {
-          personalLink = `${personalLink}/${encodeURIComponent(vibe)}`;
-        }
-        return personalLink;
+        return `${serverBase}send#${localStorage.getItem("user.userID")}`;
       }
       async function verify() {
         await delayForUX(async () => {
@@ -761,7 +752,7 @@ <h2 id="privacy-implications-of-registering">Privacy implications of registering
           }
           const pgpKey = await openpgp.generateKey({
             userIDs: [{
-              email: `key+${crypto.randomUUID()}@frogtab.com`
+              email: "frogtab@example.com"
             }]
           });
           const requestBody = {
@@ -1107,6 +1098,12 @@ <h2 id="privacy-implications-of-registering">Privacy implications of registering
         cancelDisableAchievements: document.getElementById("cancel-disable-achievements")
       };
       const serverBase = document.documentElement.getAttribute("data-server-base");
+      const serverHostname = (new URL(serverBase, window.location.origin)).hostname;
+      // ^ If serverBase is absolute, gets hostname from serverBase
+      //   If serverBase is relative, gets hostname from window.location.origin
+      for (const element of document.querySelectorAll(".server-hostname")) {
+        element.innerText = serverHostname;
+      }
       let verifiedUser = false;
       let openpgp;
       startApp();

diff --git a/app/send.html b/app/send.html
@@ -222,6 +222,11 @@
             }
             catch (err) {}
           }
+          setPlaceholder = (text = "Send to your inbox…") => {
+            window.history.replaceState(null, "", `#${userID}/${encodeURIComponent(text)}`);
+            dom.editor.placeholder = text;
+            return text;
+          };
           setSendCloud();
         }
         dom.send.addEventListener("mouseenter", () => {
@@ -254,6 +259,7 @@
       let userID = null;
       let pgpPublicKeyObj = null;
       let openpgp;
+      let setPlaceholder;
       startApp();
     </script>
   </body>

diff --git a/app/simple-customizations.css b/app/simple-customizations.css
@@ -99,6 +99,9 @@ img.dark-only {
 :root[data-registration="short"] .long-registration-only {
   display: none;
 }
+:root[data-registration="long"] .short-registration-only {
+  display: none;
+}
 /* Hide parts of the data export help */
 :root[data-save="service"] .browser-save-only {
   display: none;

diff --git a/dev_build_local.sh → dev_create_release.sh b/dev_build_local.sh → dev_create_release.sh
@@ -1,19 +1,30 @@
 #!/bin/sh
 
-cp LICENSE local
-cp LICENSE_openpgp local
+cp LICENSE LICENSE_openpgp local
 rm -rf local/static
 cp -r app local/static
 rm -rf local/__pycache__
 rm -f local/Frogtab_backup.json
 
 cd local/static
 sed -i'.backup' 's/data-save=\"browser\"/data-save=\"service\"/' index.html icon-*.html help.html
-sed -i'.backup' 's/data-vibe=\"\"/data-vibe=\"👽 Send to your inbox…\"/' help.html
 rm *.backup
 
 cd ..
 zip -r frogtab_local_v1xx.zip .
 mv frogtab_local_v1xx.zip ..
 
+cd ..
+rm -rf snapcraft
+cp -r local snapcraft
+rm -f snapcraft/README.md
+rm -f snapcraft/CHANGELOG.md
+cp -r snap/* snapcraft
+
+cd snapcraft
+mkdir flask
+mv static app.py frogtab_helpers.py requirements.txt flask
+snapcraft pack
+mv frogtab_*.snap ..
+
 cd ..
diff --git a/local/CHANGELOG.md b/local/CHANGELOG.md
@@ -0,0 +1,16 @@
+# 1.04
+  - Changed the Flask app to run via Python instead of the `flask` command. The port is now specified in *config.py*
+  - Changed the name of the built-in backup method to show the backup directory instead of the filename
+  - Identified the registration server in "Registering for a personal link" on the help page
+  - Removed the `data-vibe` attribute and documented how to [customize the placeholder text of your personal link](https://github.com/dwilding/frogtab#customizing-the-placeholder-text-of-your-personal-link)
+
+# 1.03
+  - Improved support & docs for self-hosted servers
+
+# 1.02
+  - Fixed a bug with the registration button
+  - Made some minor documentation updates
+  - Updated Simple.css and OpenPGP.js
+
+# 1.01
+  - Initial version of Frogtab Local
diff --git a/local/README.md b/local/README.md
@@ -2,7 +2,7 @@
 
 Frogtab Local is a version of https://frogtab.com that you can run on your computer.
 Frogtab Local is implemented as a Flask app that runs in development mode.
-You're encouraged to tinker with the app!
+I encourage you to tinker with the app!
 
 Frogtab Local supports personal links, but your device will be registered with frogtab.com.
 If you self-host Frogtab, you can configure Frogtab Local to use your own server instead.
@@ -11,47 +11,37 @@ See below for details.
 ## Requirements
 
   - Python 3.8 or later. See https://www.python.org/downloads/
-  - Flask. See https://flask.palletsprojects.com/en/3.0.x/installation/
+  - Flask.
+    I recommend that you install Flask in a virtual environment.
+    See https://flask.palletsprojects.com/en/3.0.x/installation/#virtual-environments
 
 ## Running the Flask app
 
-Open a terminal in the directory that contains *app.py*, then use the following command:
+Open a terminal in the directory that contains *app.py*, then enter the following command:
 
 ```sh
-flask run
+python app.py
 ```
 
 The Flask app starts:
 
 ```
- * Debug mode: off
 WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
  * Running on http://127.0.0.1:5000
 ```
 
-To access Frogtab Local, open http://127.0.0.1:5000 in your browser.
+To access Frogtab, open http://127.0.0.1:5000 in your browser.
 
-To specify a different port, use the following command instead of `flask run`:
-
-```sh
-flask run --port 8080
-```
-
-## Differences between Frogtab Local and frogtab.com
-
-  - Frogtab Local doesn't rely on your browser to save backup files.
-    Instead, the Flask app can save backup files.
-    This approach improves support for automatic backups and lets you add your own backup methods. See below for details.
-
-  - You can register for a personal link without sending a comment.
-
-  - You can customize the placeholder text of your personal link.
-    This is actually possible with frogtab.com too, but you have to manually adjust the URL of your personal link.
-    With Frogtab Local, you can use the `data-vibe` attribute at the top of *static/help.html* to customize the placeholder text.
+To specify a different port, modify the `local_port` variable in *config.py*, then run `python app.py` again.
 
 ## Adding your own backup method
 
-Define your backup method as a function in *config.py* and apply the `@backup` decorator to the function. For example:
+Frogtab Local doesn't rely on your browser to save backup files.
+Instead, the Flask app can save backup files.
+This approach improves support for automatic backups and lets you add your own backup methods.
+
+To add your own backup method, define your backup method as a function in *config.py* and apply the `@backup` decorator to the function.
+For example:
 
 ```py
 @backup('Save to Desktop')
@@ -60,7 +50,7 @@ def save_to_desktop(data):
 ```
 
 The `data` parameter is a dictionary that contains the backup data from your browser.
-The argument to `@backup` is the name of the backup method that will appear on the help page of Frogtab Local.
+The argument to `@backup` is the name of the backup method that will appear in the list of backup methods.
 
 ## Using a self-hosted server for personal links
 
@@ -77,10 +67,11 @@ After installing Frogtab on your server, modify the `data-server-base` attribute
 In the `data-server-base` attribute, replace `https://frogtab.com/` by the URL of your installation of Frogtab.
 
 ## License
+
 Frogtab Local is licensed under the MIT License.
 For details, see *LICENSE*.
 
-Frogtab Local uses OpenPGP.js for PGP encryption and decryption.
+Frogtab Local uses OpenPGP.js for PGP encryption.
+The source code of OpenPGP.js is available at https://github.com/openpgpjs/openpgpjs.
 OpenPGP.js is licensed under the GNU Lesser General Public License.
-For details, see *LICENSE_openpgp*.
-The source code of OpenPGP.js is available at https://github.com/openpgpjs/openpgpjs.
+For details, see *LICENSE_openpgp*.
diff --git a/local/app.py b/local/app.py
@@ -1,6 +1,6 @@
 from flask import Flask, send_from_directory, request
-from functions import list_methods, save_data
-import config
+from frogtab_helpers import list_methods, save_data
+from config import local_port
 
 app = Flask(__name__, static_url_path='/')
 
@@ -23,4 +23,7 @@ def get_methods():
 def post_data():
     body = request.get_json()
     key = body['key']
-    return save_data(key, body['data'])
+    return save_data(key, body['data'])
+
+if __name__ == '__main__':
+    app.run(port=local_port)
diff --git a/local/config.py b/local/config.py
@@ -1,5 +1,7 @@
-from functions import backup, write_json
+from frogtab_helpers import working_dir, backup, write_json
 
-@backup('Save to Frogtab_backup.json')
+local_port = 5000
+
+@backup(f'Save file to {working_dir}')
 def save_file(data):
     write_json(data, 'Frogtab_backup.json')
diff --git a/local/functions.py → local/frogtab_helpers.py b/local/functions.py → local/frogtab_helpers.py
@@ -1,5 +1,7 @@
+from pathlib import Path
 from json import dump
 
+working_dir = Path.cwd()
 methods = {}
 
 def backup(desc):

diff --git a/local/requirements.txt b/local/requirements.txt
@@ -0,0 +1 @@
+Flask>=2.2.5
diff --git a/snap/bin/run.sh b/snap/bin/run.sh
@@ -0,0 +1,8 @@
+#!/bin/sh
+
+cd "$SNAP_USER_COMMON"
+if test ! -e config.py; then
+  cp "$SNAP/config.py" .
+fi
+export PYTHONPATH=".:$PYTHONPATH"
+"$SNAP/bin/python3" "$SNAP/flask/app.py" > /dev/null