Tutorial: How to manually 'install' and run scripts

The right place to talk JavaScript
Post Reply
User avatar
TrianguloY
Posts: 77
Joined: Thu Jan 24, 2019 9:46 am

Tutorial: How to manually 'install' and run scripts

Post by TrianguloY » Sat Feb 23, 2019 11:14 am

This is a tutorial to explain how to 'install' and run an existing script (that you can copy in your clipboard) manually without external tools. It assumes you know nothing about the launcher (as if you just installed it) although some steps not related to scripts are not explained in detail. If you want to know more about creating scripts or other ways to import them, check the wiki.
--------------------------------------------------------------------------------------------------------

So, you saw that Lightning is capable of running 'scripts' and you want to try one you saw on this forum or in the script repository, or something someone made for you. But you don't know what to do! Don't worry, here I'll explain the steps required to 'install' (import is a better word) and run any script you can copy/paste.

Let's assume you have this super-useful script:

Code: Select all

//example script
var msg = "Hello World"
alert(msg);

1) Copy the script:
Copy the full script to your clipboard: long tap and copy, click a copy-all button if available, whatever you can use so that in next steps you can paste it. Don't forget any line or characters, also don't add anything else besides the script code! Even a missing " or an added 'h' can make the script unusable.



2) Open the script editor:
You can open it by using a shortcut, using a gesture, another script...in Lightning you can run almost anything from almost everything. The easiest way however is to use the app shortcut from the app drawer.
sc1.png
sc1.png (110.68 KiB) Viewed 317 times


3) Create a new script:
The main screen of the script editor is the text editor. This is where you will spend most of the time if you are creating your own scripts, but first we need set up a few things. To open the editor menu you need to swipe from the left edge (as explained in the top).
sc2.png
sc2.png (49.22 KiB) Viewed 317 times
In this menu you can change the properties of the currently displayed script (the name displayed at the top), create or delete more scripts, and other 'script related' actions. If this is your first script you can see there is already an untitled one, you can use it, but remember to change the name to something more 'recognizable' (by clicking the pencil button at the top). If however you already have one or more scripts, you just need to click the 'new' button to create a new empty one, write a name, and press ok. Don't worry about the path, unless you have a lot of scripts and you want to organize them in folders.
sc3.png
sc3.png (50.19 KiB) Viewed 317 times


4) Set its properties:
Don't close this menu yet! One of the most important properties of scripts are the categories they belong to. There are three categories:
  • Lightning menu: scripts from this category will be shown when long clicking a container (desktop, panel, folder). Normally scripts that edit containers (adding/removing items) or that change some properties of them.
  • Item menu: scripts from this category will be shown when long clicking an item. Normally scripts that change properties of items.
  • Custom menu: scripts from this category will be shown when running the 'custom scripts menu' action. Normally utility scripts that change properties of the launcher or simply show something to the user.
The categories you need to check should be explained in the script page (where you copied it). If however they aren't or you are not sure, you can check all 3, the script will work fine but if you mark all 3 on all scripts they will be more difficult to find in the long lists. A script without any category checked can still be launched from an action or from another script though.
For this example I'll mark all three.
sc4.png
sc4.png (25.08 KiB) Viewed 317 times


5) Paste the script:
Now you can close the menu (simply slide left) and the text editor should be empty (if it is not you probably forgot to create a new script! check step 3). Click the textbox, and paste. The script will be shown line by line, remember to paste the whole script without any line/character missing!
You can close the editor now by pressing 'back' or 'home'. Don't worry about saving it, it is saved automatically.
sc5.png
sc5.png (30.2 KiB) Viewed 317 times


6) Run the script:
There are a lot of ways to run scripts, I'll explain the most common ones:

6.1) Run from an item:
To run the script from an item you just long tap the item, then choose 'Scripts...' (if you don't see that option you are probably in edit mode, exit it or click on 'Actions...' first), and finally click on the script name you defined. If you can't see the script in the list be sure to go back to the script editor and check that the 'Item menu' category is enabled, and that the script has the name you are expecting. If you still can't see the script make sure you are long tapping an item, the popup menu should say something like "Shortcut 'name' (#123456)".
sc6.png
sc6.png (84.16 KiB) Viewed 317 times

6.2) Run from a container:
To run the script from a container just long tap an empty space of the container, then choose 'Scripts...', and finally click on the script name you defined. If you can't see the script in the list be sure to go back to the script editor and check that the 'Lightning menu' category is enabled, and that the script has the name you are expecting. If you still can't see the script make sure you are not long tapping an item, the popup menu should say something like "Desktop 'name' (#123456)".
sc7.png
sc7.png (72.78 KiB) Viewed 317 times

6.3) Run from the custom scripts menu:
To open that menu you need to launch the Lightning action 'Custom scripts menu', either by adding a shortcut [long tap desktop, + button, Lightning action, Custom scripts menu] or from an event [long tap, pencil button, properties, swipe until 'events' or go to settings and events&actions, Lightning action, Custom scripts menu]. After launching the action a list of scripts will be shown, then choose the script. If you can't see the script in the list be sure to go back to the script editor and check that the 'Custom menu' category is enabled, and that the script has the name you are expecting.
sc8.png
sc8.png (56.93 KiB) Viewed 317 times

