PageRenderTime 28ms CodeModel.GetById 2ms app.highlight 21ms RepoModel.GetById 2ms app.codeStats 0ms

/README.md

https://github.com/deanishe/alfred-searchio
Markdown | 164 lines | 117 code | 47 blank | 0 comment | 0 complexity | 38e26c9ea3846a2f646c18db26bd35ac MD5 | raw file
  1Searchio! workflow for Alfred
  2=============================
  3
  4Auto-suggest search results from multiple search engines and languages.
  5
  6![Searchio! Demo][demo]
  7
  8
  9Contents
 10--------
 11
 12<!-- MarkdownTOC autolink="true" bracket="round" depth="3" autoanchor="true" -->
 13
 14- [Download and installation](#download-and-installation)
 15- [Usage](#usage)
 16    - [Configuration](#configuration)
 17        - [Workflow Configuration Sheet](#workflow-configuration-sheet)
 18        - [In-Workflow Configuration](#in-workflow-configuration)
 19    - [Importing Searches](#importing-searches)
 20- [Adding Engines](#adding-engines)
 21- [Licensing, thanks](#licensing-thanks)
 22
 23<!-- /MarkdownTOC -->
 24
 25Supports the following search engines/websites:
 26
 27- Amazon
 28- Bing
 29- DuckDuckGo
 30- DuckDuckGo Image Search
 31- eBay
 32- Google
 33- Google "I'm Feeling Lucky"
 34- Google Images
 35- Google Maps (requires a Google Places API key)
 36- Naver
 37- Wikia (only the top ~200 wikis, but you can [import](#importing-searches) any others)
 38- Wikipedia
 39- Wiktionary
 40- Yandex
 41- YouTube
 42- **plus** it can [import a search configuration](#importing-searches) from *any* website that supports OpenSearch autosuggestions
 43
 44
 45<a name="download-and-installation"></a>
 46Download and installation
 47-------------------------
 48
 49Download the latest version from the [GitHub releases page](https://github.com/deanishe/alfred-searchio/releases/latest).
 50
 51
 52<a name="usage"></a>
 53Usage
 54-----
 55
 56There are several example searches pre-configured:
 57
 58- `g` — Search Google in English
 59- `gd` — Search Google in German
 60- `w` — Search the English Wikipedia
 61- `wd` — Search the German Wikipedia
 62- `yt` — Search the United States version of YouTube
 63- `ytd` — Search the German version of YouTube
 64
 65
 66<a name="configuration"></a>
 67### Configuration ###
 68
 69The workflow is configured via the `searchio` keyword and some [workflow variables](https://www.alfredapp.com/help/workflows/advanced/variables/) set in the workflow configuration sheet.
 70
 71
 72<a name="workflow-configuration-sheet"></a>
 73#### Workflow Configuration Sheet ####
 74
 75There are some variables in the workflow configuration screen (open the workflow in Alfred Preferences and hit the `[𝒙]` button):
 76
 77|           Name          |                                                                                                    Description                                                                                                    |
 78|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 79| `ALFRED_SORTS_RESULTS`  | Set to `1` or `yes` to enable Alfred's knowledge. Set to `0` or `no` to always show results in the order returned by the API.                                                                                     |
 80| `GOOGLE_PLACES_API_KEY` | You must set this to use Google Maps search. You can get an API key [here](https://developers.google.com/places/web-service/get-api-key).                                                                         |
 81| `SHOW_QUERY_IN_RESULTS` | Set to `1` or `yes` to always append the entered query to the end of the results (so you can hit `↑` to select it). If unset (or set to `0` or `no`), the query will only be shown if there are no other results. |
 82
 83
 84<a name="in-workflow-configuration"></a>
 85#### In-Workflow Configuration ####
 86
 87- `searchio [<query>]` — Show workflow settings
 88    - `Update Available …` — Shown if there is a new version of the workflow available to download. Action the item to install it.
 89    - `Installed Searches …` — View and delete your configured searches
 90    - `All Engines …` — View supported engines and add new searches
 91    - `Import Search …` — Import a new search configuration from a URL (see [Importing Searches](#importing-searches))
 92    - `Reload` — Regenerate the workflow's Script Filters from your configured searches (and clean the cache). Run this if you screw up the Script Filters or an update overwrites them.
 93    - `Show Query in Results` — Turn the option to show the query you entered in the results on/off. The query is added to the end of the results, so you can hit `↑` to go straight to it. The query is always shown if there are no other results.
 94    - `Alfred Sorts Results` — Turns Alfred's knowledge on/off. If on,
 95    Alfred remembers which result you chose for which query and moves
 96    that result to the top. If off, results are always shown in the
 97    order they are returned by the API. If on, `Show Query in Results`
 98    cannot guarantee that the query is always the last result.
 99    - `Online Help` — Open this page in your browser.
100    - `Workflow up to Date` — You have the latest version of the workflow. Action this item to force a check for a new version.
101
102
103<a name="importing-searches"></a>
104### Importing Searches ###
105
106Searchio! has the ability to import a search configuration from any website that supports the OpenSearch autosuggestion API.
107
108Run `searchio` > `Import Search …` and the workflow will offer to import a search from a URL on your clipboard, the frontmost Safari tab or the frontmost Chrome tab.
109
110It will try to find and read the OpenSearch description at the URL and import it (and the website's icon if available), then ask you to assign a keyword for the search.
111
112**NOTE**: Although many websites support OpenSearch, few support the autosuggestion API that Searchio! uses. Sites based on MediaWiki usually support the API, so you can add all your favourite Wikia wikis (the built-in Wikia engine only supports the few hundred most popular wikis).
113
114
115<a name="adding-engines"></a>
116Adding Engines
117--------------
118
119In addition to the built-in engines, you can add your own definitions in the `engines` folder in the workflow's data directory. (Enter `searchio workflow:opendata` to open the data folder in Finder.)
120
121An engine definition looks like this:
122
123```json
124{
125  "description": "Alternative search engine",
126  "jsonpath": "$[*].phrase",
127  "title": "DuckDuckGo Images",
128  "pcencode": false,
129  "variants": [
130    {
131      "name": "Argentina",
132      "search_url": "https://duckduckgo.com/?iax=images&ia=images&kp=-2&kz=-1&kl=ar-es&q={query}",
133      "suggest_url": "https://duckduckgo.com/ac/?kp=-2&kz=-1&kl=ar-es&q={query}",
134      "title": "DuckDuckGo Images Argentina",
135      "uid": "ar-es"
136    }
137  ]
138}
139```
140
141`title` and `description` are self-explanatory. `jsonpath` is the JSON path expression that extracts the search suggestions from the JSON returned by the suggestion API.
142
143The optional `pcencode` field tells Searchio! to percent-encode the search query rather than use plus-encoding (the default).
144
145`variants` define the actual searches supported by the search engine, typically one per region or language. All fields are required. `suggest_url` points to the autosuggestion endpoint and `search_url` is the URL of the search results that should be opened in the browser. Both URLs must contain the `{query}` placeholder, which is replaced with the user's search query.
146
147The (optional) icon for your custom engine should be placed in the `icons` directory alongside the `engines` one. It should have the same basename as the engine definition file, just with a different file extension. Supported icon extensions are `png`, `icns`, `jpg` and `jpeg`.
148
149<a name="licensing-thanks"></a>
150## Licensing, thanks ##
151
152The code in this workflow is released under the [MIT Licence](http://opensource.org/licenses/MIT).
153
154The icons belong to the respective search engines and websites.
155
156This workflow uses the following libraries:
157
158- [Alfred-Workflow](https://www.deanishe.net/alfred-workflow/)
159- [AwGo](https://github.com/deanishe/awgo/)
160- [BeautifulSoup](https://pypi.org/project/beautifulsoup4/)
161- [docopt](http://docopt.org/)
162- [jsonpath-rw](https://pypi.org/project/jsonpath-rw/)
163
164[demo]: ./docs/demo.gif