Implement Crop (#50)

* Add vanilla-JS playground

* Remove vanilla playground

* Add crop handling

* Add ... to crop

* Refacto

* Add desctructuration

Author: curquiza

.gitignore

@@ -102,3 +102,6 @@ dist
 
 # TernJS port file
 .tern-port
+
+# misc
+.DS_Store

playgrounds/vue/src/App.vue

@@ -34,6 +34,9 @@
                   <ais-highlight :hit="item" attribute="name"/>
                 </div>
                 <img :src="item.image" align="left" :alt="item.image">
+                <div class="hit-description">
+                  <ais-snippet :hit="item" attribute="description"/>
+                </div>
                 <div class="hit-info">price: {{item.price}}</div>
                 <div class="hit-info">release date: {{item.releaseDate}}</div>
               </div>
@@ -44,6 +47,8 @@
 
           <ais-configure
             :hits-per-page.camel="6"
+            :attributesToSnippet="['description:50']"
+            snippetEllipsisText="…"
           />
         </div>
       </ais-instant-search>
@@ -60,10 +65,7 @@ export default {
     return {
       searchClient: instantMeiliSearch(
         "https://demos.meilisearch.com",
-        "dc3fedaf922de8937fdea01f0a7d59557f1fd31832cb8440ce94231cfdde7f25",
-        {
-          paginationTotalHits: 60
-        }
+        "dc3fedaf922de8937fdea01f0a7d59557f1fd31832cb8440ce94231cfdde7f25"
       )
     };
   }
@@ -94,7 +96,7 @@ body {
   margin-bottom: 0.5em;
 }
 
-.ais-Highlight-highlighted {
+.ais-Highlight-highlighted, .ais-Snippet-highlighted {
   background: cyan;
   font-style: normal;
 }
@@ -107,6 +109,12 @@ body {
   margin-bottom: 0.5em;
 }
 
+.hit-description {
+  font-size: 90%;
+  margin-bottom: 0.5em;
+  color: grey;
+}
+
 .hit-info {
   font-size: 90%;
 }

src/format.js

@@ -0,0 +1,89 @@
+import { isString } from './utils.js'
+
+function replaceHighlightTags(value, highlightPreTag, highlightPostTag) {
+  let newHighlightValue = value || ''
+  // If the value of the attribute is a string,
+  // the highlight is applied by MeiliSearch (<em> tags)
+  // and we replace the <em> by the expected tag for InstantSearch
+  if (isString(value)) {
+    newHighlightValue = value
+      .replace(/<em>/g, highlightPreTag)
+      .replace(/<\/em>/g, highlightPostTag)
+  }
+  return newHighlightValue.toString()
+}
+
+function createHighlighResult({
+  formattedHit,
+  highlightPreTag,
+  highlightPostTag,
+}) {
+  // formattedHit is the `_formatted` object returned by MeiliSearch.
+  // It contains all the highlighted and croped attributes
+  return Object.keys(formattedHit).reduce((result, key) => {
+    result[key] = {
+      value: replaceHighlightTags(
+        formattedHit[key],
+        highlightPreTag,
+        highlightPostTag
+      ),
+    }
+    return result
+  }, {})
+}
+
+function snippetFinalValue(
+  value,
+  snippetEllipsisText,
+  highlightPreTag,
+  highlightPostTag
+) {
+  let newValue = value
+  // manage a kind of `...` for the crop until this issue is solved: https://github.com/meilisearch/MeiliSearch/issues/923
+  // `...` is put if we are at the middle of a sentence (instead at the middle of the document field)
+  if (snippetEllipsisText !== undefined && isString(newValue)) {
+    if (
+      newValue[0] === newValue[0].toLowerCase() && // beginning of a sentence
+      newValue.startsWith('<em>') === false // beginning of the document field, otherwise MeiliSearch would crop around the highligh
+    ) {
+      newValue = `${snippetEllipsisText}${newValue}`
+    }
+    if (!!newValue.match(/[.!?]$/) === false) {
+      // end of the sentence
+      newValue = `${newValue}${snippetEllipsisText}`
+    }
+  }
+  return replaceHighlightTags(newValue, highlightPreTag, highlightPostTag)
+}
+
+function createSnippetResult({
+  formattedHit,
+  attributesToSnippet,
+  snippetEllipsisText,
+  highlightPreTag,
+  highlightPostTag,
+}) {
+  if (attributesToSnippet === undefined) {
+    return null
+  }
+  attributesToSnippet = attributesToSnippet.map(
+    (attribute) => attribute.split(':')[0]
+  )
+  // formattedHit is the `_formatted` object returned by MeiliSearch.
+  // It contains all the highlighted and croped attributes
+  return Object.keys(formattedHit).reduce((result, key) => {
+    if (attributesToSnippet.includes(key)) {
+      result[key] = {
+        value: snippetFinalValue(
+          formattedHit[key],
+          snippetEllipsisText,
+          highlightPreTag,
+          highlightPostTag
+        ),
+      }
+    }
+    return result
+  }, {})
+}
+
+export { createHighlighResult, createSnippetResult }

src/index.js

@@ -1,5 +1,6 @@
 import MeiliSearch from 'meilisearch'
-import { isString, removeUndefinedFromObject } from './utils.js'
+import { removeUndefinedFromObject } from './utils.js'
+import { createHighlighResult, createSnippetResult } from './format.js'
 
 export default function instantMeiliSearch(hostUrl, apiKey, options = {}) {
   return {
@@ -12,38 +13,18 @@ export default function instantMeiliSearch(hostUrl, apiKey, options = {}) {
       const limit = this.pagination // if pagination widget is set, use paginationTotalHits as limit
         ? this.paginationTotalHits
         : this.hitsPerPage
+      const { query, facets, facetFilters, attributesToSnippet } = params
       const searchInput = {
-        q: this.placeholderSearch && params.query === '' ? null : params.query,
-        facetsDistribution: params.facets.length ? params.facets : undefined,
-        facetFilters: params.facetFilters,
+        q: this.placeholderSearch && query === '' ? null : query,
+        facetsDistribution: facets.length ? facets : undefined,
+        facetFilters: facetFilters,
         attributesToHighlight: this.attributesToHighlight,
+        attributesToCrop: attributesToSnippet,
         limit,
       }
       return removeUndefinedFromObject(searchInput)
     },
 
-    replaceHighlightTags: function (
-      formattedHit,
-      highlightPreTag,
-      highlightPostTag
-    ) {
-      // formattedHit is the `_formatted` object returned by MeiliSearch.
-      // It contains all the highlighted attributes
-      return Object.keys(formattedHit).reduce((result, key) => {
-        let newHighlightString = formattedHit[key] || ''
-        // If the value of the attribute is a string,
-        // the highlight is applied by MeiliSearch (<em> tags)
-        // and we replace the <em> by the expected tag for InstantSearch
-        if (isString(formattedHit[key])) {
-          newHighlightString = formattedHit[key]
-            .replace(/<em>/g, highlightPreTag)
-            .replace(/<\/em>/g, highlightPostTag)
-        }
-        result[key] = { value: newHighlightString.toString() }
-        return result
-      }, {})
-    },
-
     parseHits: function (meiliSearchHits, params) {
       if (this.pagination) {
         const start = params.page * this.hitsPerPage
@@ -55,11 +36,8 @@ export default function instantMeiliSearch(hostUrl, apiKey, options = {}) {
         delete hit._formatted
         return {
           ...hit,
-          _highlightResult: this.replaceHighlightTags(
-            formattedHit,
-            params.highlightPreTag,
-            params.highlightPostTag
-          ),
+          _highlightResult: createHighlighResult({ formattedHit, ...params }),
+          _snippetResult: createSnippetResult({ formattedHit, ...params }),
         }
       })
     },
@@ -108,7 +86,7 @@ export default function instantMeiliSearch(hostUrl, apiKey, options = {}) {
       // Params got from InstantSearch
       const params = requests[0].params
       this.pagination = params.page !== undefined // If the pagination widget has been set
-      this.hitsPerPage = params.hitsPerPage || 20 // 20 is the MeiliSearch's default limit value. It can be changed with `InsantSearch.configure`.
+      this.hitsPerPage = params.hitsPerPage || 20 // 20 is the MeiliSearch's default limit value. `hitsPerPage` can be changed with `InsantSearch.configure`.
       // Gets information from IS and transforms it for MeiliSearch
       const searchInput = this.transformToMeiliSearchParams(params)
       const indexUid = requests[0].indexName