Locale-based search engines are imported from the Android l10n repos. To import the latest set of plugins, execute the ./scrape_plugins.py
script.
Do not make changes to SearchPlugins.plist
-- these changes will be overwritten on the next import! If you need to make changes to search plugins, you have the following options (in preferred order):
- Update the plugin directly in the Android l10n repos. This is preferred if your changes apply to both platforms. Since the iOS engines are imported from Android, any changes to the Android l10n repos will be picked up here when the import script is run.
- Define an overlay. Overlays allow local, iOS-specific modifications to be applied after the files are imported.
For the most part, the engines are the same on both platforms. There are, however, certain iOS-specific changes that we want to make to some of the engines. Previously, we would modify the engine XML files directly, but this made it difficult to re-import the engines from Android without losing our local changes.
To address this, we've added support for search engine overlays. These are XML files located in the SearchOverlays
directory that contain document transformations to be applied after each import.
To add an overlay, append the overlay definition to the corresponding XML file (or create it if it doesn't exist) in the search engine in the SearchOverlays
directory. The overlay file name is based on the plugin file name used in list.json
; for example, to create a Yahoo overlay, we would add an overlay to SearchOverlays/yahoo.xml
.
Overlay files have the following structure:
<SearchOverlay>
<append parent="https://search:Url[@type='text/html']">
<!-- Child node to append -->
</append>
<replace target="https://search:Image">
<!-- Replacement node -->
</append>
</SearchOverlay>
The root node of an overlay document must be a SearchOverlay
element. It can have any number of <append>
or <replace>
nodes, which will perform those respective actions on the engine matching this file.
- Node name:
append
- Required attribute:
parent
- The value forparent
is an XPath expression identifying elements in the search plugin XML. Note that all nodes must be prefixed by thesearch
namespace. - Children:
append
must have exactly one child element; the element may have any number of children. This element will be appended to any elements matching theparent
XPath expression.
- Node name:
replace
- Required attribute:
target
- The value fortarget
is an XPath expression identifying elements in the search plugin XML. Note that all nodes must be prefixed by thesearch
namespace. - Children:
replace
must have exactly one child element; the element may have any number of children. This element will replace any elements matching thetarget
XPath expression.
Execute ./run_tests.py
to run tests. This uses test files in the Tests
directory to check overlay behavior.