Swift Selection Search (SSS)
Options

Instructions
Quick setup
  1. Add new search engines using the Add engine button in the Search engines section below. SSS comes with a few examples! You can also load engines from Firefox (the ones used in the search bar).
  2. Engines appear in a popup and/or context menu when you select text on a page. When you click one, the search URL you defined is called and {searchTerms} gets replaced by whatever text is selected.
  3. For customizing popup look, context menu, click behaviour, etc, please explore the options in this page. ;)
Problems?
  • Some blocking lists in your ad blocker can stop certain search engine icons or names from loading! If an icon doesn't show up, please check that. (ex.: YouTube may be blocked by Fanboy's Annoyance List. Sometimes simply renaming "YouTube" to something else like "YouTub" works too!)
  • If the popup appears when you pause/unpause a YouTube video, it's because you slightly moved the mouse and selected the country code beside the YouTube logo at the top. ;) Annoying, I know! Try setting the "Minimum selected characters" setting to 3, or use an "Opening behaviour" that isn't "Auto".
  • Some search engine icons may not appear if they are resource:// links (some imported engines have those). This is normal, unfortunately. Please try finding another icon for the engine, or delete the icon link and SSS will try getting it for you.
  • If the popup does not appear at all on a website or parts of a website, it may be due to that site's content policy. For example, addons.mozilla.org disables page modifications, and bugzilla.mozilla.org can block images.
  • Is your problem not here? Please go to SSS's page on Mozilla Add-ons and check how you can report it.
