Change naming for functionality added in leo-buneev#10

Author: Leonid Buneev

CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+## 2.1.0 (2020-10-22)
+
+### Added
+
+- Support for Hiragana and Katakana in Japanese. (@shout-star in #20)
+- Support for hooks functions (@bobheadxi in #10)
+- Ability to set search query from URL parameter (@bobheadxi in #10)
+- Ability to exclude page from search (@bobheadxi in #10)

README.md

@@ -1,6 +1,7 @@
 # vuepress-plugin-fulltext-search
 
-Add full-text search capabilities to your [VuePress](https://vuepress.vuejs.org/) website using the [Flexsearch](https://github.com/nextapps-de/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.
 
@@ -29,79 +30,86 @@ 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:
+### Search parameters
 
-```ts
-/**
- * Augment, adjust, or manipulate the suggestions shown to users.
- */
-async function processSuggestions(suggestions: Suggestion[], queryString: string, queryTerms: string[]): Suggestion[]
+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:
 
-/**
- * Callback function to call when a user clicks on a suggestion.
- */
-async function onGoToSuggestion(index: number, suggestion: Suggestion, queryString: string, queryTerms: string[])
+```none
+https://your-website.com?query=hello+world
 ```
 
-Functions are provided to the plugin like so:
+### Excluding pages from search
+
+You can exclude pages from search suggestions by adding `search: false` to a page's frontmatter:
 
-```js
-// docs/.vuepress/config.js
-const fs = require('fs');
-const { path } = require('@vuepress/shared-utils');
+```none
+---
+search: false
+---
 
-module.exports = {
-  plugins: [
-    ['fulltext-search', {
-      // provide the contents of a JavaScript file
-      functions: fs.readFileSync(path.resolve(__dirname, 'fulltextSearchFunctions.js')),
-    }],
-  ]
-}
+<!-- page content -->
 ```
 
-For example, in `fulltextSearchFunctions.js`, you might have:
+### Hooks
 
-```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;
-}
+You can define several hooks to customize behaviour of various search features. For example:
 
-export async function onGoToSuggestion() {
-  // create an analytics event
+```js
+// /docs/.vuepress/searchHooks.js
+export default {
+  async 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
+  },
+
+  async onGoToSuggestion(index, suggestion, queryString, queryTerms) {
+    // e.g. create an analytics event
+
+    // return true if you want to prevent default navigation
+    return true
+  },
 }
-```
 
-### 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:
+// /docs/.vuepress/config.js
+// Important: Because of the way Vuepress build works, you cannot use regular import/require,
+// code must be provided as plaintext. Hence syntax below is required with fs.readFileSync
+const fs = require('fs')
+const { path } = require('@vuepress/shared-utils')
 
-```none
-https://your-website.com?query=hello+world
+module.exports = {
+  plugins: [
+    [
+      'fulltext-search',
+      {
+        // provide the contents of a JavaScript file
+        hooks: fs.readFileSync(path.resolve(__dirname, './searchHooks.js')),
+      },
+    ],
+  ],
+}
 ```
 
-### Excluding pages from search
-
-You can exclude pages from search suggestions by adding `search: false` to a page's fontmatter:
+Supported hooks are:
 
-```none
----
-search: false
----
+```ts
+/**
+ * Augment, adjust, or manipulate the suggestions shown to users.
+ */
+async function processSuggestions(suggestions: Suggestion[], queryString: string, queryTerms: string[]): Suggestion[]
 
-<!-- page content -->
+/**
+ * Callback function to call a suggestion.
+ */
+async function onGoToSuggestion(index: number, suggestion: Suggestion, queryString: string, queryTerms: string[]): Boolean?
 ```

components/SearchBox.vue

@@ -43,7 +43,7 @@
 import flexsearchSvc from '../services/flexsearchSvc'
 
 // see https://vuepress.vuejs.org/plugin/option-api.html#clientdynamicmodules
-import * as functions from '@dynamic/functions'
+import hooks from '@dynamic/hooks'
 
 /* global SEARCH_MAX_SUGGESTIONS, SEARCH_PATHS, SEARCH_HOTKEYS */
 export default {
@@ -119,8 +119,8 @@ export default {
       )
 
       // augment suggestions with user-provided function
-      if (functions && functions.processSuggestions) {
-        this.suggestions = await functions.processSuggestions(suggestions, this.query, this.queryTerms)
+      if (hooks.processSuggestions) {
+        this.suggestions = await hooks.processSuggestions(suggestions, this.query, this.queryTerms)
       } else {
         this.suggestions = suggestions
       }
@@ -174,8 +174,9 @@ export default {
       if (!this.showSuggestions) {
         return
       }
-      if (functions && functions.onGoToSuggestion) {
-        functions.onGoToSuggestion(i, this.suggestions[i], this.query, this.queryTerms)
+      if (hooks.onGoToSuggestion) {
+        const result = hooks.onGoToSuggestion(i, this.suggestions[i], this.query, this.queryTerms)
+        if (result === true) return
       }
       if (this.suggestions[i].external) {
         window.open(this.suggestions[i].path + this.suggestions[i].slug, '_blank')
@@ -206,7 +207,7 @@ export default {
         return null
       }
       return new URLSearchParams(window.location.search)
-    }
+    },
   },
 }
 </script>

index.js

@@ -34,10 +34,10 @@ module.exports = options => ({
   },
   clientDynamicModules() {
     return {
-      name: 'functions.js',
-      content: options.functions || 'export default null',
+      name: 'hooks.js',
+      content: options.hooks || 'export default {}',
     }
-  }
+  },
 })
 
 function getCharsets(text) {

package.json

@@ -16,6 +16,7 @@
     "vuepress": "^1.4.0"
   },
   "devDependencies": {
+    "cross-env": "^7.0.2",
     "eslint-plugin-tyrecheck": "^2.10.3"
   }
 }

services/flexsearchSvc.js

@@ -13,7 +13,7 @@ const cjkRegex = /[\u3131-\u314e|\u314f-\u3163|\uac00-\ud7a3]|[\u4E00-\u9FCC\u34
 
 export default {
   buildIndex(allPages) {
-    const pages = allPages.filter((p) => !p.frontmatter || (p.frontmatter.search !== false))
+    const pages = allPages.filter(p => !p.frontmatter || p.frontmatter.search !== false)
     const indexSettings = {
       tokenize: 'forward',
       async: true,