Merge pull request #1703 from ral-facilities/feature/add-examples-section-advanced-search-help

Add examples section to advanced help dialogue

Author: louise-davies

packages/datagateway-search/public/res/default.json

@@ -303,6 +303,20 @@
     "close_button_arialabel": "Close",
     "title": "Advanced Search Tips",
     "description": "Searching the metadata catalogue using one or more words should be intuitive, with the most relevant matches appearing first. However, there is a powerful syntax that supports more advanced use cases, which are described below.",
+    "examples": {
+      "title": "Examples",
+      "description": "Below are a few examples of common searches and how they can be crafted to execute efficiently for those with access to large volumes of data:",
+      "examples": [
+        {
+          "name": "To search for a visit and partial location",
+          "value": "+visitId:\"nt20-8\" +location:\"jpegs/pg1/\""
+        },
+        {
+          "name": "To search for a visit, partial location and filename ext",
+          "value": "+visitId:\"nt20-8\" +location:\" jpegs/pg1/\" +(location:jpeg location:*.jpeg)"
+        }
+      ]
+    },
     "terms": {
       "title": "Terms",
       "description": "By default, all words in the search text are treated as separate <strong>terms</strong>. Results must contain at least one <strong>term</strong> to be returned, and they can occur in any order in the result. When using the default relevancy based sorting, results containing the most <strong>terms</strong> will appear first. For example, <10>neutron scattering</10> will return results containing both <strong>terms</strong> first, then results containing only one or the other.",

packages/datagateway-search/src/search/advancedHelpDialogue.component.test.tsx

@@ -15,6 +15,7 @@ import {
 import { initialState as dgSearchInitialState } from '../state/reducers/dgsearch.reducer';
 import { StateType } from '../state/app.types';
 import userEvent from '@testing-library/user-event';
+import reactI18Next from 'react-i18next';
 
 jest.mock('react-redux', () => ({
   ...jest.requireActual('react-redux'),
@@ -37,6 +38,8 @@ function renderComponent({
 
 describe('Advanced help dialogue', () => {
   let state: StateType;
+  const tSpy = jest.fn((str) => str);
+  let originalUseTranslation: typeof reactI18Next.useTranslation;
 
   beforeEach(() => {
     state = JSON.parse(
@@ -45,6 +48,13 @@ describe('Advanced help dialogue', () => {
         dgsearch: dgSearchInitialState,
       })
     );
+
+    originalUseTranslation = reactI18Next.useTranslation;
+    reactI18Next.useTranslation = jest.fn().mockReturnValue([tSpy]);
+  });
+
+  afterEach(() => {
+    reactI18Next.useTranslation = originalUseTranslation;
   });
 
   it('is hidden initially', () => {
@@ -66,7 +76,7 @@ describe('Advanced help dialogue', () => {
     );
 
     expect(
-      screen.getByRole('dialog', { name: 'Advanced Search Tips' })
+      screen.getByRole('dialog', { name: 'advanced_search_help.title' })
     ).toBeInTheDocument();
 
     await user.click(
@@ -75,11 +85,42 @@ describe('Advanced help dialogue', () => {
       })
     );
 
+    // advanced_search_help.examples.examples is not an array so example section is not rendered
+    expect(
+      screen.queryByText('advanced_search_help.examples.title')
+    ).not.toBeInTheDocument();
+
     await waitForElementToBeRemoved(
-      screen.getByRole('dialog', { name: 'Advanced Search Tips' })
+      screen.getByRole('dialog', { name: 'advanced_search_help.title' })
     );
     expect(
-      screen.queryByRole('dialog', { name: 'Advanced Search Tips' })
+      screen.queryByRole('dialog', { name: 'advanced_search_help.title' })
     ).toBeNull();
   });
+
+  it('renders examples section when an example is given', async () => {
+    tSpy.mockImplementation((key) => {
+      if (key === 'advanced_search_help.examples.examples') {
+        return [{ name: 'example 1', value: 'example 1' }];
+      } else return key;
+    });
+    const user = userEvent.setup();
+
+    renderComponent({ initialState: state });
+
+    await user.click(
+      screen.getByRole('button', {
+        name: 'advanced_search_help.search_options_arialabel',
+      })
+    );
+
+    expect(
+      screen.getByRole('dialog', { name: 'advanced_search_help.title' })
+    ).toBeInTheDocument();
+
+    // advanced_search_help.examples.examples is an array with items in it so we should render example section
+    expect(
+      screen.getByText('advanced_search_help.examples.title')
+    ).toBeInTheDocument();
+  });
 });

packages/datagateway-search/src/search/advancedHelpDialogue.component.tsx

@@ -6,8 +6,14 @@ import {
   IconButton,
   Link,
   styled,
+  Table,
+  TableBody,
+  TableRow,
+  TableCell,
   Theme,
   Typography,
+  TableContainer,
+  Paper,
 } from '@mui/material';
 import CloseIcon from '@mui/icons-material/Close';
 import { Trans, useTranslation } from 'react-i18next';
@@ -80,7 +86,7 @@ const AdvancedHelpDialogue = (): React.ReactElement => {
         }}
       >
         <DialogTitle id="advanced-search-dialog-title">
-          Advanced Search Tips
+          {t('advanced_search_help.title')}
           <IconButton
             aria-label={t('advanced_search_help.close_button_arialabel')}
             sx={{
@@ -99,6 +105,58 @@ const AdvancedHelpDialogue = (): React.ReactElement => {
           <Typography gutterBottom>
             {t('advanced_search_help.description')}
           </Typography>
+          {Array.isArray(
+            t('advanced_search_help.examples.examples', {
+              returnObjects: true,
+            })
+          ) &&
+            (
+              t('advanced_search_help.examples.examples', {
+                returnObjects: true,
+              }) as { name: string; value: string }[]
+            ).length > 0 && (
+              <Section>
+                <SectionTitle>
+                  {t('advanced_search_help.examples.title')}
+                </SectionTitle>
+                <SectionText>
+                  <Trans
+                    t={t}
+                    i18nKey="advanced_search_help.examples.description"
+                  >
+                    Below are a few examples of common searches and how they can
+                    be crafted to execute efficiently for those with access to
+                    large volumes of data:
+                  </Trans>
+                </SectionText>
+
+                <TableContainer component={Paper}>
+                  <Table size="small">
+                    <TableBody>
+                      {(
+                        t('advanced_search_help.examples.examples', {
+                          returnObjects: true,
+                        }) as { name: string; value: string }[]
+                      ).map(({ name, value }, index) => (
+                        <TableRow key={index}>
+                          <TableCell>{name}</TableCell>
+                          <TableCell>
+                            <Link
+                              component={RouterLink}
+                              to={`?searchText=${value}`}
+                              onClick={handleClose}
+                            >
+                              {value}
+                            </Link>
+                          </TableCell>
+                        </TableRow>
+                      ))}
+                    </TableBody>
+                  </Table>
+                </TableContainer>
+              </Section>
+            )}
+
           <Section>
             <SectionTitle>{t('advanced_search_help.terms.title')}</SectionTitle>
             <SectionText>