6.4) Run from an event:
You can run scripts directly from gestures, for example when swiping left, when a container is resumed, etc. Perhaps the script you are running is needed in one of those events, as you can even specify additional data (script data). Simply go to the event you want to set [long tap, pencil button, properties, swipe until 'events' or go to settings and events&actions] and choose the action 'run a script'. Then find the script by its name (here is shown all scripts available regardless of their categories) and optionally, if required, press the 'script data' checkbox and write something the creator of the script told you to write as 'script data'. Ok and done. This can even be set with other apps as a normal shortcut!
sc9.png
sc9.png (42.86 KiB) Viewed 317 times


7) Troubleshooting:
If everything went correctly, the script should now run and do whatever it was meant to do. In the example it shows a dialog saying hello to the world (no, the message is not duplicated, the top one is the name of the script, the second one is the message) that you can close with the ok button (don't press the 'disable' one! it will disable the script so it can't be run again, this is meant for scripts that under wrong circumstances can become stuck and show a dialog after another infinitely. Check 7.1 below).
sc10.png
sc10.png (52.58 KiB) Viewed 317 times
If however the script doesn't run, here are some of the most common errors:

7.1) Nothing happens:
First, make sure that *nothing* happens, some scripts don't notify anything to the user but they do run and do things in background. If however you are sure the script is not running (for example if you know it should show a dialog but it doesn't) perhaps you disabled it by mistake by clicking the disable button. To enable a script again just open the script editor and choose the script, as soon as the script is shown in the editor it is enabled automatically. Close and try again.

7.2) "At line X: Error: some error":
If you see a dialog with a similar message, it means the script couldn't run correctly. The most probable cause is that you pasted it incorrectly and missed some lines or characters, or you added some by mistake. If you know a bit about javascript you can try to find it (the error message can help you) but otherwise it is better to just clear the editor and copy/paste it again (no need to delete and create a new script, although it can help in some very specific cases). If it still makes an error perhaps the error is from the script itself (specially if the script is an old one from the repository). In that case try to contact the author for help or write a post in the bug report forum specifying the script you are trying to run, the device and android version you are running, and the steps you are following that leads to the error.

7.3) The launcher crashes:
If the launcher crashes when running the script...that script is not doing things correctly. Perhaps it is very old and using something that isn't supported on newer android versions, perhaps the script is wrong coded, or maybe your device/version is incompatible with some of the functions. In either case you can do as in 7.2: try to fix it yourself or ask for help in the bug report forum specifying the script you are trying to run, the device and android version you are running, and the steps you are following that leads to the error.

7.4) Other:
If you have any other error, or question you can post it in the bug report forum specifying the script you are trying to run, the device and android version you are running, and the steps you are following that leads to the error.



And that should be all. I hope this tutorial was useful, but if you have troubles with something or even you have suggestions to improve it (some steps are not clear? incorrect images? grammar mistakes?) I'll be happy to hear them!

ralvy
Posts: 16
Joined: Mon Feb 18, 2019 6:08 pm

Re: Tutorial: How to manually 'install' and run scripts

Post by ralvy » Sat Feb 23, 2019 10:44 pm

Thank you!

User avatar
JayM
Posts: 34
Joined: Tue Jan 29, 2019 11:57 pm

Re: Tutorial: How to manually 'install' and run scripts

Post by JayM » Sun Feb 24, 2019 3:55 pm

nice work bet this took a while to put together.

User avatar
Pierrot
Site Admin
Posts: 160
Joined: Wed Jan 23, 2019 12:18 pm
Location: French Alps

Re: Tutorial: How to manually 'install' and run scripts

Post by Pierrot » Sun Feb 24, 2019 6:40 pm

Great tutorial, extensive and clear! This is also a good introduction on how to write scripts, just before to dive in the javascript code.
The only typo I could find is at: 7) If everything were -> went
But that's really to find a mistake because your tutorial is really good.

User avatar
TrianguloY
Posts: 77
Joined: Thu Jan 24, 2019 9:46 am

Re: Tutorial: How to manually 'install' and run scripts

Post by TrianguloY » Sun Feb 24, 2019 7:01 pm

(fixed!)
Thank for the comments, yes it took a bit (as you can see in the screenshots with the time/date lol, plus some days before thinking about the idea) but I was having fun so I don't mind. I wanted to make something like this to avoid having this information repeated in other scripts posts, so if someone asks you can simply link here. I wasn't sure if there is any existing tutorial (didn't find on the wiki or google+, although I may have missed it) so I made it. If there is please say so (specially if it is a video!) so I'll add it.

brunoisa10
Posts: 86
Joined: Sun Jan 27, 2019 7:31 pm
Location: Westende Belgium

Re: Tutorial: How to manually 'install' and run scripts

Post by brunoisa10 » Mon Feb 25, 2019 2:00 pm

nice tuto :)
Bruno 8-)

Post Reply