Add support for customizing concordance size, clarify readme

README.md

@@ -935,10 +935,14 @@ Through javascript you can do many things, but outlined below are some of the mo
   </details>
 
 - <details>
-    <summary>[Results/Hits] configure which annotation is shown as context and snippet and enable html mode</summary>
+    <summary>[Results/Hits] configure the displaying of hits and their surrounding words</summary>
 
     `vuexModules.ui.actions.results.shared.concordanceAnnotationId('word_xml')`
+    `vuexModules.ui.actions.results.shared.concordanceSize(100)`
     `vuexModules.ui.actions.results.shared.concordanceAsHtml(true)`
+    `vuexModules.ui.actions.results.shared.transformSnippets(snippet -> {/* modify snippet in place */})`
+
+    -------
 
     `concordanceAnnotationId` lets you set which annotation is used to display words in the results table:
 
@@ -956,6 +960,13 @@ Through javascript you can do many things, but outlined below are some of the mo
 
     -------
 
+    `concordanceSize` controls the number of visible surrounding words when expanding hits to view details (default 50, max 1000).
+    ![](docs/img/concordance_size_50.png)
+    `vuexModules.ui.actions.results.shared.concordanceSize(10)`
+    ![](docs/img/concordance_size_10.png)
+
+    -------
+
     `concordanceAsHtml` is an advanced feature.
     Combined with blacklab's [captureXml](https://github.com/INL/BlackLab/blob/9fdc0e146f136287b0c3cca8456b0ef60ce2cbe2/core/src/site/markdown/how-to-configure-indexing.md#indexing-xml) mode, you can index snippets of raw xml from your document into an annotation. You can then set that annotation to display as html in the results table. This allows you to style it as any html using `custom css`.
 
@@ -991,7 +1002,36 @@ Through javascript you can do many things, but outlined below are some of the mo
 
     Browser support for non-html elements is good, so arbitrary xml should work out of the box, given it is well-formed.
 
-    USE THIS FEATURE WITH CARE! It may break your page if the xml contains unexpected or malformed contents.
+    **USE THIS FEATURE WITH CARE!** It may break your page if the xml contains unexpected or malformed contents.
+
+    -------
+
+    `transformSnippets` can be used to replace some words, add warnings, or correct some things in your data (such as escape sequences) after the fact, when doing so would be hard to do in the source files.
+    Or it could be used to do some markup in combination with the `concordanceAsHtml` settings.
+    ```ts
+      /** E.g. {word: ['words', 'in', 'the', 'hit'], lemma: [...], pos: [...]} */
+      type SnippetPart = { [annotationId: string]: string[]; };
+      type Snippet = {
+        left: SnippetPart;
+        match: SnippetPart;
+        right: SnippetPart;
+        // Warning: there might be more!
+      };
+      type TransformFunction = ((snippet: Snippet): void);
+      vuexModules.ui.actions.results.shared.transformSnippets(snippet => {
+        const transform = (...snippets) => snippets.forEach(v => v.word = v.word.map(word => {
+          if (word === 'de') return `<span style="text-decoration: underline; text-shadow: 0 0 2px red;">${word}</span>`;
+          return word;
+        }))
+        transform(snippet.left, snippet.match, snippet.right);
+      });
+    ```
+
+    ### before:
+    ![](docs/img/snippet_transform_before.png)  
+    ### after:
+    ![](docs/img/snippet_transform_after.png)
+
 
   </details>
 
@@ -1043,7 +1083,6 @@ Through javascript you can do many things, but outlined below are some of the mo
     `vuexModules.ui.results.shared.totalsRefreshIntervalMs(2_000)`  
 
     ![](docs/img/result_totals_in_progress.png)
-
 
   </details>
 

src/frontend/src/pages/search/results/table/DocResults.vue

