Update algolia plugin #1730

jonahtanjz · 2022-01-20T04:43:41Z

What is the purpose of this pull request?

Overview of changes:
Update Algolia from v2 to v3. Algolia now requires appId to be provided in order to use its APIs. V3 also requires that the search box be a div and no longer supports input.

User facing changes include adding new options and removing unsupported options:

Added:
appId - compulsory field
searchParameters - optional

Removed:
debug
algoliaOptions

Anything you'd like to highlight / discuss:
V3 has changed its design drastically from V2. The search bar has a new design and clicking on the search bar will open a modal instead. The searches will be done on this modal and the results will be displayed on the modal instead of the dropdown that is used by Markbind's search. Since the new search bar and modal are auto generated by Algolia's package, it will be complicated to try to make the design similar to the current Markbind's search. Is it fine to stick to their native design?

New search bar:

New search modal instead of dropdown:

Testing instructions:
Add the following to site.json and serve the site.

"plugins": [
    "algolia"
  ],
  "pluginsContext": {
    "algolia": {
      "apiKey": "599cec31baffa4868cae4e79f180729b",
      "appId": "R2IYF7ETH7",
      "indexName": "docsearch"
    }
  }

Proposed commit message: (wrap lines at 72 characters)
Update Algolia plugin

Algolia docsearch v2 is now a legacy version. Algolia also
requires new parameters for their APIs.

Let's update the version of Algolia docsearch to v3 and change
the plugin options accordingly.

Checklist: ☑️

Updated the documentation for feature additions and enhancements
Added tests for bug fixes or features
Linked all related issues
No unrelated changes

damithc · 2022-01-20T04:56:10Z

Thanks for tackling this @jonahtanjz

V3 has changed its design drastically from V2. The search bar has a new design and clicking on the search bar will open a modal instead. The searches will be done on this modal and the results will be displayed on the modal instead of the dropdown that is used by Markbind's search. Since the new search bar and modal are auto generated by Algolia's package, it will be complicated to try to make the design similar to the current Markbind's search. Is it fine to stick to their native design?

I'm OK with it, if they haven't provided an easy way to use the dropdown for search results.

ryoarmanda

LGTM! 🎉

ang-zeyu · 2022-01-22T04:40:41Z

packages/core-web/src/index.js

