URL & local first client side actions for the browser omnibox
GPL-3.0 License
Check the other files of this folder for more documentation.
Web browser URL search engine utility to customize the omnibar actions.
It is built as a single importable file, without dependency, that can run in web browsers and node.js javascript contexts.
It is distributed as a website, javascript class, npm package and git repository.
To install and use a personal/community instance, follow the installation/deployment guides.
To make Find the default search engine of a web browser:
Alternatively, adding manually the search engine could be done with this open search browser config:
Search engine: `Find`
Keyword: `f`
Query URL: `https://internet4000.github.io/find/#q=%s`
The mobile installation is not the easiest, but works on Firefox; web-browsers are making their bread and butter on the default search engines, and our queries; so they sometimes make changing it slightly annoying.
All find "search queries" or "commands", are to be run in the browser omnibox, or a find search input.
A "find search query" is a string of text, which "Finds tries to decode", to find some syntax it knows, to build (destination) URLs (what the user is requesting).
The user query string, is splitted into a list of strings, for every
white space, and from there, find looks for a "symbol", probably the
first character of the first string, for example !
, or +
.
It then looks for an "engine ID", for example m
in the user query
starting with !m
.
The last part, are the user arguments to the the requested destination URL/web-application.
For example !m tokyo
in order to search (!
) for "tokyo" on the
map application (m
).
If the query we write in Find starts by one of these symbols, Find will try to decrypt the user query to see if it can do something with it.
All available symbols are:
!
= search+
= action&
= build#
= command (no custom engines)Symbols are a way to give semantic meaning to engines. It should help organize what the engines do, what parameter and query they can accept.
For an up-to date list of default engines by symbols, look at the index.js
file.
All these symbols can be overwritten by the user, and new ones can be added.
These engines are stored under this !
symbol, because they provide
search results, from your query.
!c <query>
- contacts.google.com!d <query>
- duckduckgo.com!dd <query>
- devdocs.io!dr <query>
- drive.google.com!m <query>
- maps.google.com!osm <query>
- openstreetmap.org!w <query>
- en.wikipedia.org!y <query>
- youtube.comThese engines are stored under this +
symbol, because they will allow you to
complete an action; add a item to a library, create a drawing, find a random
image or text etc.
+r4 [url]
- add a new track to a radio4000, from a youtube URL+draw [title]
- open a new drawing in Google Drive Draw+doc [title]
- open a new Google Docs document+sheet
- open a new Google Spreadsheets document+gmail
- open a new Gmail (Google Mail) email+wr
- random wikipedia article+wri
- random wikipedia image media+r4p
[radio] - play a radio4000 radio+r4pr
[radio] - play a random track from a radio4000 radioThese engines are stored under this &
symbol, because the parameters
taken by the engines allows you to build complex URLs.
&gh [actor] [repo]
- github/[actor]/[repo]&gl [actor] [repo]
- gitlab/[actor]/[repo]&firebase [project]
- firebase/[project]&netlify [project]
- netlify/[project]&r4 [radio]
- radio4000/[radio]This is a special symbol, for command functions within find.
#add <symbol> <engine-id> <engine-url>
adds a custom engine, by its engine-id
, under a specific symbol
#add ! gh https://github.com/search?q=
#del <symbol> <engine-id>
deletes a custom engine, by its engine-id
, under a specific symbol
#del ! gh
It is possible to customize the default search engine used by find.
We have to overwrite the engine under the id d
(!d
; d for default).
For this we can use the following "find command", to make Google our default search engine.
#add ! d https://encrypted.google.com/search#q={}
To use these triggers, for exemple with the search query foo
:
!keyword
(the website on which you want to!y
for Youtube), prefixed with a !
.space
(just normally as in between twofoo
!y foo
(there!y
and foo
).enter
(the return key), to validate our search.foo
.Note: in the exemple above Find!
is considered to be our default
search engine. If it is not, and you use it as one of Firefox's "one click
search engine", or Chrome/Chromium's "other search engine", you have
to follow the same steps as above but as a first step you need to
trigger the search Find!
search engine ("Tab" key in Firefox /
"one space" in Chrome/ium, after writting the keyword).
The interest of Find is the possibility to add a custom engines, and replace the default ones depending on our preferences.
There are different ways to add engines (works for all symbols, but #
):
#add
commandFind
object in the browser console (Try: Find.help()
)to sync
custom engines between devices, we use a trick with the password manager, and take advantage of the user usual way to synchronise credentials between their devices.
This operation currently overwrites existing user defined engines, when importing new ones (in does not merge them).
The imported data, is written as the new user defined engines, and saved to local storage for this browser.
search
engine urlsfoo
in thefoo
in it (usually after a parameterq
, or query
, but it could be a different pattern). Copyscheme://
to foo
(excluded).Note that you can also use the information stored in the
.xml
file possibly used by websites to define theirOpen Search Description
. To do that, inspect the HTML code of the site you want to add and search for a HTML link tag with the folloing type:application/opensearchdescription+xml"
. The file it points to will have the infortmation you are looking for in theUrl
XML tag.
Find has different interfaces, some of which can be used programatically (better than others):
I4kFind
Javascript class exported by the package (and.find("my query")
public method)./src/ui/index.js
, and all./service-worker.js
client side OpenSearch suggestionsassets/opensearch.xml
to fit the URL address of theThis software does not collect any data, there are and should be no analytics functionalities on the user queries and usage.
It stores in the browsers local storage (could be improved, or enhanced), only the user defined customization(s).
There is a cloudflare analytics beacon.
It sends a HTTP get request, to cloudflare, to check if it can. If it can, it warns the user that they should install a "blocker" with instructions.
If the HTTP request succeeds (user has no advert blocker), Cloudflare, eventually must be saving the "request information", for a certain amount of time.
The user query is (and should) never be shared with Cloudflare, the
#
param where the user request, always stays on the client side of
the browser.
It is used to warn the user:
When making a search to an instance of find, the user query is passed to the client side application, and never to the server.
The query should never leave the user browser (and reach the server
hosting the site serving the Find webpage and code), as it is passed
to the browser as value of the hash
parameter.
This should help protect more the privacy of the user, as the value of
the hash
parameter in a URL, does not "leak the user query" to the
server it is hosted on (or any third party; there are none, except the
Cloudflare beacon, which can be removed; @TODO: add flag to local
storage to not even insert; but need to define first user settings,
more than just the custom engines).
#
#q=
?
?q=
, butThe easieset way to start debugging is from the developer tools of a web browser. Because Find is unminified javascript code, it is possible to look at what read what the code does and where it fails. You can for example use a debugger to follow how a query is translated.
From a browser we can look at it like so:
.
In firefox omnibar, we can use the prefixes:
* to search for matches in bookmarks
% to search for matches in currently open tabs
^ to search for matches in browsing history
> to search for marches in firefox actions
+ to search for matches in tagged pages
# to search for matches in page titles
$ to search for matches in web addresses (URLs)
? to search for matches in suggestions