Skip to content

Commit 33a48fc

Browse files
committed
docs: Document impact of grouping by url_without_anchor
1 parent 3501115 commit 33a48fc

File tree

3 files changed

+59
-10
lines changed

3 files changed

+59
-10
lines changed

CONTRIBUTING.md

Lines changed: 59 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,24 +2,73 @@
22

33
## Implementation notes
44

5-
* The `cache` Map lets us instantly display any previous result in the same browser tab. We follow the [LRU strategy](https://en.wikipedia.org/wiki/Least_recently_used).
5+
### Group by url_without_anchor
66

7-
For example, if you type `a`, `app`, `apple`, `apples`, and backspace to a shorter previous query, we instantly show those previous results. (No time wasted waiting for re-download of the same results. It also saves client bandwidth and server load.) Or, if you think another word might yield better results and replace it with `banana`, and return to `apple` because that had a better one, we respond instantly.
7+
One of the ways in which minibar provides different (and arguably, better) default settings compared to DocSearch.js, is the removal of duplicate results from the same page.
88

9-
We keep up to 100 past results in memory. After that, we prioritize keeping the most recently shown data, and delete older unused results. We assume that you're most likely to return to what you've seen most recently. (Maybe not within the last 10, but within 100. Even if you do return to the very first after a hundred, you're likely to pass by more recent ones on the way there. All queries have equal cost.) When we store a new result, or when we re-use an old result, we delete it and re-set it, so that it goes to the "bottom" of the map.
9+
- [Demo: typesense-minibar](https://jquery.github.io/typesense-minibar/)
10+
- [Demo: Comparison to DocSearch.js](https://jquery.github.io/typesense-minibar/demo/compare--docsearch-3.html)
1011

11-
When it is time to delete an old result, we take a key from the "top" of the map, which is either the oldest and never used, or the least recently used.
12+
In minibar, entering "ajax" returns these 5 results:
1213

13-
If we only add new results and reuse results as-is ([FIFO strategy](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics))), that may delete very recently used data.
14+
<img align="right" width="300" src="./assets/eg-minibar132-ajax.png">
1415

15-
* The styles for `typesense-minibar` as web component, and `.tsmb-form` class name are kept independent (that is, the web component does not auto-add the class name, nor does it otherwise rely on styles for the class name, and vice versa).
16+
> Low-Level Interface
17+
>
18+
> 1. jQuery.ajax()
19+
> 2. jQuery.ajaxTransport()
20+
>
21+
> Global Event Handlers
22+
>
23+
> 3. ajaxComplete event
24+
> 4. ajaxSuccess event
25+
> 5. ajaxError event
26+
27+
In DocSearch, entering "ajax" returns these 10 results (the first 7 are visible without scrolling):
28+
29+
<img align="right" width="300" src="./assets/eg-docsearch301-ajax.png">
30+
31+
> Documentation
32+
>
33+
> 1. jQuery 3.0 Upgrade Guide
34+
> 2. jQuery 3.0 Upgrade Guide
35+
> 3. jQuery 3.0 Upgrade Guide
36+
> 4. jQuery 3.0 Upgrade Guide
37+
> 5. jQuery 3.0 Upgrade Guide
38+
>
39+
> Global Event Handlers
40+
>
41+
> 6. ajaxComplete event
42+
> 7. ajaxComplete event
43+
>
44+
> Global Event Handlers (contd., after scrolling)
45+
>
46+
> 8. ajaxSuccess event
47+
> 9. ajaxSuccess event
48+
> 10. ajaxError event
49+
50+
### The `cache` Map
51+
52+
This lets us instantly display any previous result in the same browser tab. We follow the [LRU strategy](https://en.wikipedia.org/wiki/Least_recently_used).
53+
54+
For example, if you type `a`, `app`, `apple`, `apples`, and backspace to a shorter previous query, we instantly show those previous results. (No time wasted waiting for re-download of the same results. It also saves client bandwidth and server load.) Or, if you think another word might yield better results and replace it with `banana`, and return to `apple` because that had a better one, we respond instantly.
55+
56+
We keep up to 100 past results in memory. After that, we prioritize keeping the most recently shown data, and delete older unused results. We assume that you're most likely to return to what you've seen most recently. (Maybe not within the last 10, but within 100. Even if you do return to the very first after a hundred, you're likely to pass by more recent ones on the way there. All queries have equal cost.) When we store a new result, or when we re-use an old result, we delete it and re-set it, so that it goes to the "bottom" of the map.
57+
58+
When it is time to delete an old result, we take a key from the "top" of the map, which is either the oldest and never used, or the least recently used.
59+
60+
If we only add new results and reuse results as-is ([FIFO strategy](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics))), that may delete very recently used data.
61+
62+
### Separate CSS selectors for class and web component
63+
64+
The styles for `typesense-minibar` as web component, and `.tsmb-form` class name are kept independent (that is, the web component does not auto-add the class name, nor does it otherwise rely on styles for the class name, and vice versa).
1665

1766
This is done for two reasons:
1867

19-
1. Avoid selector conflict for Style API.
20-
If we were to add `class="tsmb-form"` in the web component, it would mean `typesense-minibar form` and `.tsmb-form` both match. This makes the `typesense-minibar form` selector impsosible to override in CSS for downstream users, because our defaults for `.tsmb-form` (weight 0010) would continue to "win" the cascade, as being a stronger selector than `typesense-minibar form` (weight 0002).
21-
2. Avoid a FOUC.
22-
The element should render identically and without reflows both before and after JavaScript loads. During local development it's easy to miss a FOUC if it fixes itself once JavaScript loads. By not auto-correcting these, the bugs are more obvious and we fix them.
68+
1. Avoid selector conflict for Style API.
69+
If we were to add `class="tsmb-form"` in the web component, it would mean `typesense-minibar form` and `.tsmb-form` both match. This makes the `typesense-minibar form` selector impsosible to override in CSS for downstream users, because our defaults for `.tsmb-form` (weight 0010) would continue to "win" the cascade, as being a stronger selector than `typesense-minibar form` (weight 0002).
70+
2. Avoid a FOUC.
71+
The element should render identically and without reflows both before and after JavaScript loads. During local development it's easy to miss a FOUC if it fixes itself once JavaScript loads. By not auto-correcting these, the bugs are more obvious and we fix them.
2372

2473
## Internal API
2574

assets/eg-docsearch301-ajax.png

83.1 KB
Loading

assets/eg-minibar132-ajax.png

82.2 KB
Loading

0 commit comments

Comments
 (0)