+        height: calc(100% - ${headerHeight}px - 66px);
+      }
+    }`,
+  );


Just a quick look, would it be better to keep these strictly to the plugin itself? Since docsearch isn't really core functionality, but a plugin.

Some questions release wise:

whether its possible to deliver a more minimal fix by adding the apiKey you mentioned onto v3.1.1 or so (also so no immediate action needed on author end to migrate v2 -> v3)

while we merge this bigger change into the main branch for v4.0 (since v2 -> v3 docsearch is a breaking change)

Just a quick look, would it be better to keep these strictly to the plugin itself? Since docsearch isn't really core functionality, but a plugin.

I've shifted the plugin css code to within the plugin file. The rest of the plugin code related to adjustHeaderClasses is left there to minimise duplication as there are a couple of conditions that will need to adjust the plugin's css.

whether its possible to deliver a more minimal fix by adding the apiKey you mentioned onto v3.1.1 or so (also so no immediate action needed on author end to migrate v2 -> v3)

while we merge this bigger change into the main branch for v4.0 (since v2 -> v3 docsearch is a breaking change)

Yup agree with this. We should do the v2 -> v3 docsearch in our v4.0 and release the minimal fix in v3.1.1. I'll create a separate branch called v3.1.x-hotfixes (similar to the v2.7.x-hotfixes branch) and push the update there. Is this workflow fine?

Yup agree with this. We should do the v2 -> v3 docsearch in our v4.0 and release the minimal fix in v3.1.1. I'll create a separate branch called v3.1.x-hotfixes (similar to the v2.7.x-hotfixes branch) and push the update there. Is this workflow fine?

👍

Alternatively there haven't been any breaking changes since the last release so far, so we could also merge the more minimal fix directly on the main branch. (I think either is fine)

I've shifted the plugin css code to within the plugin file. The rest of the plugin code related to adjustHeaderClasses is left there to minimise duplication as there are a couple of conditions that will need to adjust the plugin's css.

V3 has changed its design drastically from V2. The search bar has a new design and clicking on the search bar will open a modal instead. The searches will be done on this modal and the results will be displayed on the modal instead of the dropdown that is used by Markbind's search. Since the new search bar and modal are auto generated by Algolia's package, it will be complicated to try to make the design similar to the current Markbind's search. Is it fine to stick to their native design?

*For v4

Sorry, I completely missed the purpose of these changes earlier.

Are the dynamic styles added to tackle the above mentioned issue?

I'm favouring sticking with algolia's default design as much as possible if so, imo there isn't much benefit from pushing the dropdown / ui downward. Coupling our dynamic style detections over to an external element might break as well if algolia's styles / classes / dom structure changes.

If its an issue with correctness (e.g. the modal going out of the screen) I'll need a little more time to review this with your algolia setup

Mainly because the modal gets blocked by the navbar if the header is fixed.

I could try to increase the z-index of the modal to be higher. That may help to resolve this issue without pushing it down below the fixed header.

Tested with z-index and it works as well. Will change to this implementation as it's much simpler.

damithc · 2022-01-22T06:55:50Z

Perhaps we can do a minor release after this is merged? I would like to start using this in the module website ASAP.

ang-zeyu · 2022-01-29T09:12:37Z

packages/core-web/src/index.js

@@ -42,18 +42,19 @@ function detectAndApplyFixedHeaderStyles() {

  const headerHeight = headerSelector.height();
  const bufferHeight = 1;
-  insertCss(`.fixed-header-padding { padding-top: ${headerHeight}px !important }`);
+  insertCss(`.fixed-header-padding { padding-top: ${headerHeight}px !important; }`);


Nice work @jonahtanjz, but do try to avoid the unnecessary changes here!

Particularly as there are no functional changes in the entire file

jonahtanjz requested a review from ryoarmanda January 20, 2022 04:46

jonahtanjz force-pushed the update-algolia-plugin branch from 74420d1 to b33d585 Compare January 20, 2022 05:55

ryoarmanda approved these changes Jan 20, 2022

View reviewed changes

ang-zeyu reviewed Jan 22, 2022

View reviewed changes

jonahtanjz force-pushed the update-algolia-plugin branch from 97bf3a5 to 63c3d9f Compare January 22, 2022 06:56

jonahtanjz added 8 commits January 23, 2022 11:30

Update algolia plugin to v3

b382043

Update algolia test

fc6b637

Polish code and documentation

675cff8

Add appId to algolia test

6b6d2f5

Minor styling update

7e09ad3

Adjust mobile height for search result dropdown

c4e39f5

Shift algolia specific css to plugin file

7a5b6d8

Change css to use z-index

24c919b

jonahtanjz force-pushed the update-algolia-plugin branch from 58f6f06 to 24c919b Compare January 23, 2022 03:34

ryoarmanda added this to the 4.0 milestone Jan 27, 2022

ryoarmanda merged commit 65a58e8 into MarkBind:master Jan 27, 2022

ang-zeyu reviewed Jan 29, 2022

View reviewed changes

jonahtanjz added the breakingChange 💥 Feature will behave significantly different, or is made obsolete label Apr 30, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update algolia plugin #1730

Update algolia plugin #1730

jonahtanjz commented Jan 20, 2022

damithc commented Jan 20, 2022

ryoarmanda left a comment

ang-zeyu Jan 22, 2022

jonahtanjz Jan 22, 2022

ang-zeyu Jan 22, 2022

ang-zeyu Jan 22, 2022 •

edited

Loading

jonahtanjz Jan 22, 2022

jonahtanjz Jan 22, 2022

damithc commented Jan 22, 2022

ang-zeyu Jan 29, 2022 •

edited

Loading

Update algolia plugin #1730

Update algolia plugin #1730

Conversation

jonahtanjz commented Jan 20, 2022

damithc commented Jan 20, 2022

ryoarmanda left a comment

Choose a reason for hiding this comment

ang-zeyu Jan 22, 2022

Choose a reason for hiding this comment

jonahtanjz Jan 22, 2022

Choose a reason for hiding this comment

ang-zeyu Jan 22, 2022

Choose a reason for hiding this comment

ang-zeyu Jan 22, 2022 • edited Loading

Choose a reason for hiding this comment

jonahtanjz Jan 22, 2022

Choose a reason for hiding this comment

jonahtanjz Jan 22, 2022

Choose a reason for hiding this comment

damithc commented Jan 22, 2022

ang-zeyu Jan 29, 2022 • edited Loading

Choose a reason for hiding this comment

ang-zeyu Jan 22, 2022 •

edited

Loading

ang-zeyu Jan 29, 2022 •

edited

Loading