Ex08: New Site specific adapter
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: /adapter
and /dapplet-feature
.
button
for two contexts.#
Create an adapter with one widget 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.
In adapter/src/index.ts
implement 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: MENU
and SEARCH_RESULT
in our case (named ctx
in our examples).
tip
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 querySelector()
.
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: end
, start
and 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 adapter/src/button.ts
.
To define the contexts in which this widget is used, you must specify contextInsPoints
.
For example, let's define the contexts for MENU
and SEARCH_RESULT
Let's implement at the public method mount
of the class Button
the HTML with label
, image
and tooltip
for our insertion points MENU
and SEARCH_RESULT
.
tip
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 name
, mandatory
or not, data TYPE
, text 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 /dapplet-feature/src/index.ts
.
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.
result
to the adapter with one context insertion point#
Add a widget Add new context WIDGETS
. insPoint
should be on the top of Google widgets like Videos, Images of ..., People also ask etc.
Complete config in /adapter/src/index.ts
:
Add a new context DAPPLET_SEARCH_RESULT
, which is similar to SEARCH_RESULT
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 DAPPLET_SEARCH_RESULT
to contextInsPoints
as in the example above.
Implement module adapter/src/result.ts
that exports class Result
.
It should have an image, a title and an artificial list of results.
See the code of result.ts
Import and add Result to /adapter/src/index.ts
:
In dapplet-feature/src/index.ts
add result
to WIDGETS
. Use searchResults
from the template as a content source.
Implement the insertion of buttons into our widget.
Add support for DAPPLET_SEARCH_RESULT
context to adapter/src/button.ts
.
Here is the result: ex08.2-new-adapter-widget-solution.
Run the dapplet:
To see the full result, please enter clouds
into Google