I don't know how to add a particular site...
[Press to expand/collapse]
  • It's not always easy to figure out! I'll try to help. :)
  • After using a search bar on a website, the site will usually place what you searched for in the URL somewhere. For example, if you search for Firefox Add-ons on Google, Google adds q=Firefox+Add-ons to the URL (among probably a lot of other things). q is the parameter Google uses for user queries. Other sites will use different structures, but what you wrote should be there (unless the site uses POST requests, but that's another story!).
  • SSS needs a search URL that says {searchTerms} in the part where your query usually goes. In the previous example, that means replacing q=Firefox+Add-ons with q={searchTerms}.
  • Tips
    • Check the search URLs of the search engines that come with SSS! They may help.
    • Many websites use the ? symbol and then add a lot of parameters separated with the & symbol. You'll usually be looking for the parameter that represents your query and replacing that with {searchTerms}.
    • Most of the time, the URL also contains a lot of unnecessary parameters. Removing them is mostly trial and error.
    • Sometimes it's not a parameter, and sometimes it's in another place in the URL. Sometimes websites are complicated. :(
Advanced usage
[Press to expand/collapse]
  • You may notice that when you select a search engine in the list of engines it expands and can show additional options. One of these is the "Text encoding" option. Being able to change the encoding is sometimes essential for websites that use non-latin alphabets like Japanese, Chinese, etc. If you run into problems with such websites try changing the encoding from UTF-8 to a more adequate one (it depends on what encoding the website uses for its search!).
  • Most JavaScript URL properties are available for search URLs as {hash}, {host}, {hostname}, {href}, {origin}, {password}, {pathname}, {port}, {protocol}, {search} and {username}. For example, if {hostname} is present in the search URL when searching, it will be replaced by the website domain you are on (ex.: google.com).
  • Variables such as {searchTerms} and the JavaScript URL properties (like {hostname}, {href}, etc) support text replacements in the format {variable{original text|new text}}, allowing multiple pairs of {original text|new text}.
    • So if you want to always replace spaces in your search with "+", and "@" with "at", you can use {searchTerms{ |+}{@|at}} in your search engine.
    • Since SSS uses the special characters \, {, |, and } for delimiting the replacements, if you want to use these characters in the replacement itself, you should precede them with a \. This is called "escaping characters". For example, {searchTerms{\{|\}}} replaces { with } in your text and {searchTerms{ |\\}} replaces spaces with a \ (yes, that is hard to read!).
    • Replacements can also be regular expressions. If you don't know these, it's okay. It's way beyond the scope of these instructions to explain them.
      • These come in the form of either {searchTerms{re/your_regex_here/flags_here}}, where the selected text will be replaced with only the characters that match the expression, or {searchTerms{re/your_regex_here/flags_here|replacement}}, where the match will be replaced with the replacement. If you use the g flag that matches all occurrences, each of them will be replaced with the replacement.
      • Replacements support match groups, so $1 in the replacement corresponds to the first match, $2 to the second, etc.
      • As examples, if you want to remove all non-alphanumeric characters from the searchTerms you can use {searchTerms{re/[0-9a-z]/gi}} (g finds all matches and i is case insensitiveness). To find words separated by spaces and switch them you can use {searchTerms{re/(\w+)\s+(\w+)/g|$2 $1}}. This will transform any two words like "John Smith" into "Smith John".
  • Variables support using only part of the selected text with the indexing format {variable[index]} or {variable[start:end]} (start and end both optional).
    • {searchTerms[index]} allows selecting a character at a certain position (zero based), so if you search for "Firefox" and use {searchTerms[0]} you will get "F", and if you use {searchTerms[2]} you will get "r".
    • {searchTerms[start:end]} is for multiple characters, so {searchTerms[0:2]} for "Firefox" gives you "Fi", {searchTerms[2:5]} gives you "ref", {searchTerms[2:]} gives you "refox", and {searchTerms[:5]} gives you "Firef".
    • Indexing with negative numbers is also allowed, where {searchTerms[-1]} gives the last character of the selected text, and {searchTerms[-3:]} gives the last three.
  • Variables support a few functions. These are in the format {variable(function_name)}.
    • {searchTerms(lowercase)} and {searchTerms(uppercase)} respectively convert the text to lower case and UPPER CASE.
    • {searchTerms(encodeURIComponent)} applies URL encoding to the text, replacing forbidden URL characters with their escaped versions. For example, % is replaced by %25, / is replaced by %2F, etc. NOTE: SSS always applies URL encoding after all replacements happen (otherwise the URL could have invalid characters), so this function should be used only for the rare sites that apply encoding more than once, or apply encoding and then do additional modifications.
    • {searchTerms(disableURIEncoding)} disables the default URL encoding that is otherwise always applied to the final text. This is useful for websites that search for links. For example, the Internet Archive website can search for https://www.mozilla.org but not for https%3A%2F%2Fwww.mozilla.org (the result of the encoding), so you should use disableURIEncoding.
  • Any variable modifications mentioned above (replacements, indexing, functions) can be used in conjunction. So something like {searchTerms[2:5]{ |+}{@|at}(lowercase)} is valid and will apply each modification in the given order, so first selecting only characters 2, 3 and 4, then converting any spaces and @, and then converting the result to lowercase. (The only exception is disableURIEncoding, whose order doesn't matter.)
Search engines
P.
C.
Name
Search URL
Icon URL
S.
Import browser search engines
Imports the search engines that you usually use in the browser's search bar.

NOTE: These engines are managed by Firefox and so they can't use some SSS settings. For example, browser engines only respect "Open in this tab" or "Open in new tab" (other click behaviours behave as "Open in new tab").
Reset search engines
Resets search engines to the defaults (as if running SSS for the first time).
Source for automatic icon URLs
Defines the origin of automatic search engine icons when you add a new engine. Change this option if you have privacy concerns or would prefer to add all icons yourself.
Popup/icons behaviour
Opening behaviour
When to open the popup.
Popup location
Where the popup should appear after selecting text.
Left mouse button click
What to do when a search engine is clicked with the left mouse button.
Right mouse button click
What to do when a search engine is clicked with the right mouse button.
Middle mouse button click
What to do when a search engine is clicked with the middle mouse button.
When using a shortcut
What to do when searching via shortcut. Also applies when selecting the engine with the TAB key.
Allow popup on editable fields
Show the popup when text is selected with the mouse on an editable text field, such as a login form, a search bar, or an email composing window. NOTE: "Shortcut to open popup" ignores this option and always works on editable fields.
Hide popup on page scroll
Hides the popup when the page moves.
Hide popup on right click
Hides the popup when the right mouse button is pressed outside of the popup. NOTE: Left or middle clicks always hide it regardless.
Hide popup on search engine click
Hides the popup when a search engine is clicked. This also applies when using shortcuts.
Allow search engine shortcuts without popup
Enables search engine shortcuts even if the popup is not visible.
NOTE: A shortcut will not work if the engine is not enabled for the popup (even though the popup isn't needed). They also won't work when writing in an editable field.
Shortcut to open popup
--
To change this shortcut, use Firefox's "Manage Extension Shortcuts" menu.
Default value is Ctrl+Shift+Space (NOTE: for Mac, Ctrl means Command).
Shortcut to toggle auto popup opening
--
To change this shortcut, use Firefox's "Manage Extension Shortcuts" menu.
Default value is Ctrl+Shift+U (NOTE: for Mac, Ctrl means Command).
Popup animation duration
Duration of popup animation, in milliseconds. Use 0 to make the popup show instantly.
Auto copy to clipboard
Automatically copy selected text to clipboard when popup opens.
Website blocklist
Disables the popup on these URLs. Write each URL on a different line, WITHOUT using "http", "https", or any other protocol. URLs support the wildcard * (meaning "any number of characters, including zero") or regular expressions (regex) in the form /your_regex_here/.

NOTE: Opening the popup via the keyboard shortcut always works, regardless of this setting.

[Press to see examples]

google.com → Blocks google.com, but not www.google.com nor drive.google.com
*.google.com → Blocks www.google.com and drive.google.com, but not google.com
*google.com → Blocks google.com, www.google.com, drive.google.com
drive.google.com → Blocks drive.google.com
docs.google.com/spreadsheets → Blocks docs.google.com/spreadsheets (other pages still work)
/\.com/ → (Regex) Blocks all websites that contain ".com" somewhere in the URL

NOTE: Any regex errors are reported to Firefox' Browser Console (Ctrl+Shift+J) as warnings by SSS. To see them, make sure that "Show Content Messages" is enabled in the top right cog wheel (options) menu of the Browser Console.
Popup/icons look
Display text box
Shows a text box with the current text selection in the popup. Useful to make edits to the text before searching with one of the engines.
Display in a single row
Places all search engines in a single row, instead of a grid.
Icon size
Search engine icon size in pixels.
Separator width
Separator icon width as a percentage of icon size.
Icon horizontal padding
Search engine icon horizontal padding (left and right) in pixels.
Icon vertical padding
Search engine icon vertical padding (top and bottom) in pixels.
Icon hover behaviour
What happens to hovered search engine icons.
Icon roundness
Icon border radius in pixels. Makes icons more or less round. NOTE: this will likely be unnoticeable on icons without a background.
Popup background color
Color for the popup background. Supports transparency using #rrggbbaa.
Popup highlight color
Color for the popup highlight. Supports transparency using #rrggbbaa.
Popup horizontal padding
Popup left/right padding, in pixels.
Popup vertical padding
Popup top/bottom padding, in pixels.
Popup horizontal offset
Popup horizontal offset from the default position, in pixels (positive values move right).
Popup vertical offset
Popup vertical offset from the default position, in pixels (positive values move up).
Popup roundness
Popup border radius in pixels. Makes popup more or less round.
Use custom CSS formatting (experimental)
If you know CSS you can apply any formatting you want to the popup, such as custom icon hover animations or a background image. Please keep in mind that your custom CSS will be *added* to the internal CSS that SSS uses, and so might conflict with it.

NOTE: If the popup's internal CSS changes in any future update, this option may disable itself to avoid problems.
Context menu
Is the context menu enabled?
Enables a "Search for..." context menu with your search engines. Appears when you right click the page while having text selected.
Context menu left click behaviour
What to do when a search engine is left clicked in the context menu.
NOTE: For popup click options, please look in the "Popup/icons behaviour" section.
Context menu right click behaviour
What to do when a search engine is right clicked in the context menu.
NOTE: For popup click options, please look in the "Popup/icons behaviour" section.
Context menu middle click behaviour
What to do when a search engine is middle clicked in the context menu.
NOTE: For popup click options, please look in the "Popup/icons behaviour" section.
Context menu title
Title for the SSS submenu in the context menu. If you use %s somewhere in the title, it will be replaced by whatever text is selected when the context menu opens.
Storage & backup
Storage size
This is an estimate size of your SSS engines and options. Engines with "data:image" icons tend to occupy a lot of space. WARNING: Actual size will very likely be above or below the displayed value.
Sync options (upload)
Saves all SSS options and engines in Firefox Sync. This does not force upload, so you may have to wait for Firefox to sync or force the sync yourself from Firefox's menu. Beware that storage size should be below 100KB for this to work. If above the limit, start by deleting any "data:image" URLs in your engines, or any other extremely long URLs. Estimate size is not exact, so it may still work if above the limit, or fail if below it.
Sync options (download)
Downloads previously saved SSS options and engines from Firefox Sync. This will override all existing options and engines!
Export options to file
Exports all SSS options and engines to a file.
Import options from file
Imports SSS options and engines from a file (previously exported). This will override all existing options and engines!
Reset
Reset all options
Resets all options except search engines to their defaults (as if running SSS for the first time).