In this example we implement an adapter for Google Search and a dapplet for it.
Here is the initial code for this example: ex08-new-adapter-exercise.
The adapter and the dapplet are divided into two directories:
Create an adapter with one widget
button for two contexts.#
At the beginning we change the adapter template. Let's add buttons under each element’s title of standard Google search results and one button in the top navigation bar.
config. It is an object which describes different contexts on the page. Selectors for container, context data and insertion points for widgets are described here.
contextBuilder defines context information that widget receives in these context types:
SEARCH_RESULT in our case (named
ctx in our examples).
How to create an adapter's config?
Now we could talk about site-specific adapters. It means that dapplets using this adapter interact with some specific website. It also means that we should use the website's HTML structure to add our widgets to certain parts of the pages.
The idea of separating adapters from dapplets is to provide dapplets' developers with a simple interface to add their augmentations (we call them widgets) to existing pages. This way, dapplets developers don't need to worry about how to add their code in certain places or how to parse different blocks of information on the page. They get the template, customize it and add the behavior they need.
The goals of the adapters' developer are to create this template, define the data that can be parsed from the context, that can be useful in the dapplet.
Adapters' developer also need to describe exact places on the pages where the widgets will be inserted. To describe them we use valid CSS selectors that can be used in the Document method
For example, let's look at the Google Search page. Enter some search query,
clouds for example.
Look at the structure of the page in the browser's developer tools, Elements tab.
There you can find the block with
search id, that contains all the main search results.
It will be our containerSelector where we will search some separate results.
Then try to pick out the selectors' chain that provides access to separate context — contextSelector. You can choose relevant selectors manually or you can left click on the element in the Elements tab and choose Copy selector. In most cases the selector has to be edited.
In some cases there are several relevant selectors for different places on the page or different pages. In this case you can define them separating by using commas.
Make sure not to include unwanted blocks.
Using the same method define selectors for insertion points — exact places where the widgets will be placed.
There are 3 insert options:
inside. The first one is default.
Also in the contextBuilder you have to get all the properties for the context. There is a function that receives the node given by the contextSelector.
!! Note that websites can be changed and you will get errors trying to get properties when the nodes will not be found.
It is assumed that all interactions with DOM happen in the adapters and not in the dapplets.
So let's go back to our exercise.
Now we have two contexts: MENU and SEARCH_RESULT.
If there are many contexts of the same type on the page, like tweets or search results, you have to find a unique
id for each one. It's needed for saving the states of dapplets' widgets connected to these contexts.
The next step - is creating a widget. We have a template of the button in
To define the contexts in which this widget is used, you must specify
For example, let's define the contexts for
Let's implement at the public method
mount of the class
Button the HTML with
tooltip for our insertion points
Adapters allow the dapplet to customize the widgets. This can be the
text of the button, the
image on the icon, the choice of one of the
location options, etc. The adapter developer decides what parameters to make customizable. They should be described in the documentation as follows: parameter's
mandatory or not, data
description. If you need to select one of several value options for a parameter, they must be listed (this can be specified in the parameter type). If the parameter type is a number, then it is recommended to indicate in which units it will be converted: pixels, percentages, fractions, etc.
Add styles for the widget depending on the context.
Then change the dapplet.
Add buttons to search results and top navigation bar in
Implement an alert that would be triggered when you click the search results button. The alert should contain the title, the link to the source and a short description of the found fragment from the element.
Implement two states for the top navigation bar button. Actions: replace search results with
HI_GIF and return to default results.
Here is the result of this part: ex08.1-new-adapter-solution.
Run the dapplet:
In this example we run two servers concurrently. So you have to add two registry addresses to the Dapplet extension in the Development tab. Click here for instructions.
Add a widget
result to the adapter with one context insertion point#
Add new context
insPoint should be on the top of Google widgets like Videos, Images of ..., People also ask etc.
Complete config in
Add a new context
DAPPLET_SEARCH_RESULT, which is similar to
but adds a button to our search widget. This is done to prevent overwriting of similar search results from different sources.
Don't forget to add
contextInsPoints as in the example above.
adapter/src/result.ts that exports class
It should have an image, a title and an artificial list of results.
See the code of result.ts
Import and add Result to
searchResults from the template as a content source.
Implement the insertion of buttons into our widget.
Add support for
DAPPLET_SEARCH_RESULT context to
Here is the result: ex08.2-new-adapter-widget-solution.
Run the dapplet:
To see the full result, please enter
clouds into Google