@@ -102,7 +102,7 @@ export default Vue.extend({
 	computed: {
 		concordanceAnnotationId(): string { return UIStore.getState().results.shared.concordanceAnnotationId; },
 		concordanceAsHtml(): boolean { return UIStore.getState().results.shared.concordanceAsHtml; },
-		transformSnippets(): null|((s?: BLHitSnippet|BLHitSnippet[]) => void) { return UIStore.getState().results.shared.transformSnippets; },
+		transformSnippets(): null|((s: BLHitSnippet) => void) { return UIStore.getState().results.shared.transformSnippets; },
 		getDocumentSummary(): ((doc: BLDocInfo, fields: BLDocFields) => string) { return UIStore.getState().results.shared.getDocumentSummary; },
 
 		textDirection: CorpusStore.get.textDirection,

src/frontend/src/pages/search/results/table/HitResults.vue

@@ -312,6 +312,7 @@ export default Vue.extend({
 		/** Return all annotations shown in the main search form (provided they have a forward index) */
 		sortableAnnotations(): AppTypes.NormalizedAnnotation[] { return UIStore.getState().results.shared.sortAnnotationIds.map(id => CorpusStore.get.allAnnotationsMap()[id]); },
 		concordanceAnnotationId(): string { return UIStore.getState().results.shared.concordanceAnnotationId; },
+		concordanceSize(): number { return UIStore.getState().results.shared.concordanceSize; },
 		concordanceAsHtml(): boolean { return UIStore.getState().results.shared.concordanceAsHtml; },
 		shownAnnotationCols(): AppTypes.NormalizedAnnotation[] {
 			// Don't bother showing the value when we're sorting on the surrounding context and not the hit itself
@@ -377,7 +378,7 @@ export default Vue.extend({
 
 			const corpusId = CorpusStore.getState().id;
 			Api.blacklab
-			.getSnippet(corpusId, row.docPid, row.start, row.end)
+			.getSnippet(corpusId, row.docPid, row.start, row.end, this.concordanceSize)
 			.then(s => {
 				if (this.transformSnippets) {
 					this.transformSnippets(s);

src/frontend/src/store/search/ui.ts

@@ -140,7 +140,9 @@ type ModuleRootState = {
 			/** What annotation to use for displaying of [before, hit, after] and snippets. Conventionally the main annotation. */
 			concordanceAnnotationId: string;
 			/** Optionally run a function on all retrieved snippets to arbitrarily process the data (we use this to format the values in some annotations for display purposes). */
-			transformSnippets: null|((snippet?: BLTypes.BLHitSnippet|BLTypes.BLHitSnippet[]) => void);
+			transformSnippets: null|((snippet: BLTypes.BLHitSnippet) => void);
+			/** Size of the details hit (number of words loaded before/after the hit when expanding a hit result). Max 1000 */
+			concordanceSize: number;
 			concordanceAsHtml: boolean;
 			getDocumentSummary: ((doc: BLTypes.BLDocInfo, fields: BLTypes.BLDocFields) => string);
 
@@ -258,6 +260,7 @@ const initialState: ModuleRootState = {
 		},
 		shared: {
 			concordanceAnnotationId: '',
+			concordanceSize: 50,
 			transformSnippets: null,
 			concordanceAsHtml: false,
 			getDocumentSummary: (doc: BLTypes.BLDocInfo, fields: BLTypes.BLDocFields): string => {
@@ -476,6 +479,8 @@ const actions = {
 				r => state.results.shared.concordanceAnnotationId = id
 			), 'shared_concordanceAnnotationId'),
 			concordanceAsHtml: b.commit((state, enable: boolean) => state.results.shared.concordanceAsHtml = enable, 'shared_concordanceAsHtml'),
+			concordanceSize: b.commit((state, size: number) => state.results.shared.concordanceSize = Math.min(Math.max(0, size), 1000), 'shared_concordanceSize'),
+			transformSnippets: b.commit((state, transform: (snippet: BLTypes.BLHitSnippet) => void) => state.results.shared.transformSnippets = transform, 'shared_transformSnippets'),
 
 			detailedAnnotationIds: b.commit((state, ids: string[]|null) => {
 				if (ids != null) {
@@ -754,6 +759,9 @@ const init = () => {
 		actions.results.shared.concordanceAnnotationId(mainAnnotation.hasForwardIndex ? mainAnnotation.id : defaultAnnotationsToShow[0]);
 	}
 
+	if (initialState.results.shared.concordanceSize > 1000) 
+		actions.results.shared.concordanceSize(1000);
+
 	// Results table columns
 	// Hits table: Never show any metadata in the hits table
 	// Docs table: Show the date column if it is configured