Merge pull request leo-buneev#10 from bobheadlabs/master

add support for hooks functions, setting query from URL, search exclusion

Author: leo-buneev

README.md

@@ -1,6 +1,6 @@
 # vuepress-plugin-fulltext-search
 
-Adds full-text search capabilities to your vuepress site with a help of flexsearch library.
+Add full-text search capabilities to your [VuePress](https://vuepress.vuejs.org/) website using the [Flexsearch](https://github.com/nextapps-de/flexsearch) library.
 
 Many thanks to [Ahmad Mostafa](https://ahmadmostafa.com/2019/12/09/build-better-search-in-vuepress-site/) for the idea.
 
@@ -28,3 +28,80 @@ And that is it! Just compile your app and see for yourself.
 
 Webpack alias `@SearchBox` will be replaced with plugin's implementation, so it should work automatically with any
 VuePress theme.
+
+### Functions
+
+You can define functions to hook into various seach features. The functions that can be implemented are as follows:
+
+```ts
+/**
+ * Augment, adjust, or manipulate the suggestions shown to users.
+ */
+async function processSuggestions(suggestions: Suggestion[], queryString: string, queryTerms: string[]): Suggestion[]
+
+/**
+ * Callback function to call when a user clicks on a suggestion.
+ */
+async function onGoToSuggestion(index: number, suggestion: Suggestion, queryString: string, queryTerms: string[])
+```
+
+Functions are provided to the plugin like so:
+
+```js
+// docs/.vuepress/config.js
+const fs = require('fs');
+const { path } = require('@vuepress/shared-utils');
+
+module.exports = {
+  plugins: [
+    ['fulltext-search', {
+      // provide the contents of a JavaScript file
+      functions: fs.readFileSync(path.resolve(__dirname, 'fulltextSearchFunctions.js')),
+    }],
+  ]
+}
+```
+
+For example, in `fulltextSearchFunctions.js`, you might have:
+
+```js
+// docs/.vuepress/fulltextSearchFunctions.js
+export async function processSuggestions(suggestions, queryString, queryTerms) {
+  if (queryString) {
+    // add a suggestion to start a search in an external service
+    suggestions.push({
+      path: 'https://sourcegraph.com/search?patternType=literal&q=',
+      slug: queryString,
+      parentPageTitle: 'Sourcegraph',
+      title: 'Search code',
+      contentStr: 'Search for "' + queryString + '" on Sourcegraph',
+      external: true,
+    });
+  }
+  return suggestions;
+}
+
+export async function onGoToSuggestion() {
+  // create an analytics event
+}
+```
+
+### Search parameters
+
+The `query` URL search parameter can be provided to automatically populate and focus the search box. This is useful for adding your VuePress website as a custom search engine in browsers. For example:
+
+```none
+https://your-website.com?query=hello+world
+```
+
+### Excluding pages from search
+
+You can exclude pages from search suggestions by adding `search: false` to a page's fontmatter:
+
+```none
+---
+search: false
+---
+
+<!-- page content -->
+```

components/SearchBox.vue

@@ -41,6 +41,10 @@
 
 <script>
 import flexsearchSvc from '../services/flexsearchSvc'
+
+// see https://vuepress.vuejs.org/plugin/option-api.html#clientdynamicmodules
+import * as functions from '@dynamic/functions'
+
 /* global SEARCH_MAX_SUGGESTIONS, SEARCH_PATHS, SEARCH_HOTKEYS */
 export default {
   name: 'SearchBox',
@@ -83,6 +87,16 @@ export default {
     flexsearchSvc.buildIndex(this.$site.pages)
     this.placeholder = this.$site.themeConfig.searchPlaceholder || ''
     document.addEventListener('keydown', this.onHotkey)
+
+    // set query from URL
+    const params = this.urlParams()
+    if (params) {
+      const query = params.get('query')
+      if (query) {
+        this.query = decodeURI(query)
+        this.focused = true
+      }
+    }
   },
   beforeDestroy() {
     document.removeEventListener('keydown', this.onHotkey)
@@ -98,11 +112,18 @@ export default {
         this.suggestions = []
         return
       }
-      this.suggestions = await flexsearchSvc.match(
+      const suggestions = await flexsearchSvc.match(
         this.query,
         this.queryTerms,
         this.$site.themeConfig.searchMaxSuggestions || SEARCH_MAX_SUGGESTIONS,
       )
+
+      // augment suggestions with user-provided function
+      if (functions && functions.processSuggestions) {
+        this.suggestions = await functions.processSuggestions(suggestions, this.query, this.queryTerms)
+      } else {
+        this.suggestions = suggestions
+      }
     },
     getPageLocalePath(page) {
       for (const localePath in this.$site.locales || {}) {
@@ -153,16 +174,39 @@ export default {
       if (!this.showSuggestions) {
         return
       }
-      this.$router.push(this.suggestions[i].path + this.suggestions[i].slug)
-      this.query = ''
-      this.focusIndex = 0
+      if (functions && functions.onGoToSuggestion) {
+        functions.onGoToSuggestion(i, this.suggestions[i], this.query, this.queryTerms)
+      }
+      if (this.suggestions[i].external) {
+        window.open(this.suggestions[i].path + this.suggestions[i].slug, '_blank')
+      } else {
+        this.$router.push(this.suggestions[i].path + this.suggestions[i].slug)
+        this.query = ''
+        this.focusIndex = 0
+        this.focused = false
+
+        // reset query param
+        const params = this.urlParams()
+        if (params) {
+          params.delete('query')
+          const paramsString = params.toString()
+          const newState = window.location.pathname + (paramsString ? `?${paramsString}` : '')
+          history.pushState(null, '', newState)
+        }
+      }
     },
     focus(i) {
       this.focusIndex = i
     },
     unfocus() {
       this.focusIndex = -1
     },
+    urlParams() {
+      if (!window.location.search) {
+        return null
+      }
+      return new URLSearchParams(window.location.search)
+    }
   },
 }
 </script>

index.js

@@ -32,6 +32,12 @@ module.exports = options => ({
   alias: {
     '@SearchBox': path.resolve(__dirname, 'components/SearchBox.vue'),
   },
+  clientDynamicModules() {
+    return {
+      name: 'functions.js',
+      content: options.functions || 'export default null',
+    }
+  }
 })
 
 function getCharsets(text) {

services/flexsearchSvc.js

@@ -12,7 +12,8 @@ let pagesByPath = null
 const cjkRegex = /[\u3131-\u314e|\u314f-\u3163|\uac00-\ud7a3]|[\u4E00-\u9FCC\u3400-\u4DB5\uFA0E\uFA0F\uFA11\uFA13\uFA14\uFA1F\uFA21\uFA23\uFA24\uFA27-\uFA29]|[\ud840-\ud868][\udc00-\udfff]|\ud869[\udc00-\uded6\udf00-\udfff]|[\ud86a-\ud86c][\udc00-\udfff]|\ud86d[\udc00-\udf34\udf40-\udfff]|\ud86e[\udc00-\udc1d]|[\u3041-\u3096]|[\u30A1-\u30FA]/giu
 
 export default {
-  buildIndex(pages) {
+  buildIndex(allPages) {
+    const pages = allPages.filter((p) => !p.frontmatter || (p.frontmatter.search !== false))
     const indexSettings = {
       tokenize: 'forward',
       async: true,