Skip to content

Commit

Permalink
Improvements to documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@Waboodoo
Waboodoo committed Apr 13, 2024
1 parent 890e281 commit 530154b
Show file tree
Hide file tree
Showing 6 changed files with 55 additions and 38 deletions.
34 changes: 17 additions & 17 deletions HTTPShortcuts/app/src/main/assets/docs/scripting.html
View file

Large diffs are not rendered by default.

13 changes: 13 additions & 0 deletions HTTPShortcuts/app/src/main/assets/docs/style.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,19 @@ table thead + tbody tr:first-child td {
border-radius: 0 !important;
}

blockquote {
border: 1px solid #059df7;
border-radius: 5px;
background: #f0f9ff;
margin: 0;
padding: 0px 16px;
}

.dark blockquote {
border: 1px solid #059df7;
background: #062a40;
}

.dark code, .dark pre, .dark th {
background: #090909;
border-color: #202020;
Expand Down
2 changes: 1 addition & 1 deletion HTTPShortcuts/app/src/main/assets/docs/variables.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,6 @@
<link rel="stylesheet" href="style.css">
</head>
<body id="root">
<h1>Variables</h1><p>Variables allow you to inject pieces of information dynamically into your shortcuts when executing them. A variable consists of a name and a value which is resolved at execution time, based on its type. For some variable types this means that a prompt dialog is shown that asks for a value, others can be resolved without user input. They are global, meaning that they do not belong to a specific shortcut but can be used by any of them.</p><p>Variables are also particularly useful when combined with the app's <a href="scripting.md">Scripting</a> capabilities, as it allows you to compute a value using a piece of JavaScript code, store that value into a variable and then use that value as part of the HTTP request.</p><p>For more details on when variables are resolved see the <a href="execution-flow.md">Execution Flow</a> documentation.</p><h2>Using Variables</h2><p>You can insert a placeholder for a variable into your shortcuts' url, requests parameters, request body, authentication and header fields by clicking the <em>&quot;{ }&quot;</em> button next to the input field and selecting a variable.</p><p>When executing a shortcut that contains variable placeholders all of them are resolved according to their type. The are resolved in the order in which they appear in the Variables screen, so if you want one variable to be resolved before another, make sure to rearrange them accordingly by dragging.</p><p>You can also insert these placeholders into some of your variables, i.e., you can have variables reference other variables, and you can use them when writing <a href="scripting.md#variables">scripts</a>.</p><h2>Variable Types</h2><p>When creating a variable, you have to select its type. The type dictates how the variable will receive its value, and what types of values it supports.</p><p><a name="constant"></a></p><h3>Static Variable</h3><p>A <em>Static Variable</em> (formerly called <em>constant</em>) stores a static value. A typical use case is to store a piece of information that is shared across multiple shortcuts, such as an authentication token or a domain name. This way it can easily be changed.</p><p>It is also possible to change the value of a static variable programmatically before or after a shortcut runs, e.g., to store parts of an HTTP response into it. See the <a href="scripting.md#variables">Scripting</a> documentation for more details.</p><p><a name="multiple-choice"></a></p><h3>Multiple Choice Selection</h3><p>The <em>Multiple Choice Selection</em> type consists of a list of options, each of which has a value and a label. It triggers a dialog from which one of the options can be selected.</p><p>It can also be configured to allow selecting multiple values. The selected values will be concatenated using the specified separator. The order in which they were selected is preserved.</p><p><a name="text-number-password"></a></p><h3>Text Input, Number and Password Input</h3><p>The <em>Text Input</em>, <em>Number Input</em> and <em>Password Input</em> types trigger a prompt dialog where a value can be entered into a text field.</p><p><a name="number-slider"></a></p><h3>Number Slider</h3><p>The <em>Number Slider</em> type is similar to the <em>number</em> type. It allows you to pick a number. However, the number is entered using a horizontal slider, for which you can define the minimum and maximum value, as well as the step size.</p><p><a name="date-time"></a></p><h3>Date Input and Time Input</h3><p>The <em>Date Input</em> and <em>Time Input</em> types trigger a prompt dialog where a date or time can be selected. If you just want the current date or time without showing a picker dialog, use the <em>timestamp</em> type instead.</p><p>The output format can be specified according to Android's <a href="https://developer.android.com/reference/java/text/SimpleDateFormat.html">SimpleDateFormat</a>.</p><p><a name="timestamp"></a></p><h3>Timestamp</h3><p>A variable of <em>timestamp</em> type will use the current date and/or time as its valid, using the specified format. The output format can be specified according to Android's <a href="https://developer.android.com/reference/java/text/SimpleDateFormat.html">SimpleDateFormat</a>.</p><p><a name="color"></a></p><h3>Color Input</h3><p>The <em>Color Input</em> type triggers a prompt dialog where a color can be selected. Its value is returned in RGB hex format (e.g., ff0000 for red).</p><p><a name="toggle"></a></p><h3>Toggle</h3><p>The <em>Toggle</em> type consists of a list of values. Every time it is used it resolves to the next value in the list. When the last value is reached it starts again from the first.</p><p><a name="increment"></a></p><h3>Incrementing Counter</h3><p>The <em>Incrementing Counter</em> type tracks a and returns a number. Each time the variable is resolved, the number is increased by 1.</p><p><a name="uuid"></a></p><h3>UUID</h3><p>The <em>uuid</em> type will generate a random UUID (<em>U</em>niversally <em>U</em>nique <em>Id</em>entifier) and use that as its value.</p><p>Please note that the UUID is generated once per shortcut execution, not once per variable use, meaning that if you use the same variable multiple times within one shortcut it will have the same value in all places. If you need multiple UUIDs for a single shortcut execution you'll need to use multiple different variables.</p><p><a name="clipboard-content"></a></p><h3>Clipboard Content</h3><p>Variables of type <em>clipboard content</em> will resolve to the latest textual value that was copied to the clipboard. If there is no text in the clipboard or the last thing that was copied does not have a textual representation, the variable will have an empty value.</p><p><a name="sharing"></a></p><h2>Sharing Values into Variables</h2><p>In the advanced settings section of a variable you can mark it as <em>Allow Receiving Value from Share Dialog</em>. This makes it possible to provide the value of this variable through Android's <em>Share</em>-dialog, e.g., by sharing a URL or text snippet from another app. The variable will then assume the shared value during the execution of a shortcut.</p><p>If you enable this option, you will also find a dropdown further down which lets you pick which part of the shared value the variable should assume: the text, the title (if any), or both.</p><p>If you are on Android 11 or newer, you can enhance this by enabling a shortcut as a Direct Share target. You will find the checkbox for this in its &quot;Trigger &amp; Execution Settings&quot;. When this is enabled, the shortcut will appear in the Direct Share sheet, making it easier to quickly share text with that specific shortcut.</p>
<h1>Variables</h1><p>Variables allow you to inject pieces of information dynamically into your shortcuts when executing them. A variable consists of a name and a value which is resolved at execution time, based on its type. For some variable types this means that a prompt dialog is shown that asks for a value, others can be resolved without user input. They are global, meaning that they do not belong to a specific shortcut but can be used by any of them.</p><p>Variables are also particularly useful when combined with the app's <a href="scripting.md">Scripting</a> capabilities, as it allows you to compute a value using a piece of JavaScript code, store that value into a variable and then use that value as part of the HTTP request.</p><p>For more details on when variables are resolved see the <a href="execution-flow.md">Execution Flow</a> documentation.</p><h2>Using Variables</h2><p>You can insert a placeholder for a variable into your shortcuts' url, requests parameters, request body, authentication and header fields by clicking the <em>&quot;{ }&quot;</em> button next to the input field and selecting a variable.</p><p>When executing a shortcut that contains variable placeholders all of them are resolved according to their type. The are resolved in the order in which they appear in the Variables screen, so if you want one variable to be resolved before another, make sure to rearrange them accordingly by dragging.</p><p>You can also insert these placeholders into some of your variables, i.e., you can have variables reference other variables, and you can use them when writing <a href="scripting.md#variables">scripts</a>.</p><h2>Variable Types</h2><p>When creating a variable, you have to select its type. The type dictates how the variable will receive its value, and what types of values it supports.</p><p><a name="constant"></a></p><h3>Static Variable</h3><p>A <em>Static Variable</em> (formerly called <em>constant</em>) stores a static value. A typical use case is to store a piece of information that is shared across multiple shortcuts, such as an authentication token or a domain name. This way it can easily be changed.</p><p>It is also possible to change the value of a static variable programmatically before or after a shortcut runs, e.g., to store parts of an HTTP response into it. See the <a href="scripting.md#variables">Scripting</a> documentation for more details.</p><p><a name="multiple-choice"></a></p><h3>Multiple Choice Selection</h3><p>The <em>Multiple Choice Selection</em> type consists of a list of options, each of which has a value and a label. It triggers a dialog from which one of the options can be selected.</p><p>It can also be configured to allow selecting multiple values. The selected values will be concatenated using the specified separator. The order in which they were selected is preserved.</p><p><a name="text-number-password"></a></p><h3>Text Input, Number and Password Input</h3><p>The <em>Text Input</em>, <em>Number Input</em> and <em>Password Input</em> types trigger a prompt dialog where a value can be entered into a text field.</p><p><a name="number-slider"></a></p><h3>Number Slider</h3><p>The <em>Number Slider</em> type is similar to the <em>number</em> type. It allows you to pick a number. However, the number is entered using a horizontal slider, for which you can define the minimum and maximum value, as well as the step size.</p><p><a name="date-time"></a></p><h3>Date Input and Time Input</h3><p>The <em>Date Input</em> and <em>Time Input</em> types trigger a prompt dialog where a date or time can be selected. If you just want the current date or time without showing a picker dialog, use the <em>timestamp</em> type instead.</p><p>The output format can be specified according to Android's <a href="https://developer.android.com/reference/java/text/SimpleDateFormat.html">SimpleDateFormat</a>.</p><p><a name="timestamp"></a></p><h3>Timestamp</h3><p>A variable of <em>timestamp</em> type will use the current date and/or time as its valid, using the specified format. The output format can be specified according to Android's <a href="https://developer.android.com/reference/java/text/SimpleDateFormat.html">SimpleDateFormat</a>.</p><p><a name="color"></a></p><h3>Color Input</h3><p>The <em>Color Input</em> type triggers a prompt dialog where a color can be selected. Its value is returned in RGB hex format (e.g., ff0000 for red).</p><p><a name="toggle"></a></p><h3>Toggle</h3><p>The <em>Toggle</em> type consists of a list of values. Every time it is used it resolves to the next value in the list. When the last value is reached it starts again from the first.</p><p><a name="increment"></a></p><h3>Incrementing Counter</h3><p>The <em>Incrementing Counter</em> type tracks a and returns a number. Each time the variable is resolved, the number is increased by 1.</p><p><a name="uuid"></a></p><h3>UUID</h3><p>The <em>uuid</em> type will generate a random UUID (<em>U</em>niversally <em>U</em>nique <em>Id</em>entifier) and use that as its value.</p><blockquote><p>Please note that the UUID is generated once per shortcut execution, not once per variable use, meaning that if you use the same variable multiple times within one shortcut it will have the same value in all places. If you need multiple UUIDs for a single shortcut execution you'll need to use multiple different variables.</p></blockquote><p><a name="clipboard-content"></a></p><h3>Clipboard Content</h3><p>Variables of type <em>clipboard content</em> will resolve to the latest textual value that was copied to the clipboard. If there is no text in the clipboard or the last thing that was copied does not have a textual representation, the variable will have an empty value.</p><p><a name="sharing"></a></p><h2>Sharing Values into Variables</h2><p>In the advanced settings section of a variable you can mark it as <em>Allow Receiving Value from Share Dialog</em>. This makes it possible to provide the value of this variable through Android's <em>Share</em>-dialog, e.g., by sharing a URL or text snippet from another app. The variable will then assume the shared value during the execution of a shortcut.</p><p>If you enable this option, you will also find a dropdown further down which lets you pick which part of the shared value the variable should assume: the text, the title/subject (if any), or both.</p><p>If you are on Android 11 or newer, you can enhance this by enabling a shortcut as a Direct Share target. You will find the checkbox for this in its &quot;Trigger &amp; Execution Settings&quot;. When this is enabled, the shortcut will appear in the Direct Share sheet, making it easier to quickly share text with that specific shortcut.</p>
</body>
</html>
2 changes: 1 addition & 1 deletion HTTPShortcuts/build.gradle.kts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ buildscript {
dependencies {
classpath("com.android.tools.build:gradle:8.3.1")
classpath("com.bugsnag:bugsnag-android-gradle-plugin:8.1.0")
classpath("org.jetbrains:markdown:0.6.1")
classpath("org.jetbrains:markdown:0.7.0")
classpath(kotlin("gradle-plugin", "1.9.23"))
classpath("com.github.bjoernq:unmockplugin:0.7.9")
}
Expand Down
Loading

0 comments on commit 530154b

Please sign in to comment.