|
2 | 2 |
|
3 | 3 | ## Implementation notes
|
4 | 4 |
|
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 |
6 | 6 |
|
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. |
8 | 8 |
|
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) |
10 | 11 |
|
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: |
12 | 13 |
|
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"> |
14 | 15 |
|
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). |
16 | 65 |
|
17 | 66 | This is done for two reasons:
|
18 | 67 |
|
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. |
23 | 72 |
|
24 | 73 | ## Internal API
|
25 | 74 |
|
|
0 commit comments