Locu is an iOS app that helps with opening your daily URLs in a more flexible and faster way.
Following is the detailed help information for it.
Say you want to search in Google, with a preferred language for the resulting pages.
In Google's advanced search page, you can do that.
Then the normal way to do it is:
- open the advanced search page
- pick the preferred language
- input the keywords
- confirm to launch the search
This would be tedious if you have to do them every time.
You can add a command in Locu, set its keyword as “g”, and set its URL as following:
https://www.google.com/search?q={,-2:Q}&lr=lang_{-1:Q}
From now on, when you want to search, say “Greek myth”, and show pages in Simplified Chinese, you can just type in the following invoking text:
g Greek myth zh-CN
Locu will invoke the command you just added, and open the browser with the expected search results.
As can be seen, Locu turns opening your daily URLs into running invoking text.
Using of Locu involves the following steps:
- you add and configure URLs into Locu as commands
- you type in the invoking text
- Locu filters and shows the matching commands according to the keyword
- you tap to invoke a command
- Locu interprets arguments in your text and translates the URL to the final form
- and Locu opens the translated URL in its handling app
You configure a command to customize an URL visiting.
A command consists of the following attributes:
- enabled
- whether the command is effective or not (not implemented yet)
- keyword
- the keyword identifying the command
- required
- should be unique in Locu
- no spaces allowed
- URL
- the URL will be opened
- required
- contains argument tokens to obtain the respective arguments from the invoking text
- title
- the name of the command
- required
- will show as the title in the command entry
- description
- the detailed description of the command
- argument tokens can also be used to display dynamic information
- author
- the name of the author of this command
- contact
- the contact information of the author
You express your purpose and pass arguments to URLs by typing in a line of invoking text in Locu.
Here is an example of invoking text:
kw hello world I\’m here ‘where are you?’
0 1 2 3 4 5
Its components are separated by spaces or escaping.
3 types of escaping are supported:
- backslash:
- the immediate following character will be treated as it is.
- single quotes:
- the quoted characters will be treated as one whole component.
- double quotes:
- the quoted characters will be treated as one whole component.
After escaping, the components will have their respetive position (tagged below each component in above example):
- position 0 is always the keyword of the invoking text
- keyword will be used to filter and sort the command list
- the title and description of a command will be used to match it when there is no exact matching for keyword
- the following positions are arguments
- arguments will be interpreted and substituted to form the final URL of a command
Therefore, the above example contains 6 components:
kw
is the keywordI'm
is a whole component because its single quote has been escaped by the backslashwhere are you?
is treated as one component thanks to the surrounding single quotes
As mentioned above, other components than the keyword in the invoking text will be interpreted as the arguments.
At the URL end, argument tokens are used to express the substitution intension.
In the above Google searching example, {,-2:Q}
and {-1:Q}
are two argument tokens. Which will be replaced by relative arguments.
So far, the following argument tokens are supported (the above invoking text is used to help with the explanations):
- {@}
- all the arguments
hello world I’m here where are you?
- {n}
- number n represents the position of the component
- negative positions mean ones in the opposite direction
- {4} means
here
- {-2} means the last second component thus equals to {4} in the example
- {n,m}
- components in range from poistion n through m
- negative positions are supported too
- if n is omitted, it is filled by the beginning
- if m is omitted, it is filled by the end
- if the range is illegal, it will be empty
- {1,2} means
hello world
- {,-2} means
kw hello world I'm here
- {4,} means
here where are you?
- {2,1} will be empty since it is invalid
- {name}
- the named argument
- it represents the argument immediate following the first name component
- if no matching name component, it will be empty
- the keyword will never be counted as the name component
- {world} means
I'm
- {kw} will be empty
- {!name}
- all arguments except for the named argument part
- the name component and its immediate follower will be excluded
- {!I'm} means
hello world where are you?
- others
- will be interpreted as empty strings
When the argument tokens are used in URLs, they need to be percent escaped to ensure the URL's validity.
Locu is smart enough to do this for you (since version 1.2). It will figure out the URL component to which each token belongs, and do the escaping automatically when the command is being launched.
However, you can still indicate the escaping explicitly when it is necessary. The URL escaping attributes can be added within a token by appending them with a colon (:Q
part in {,-2:Q}
).
The following attributes are supported:
- H
- escape for the URL host
http://www.abc{1:H}.com
- PT
- for the URL path
http://www.abc.com/search{2,3:PT}
- Q
- for the URL query
http://www.abc.com/search?q={@:Q}
- F
- for the URL fragment
http://www.abc.com/search?q=blah#fragment{3:F}
- U
- for the URL user name
http://{user:U}@www.abc.com
- PW
- for the URL password
http://user:{pwd:PW}@www.abc.com
- NA
- do not escape
- some components, such as scheme and port, inherently don't need escaping
{2:NA}://www.abc.com
- when omitted, it escapes for query part by default
http://www.abc.com/search?q={@}
- argument tokens don't need percent escaping when used in description
NOTE: Locu stops doing the automatic escaping whenever any of the tokens contains an explicit escaping attribute.
Locu will maintain a history list recording every invoking text that has been invoked.
You can re-type a piece of invoking text by just choosing a history entry:
- dragging down the command list will reveal the history list
- each entry has the invoking text on the left side and relative timestamp on the right
- releasing will select the highlighted entry
- when revealed lines exceeds 5, the history window will be open
- scrolling in the window offers a faster history navigation
- clicking to select one entry and close the window
- simply swipe up the command list will close the window
Of course useful Locu commands can be shared among friends.
And the sharing is very easy because it is operated via QR code:
- to export
- swipe a command to left to reveal its action buttons
- choose
More
to invoke its action sheet - choose
QR Code
to open its QR code page - in this page, you can scan the QR code or export it to other apps
- to import
- tap the
+
button to invoke the adding menu - choose
Capture QR Code
to open the QR code scaning page - point the camera to a Locu command QR code will add the command automatically
- you may need to do some editing before you can import a command when it has some problems
- tap the
Besides typing invoking texts within Locu, there are some other ways to utilize it:
- share extension
- in apps that support text sharing, the text can be shared with Locu as the invoking text
- you can edit the text before posting, then Locu will try its best to invoke it
- spotlight search
- you can search Locu's commands with keywords input into the spotlight search
- choose a command from the list will open Locu and with its keyword already there
- today widget
- Locu's today widget has 3 buttons
|
: open Locu and start typing^
: invoke the last entry in historyqp
: try and invoke the text in system clipboard
- URL scheme
- Locu also supports some custom URL schemes
- input
locu://input/?text=textToType
- Locu will open and have
textToType
input in the search bar
- run
- text
locu://run/?text=textToRun
- Locu will try and invoke
textToRun
as the invoking text
- history
locu://run/?history=historyNumber
- Locu will try and fetch the history entry at position
historyNumber
, then invoke it
- clipboard
locu://run/?clipboard=system
- Locu will try and invoke the text in system clipboard
- text
- add
locu://add/?kw=keyword&url=URL&t=title&dsc=description&au=author&co=contact
- Locu will try to add a new command with the given parameters
- please refer to the command attributes for detailed information
- further editing may be needed if problems happen
In the search bar, if you type double spaces immediate following the keyword, Locu will replace the current keyword with the topmost command's.
If you have any issues, suggestions or requests, please contact @jixiewu