@vegan-friendly/strapi-plugin-elasticsearch 0.0.8

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Punit Sethi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# Strapi plugin strapi-plugin-elasticsearch
+
+A plugin to enable integrating Elasticsearch with Strapi CMS.
+
+## Installation
+
+via npm:
+
+```
+npm i @geeky-biz/strapi-plugin-elasticsearch
+```
+
+via yarn:
+
+```
+yarn add @geeky-biz/strapi-plugin-elasticsearch
+```
+
+## Plugin Configuration
+
+Within your Strapi project's `config/plugin.js`, enable the plugin and provide the configuration details:
+
+```
+module.exports = {
+    // ...
+    'elasticsearch': {
+      enabled: true,
+      config: {
+        indexingCronSchedule: "<cron schedule>",
+        searchConnector: {
+          host: "<hostname for Elasticsearch>",
+          username: "<username for Elasticsearch>",
+          password: "<password for Elasticsearch>",
+          certificate: "<path to the certificate required to connect to Elasticsearch>"
+        },
+        indexAliasName: "<Alias name for the Elasticsearch index>"
+      }  
+    },
+    // ...
+  }
+```
+
+Example plugin configuration (with adequate `.env` variables set up):
+```
+module.exports = {
+    // ...
+    'elasticsearch': {
+      enabled: true,
+      config: {
+        indexingCronSchedule: "00 23 * * *", //run daily at 11:00 PM
+        searchConnector: {
+          host: process.env.ELASTIC_HOST,
+          username: process.env.ELASTIC_USERNAME,
+          password: process.env.ELASTIC_PASSWORD,
+          certificate: path.join(__dirname, process.env.ELASTIC_CERT_NAME)
+        },
+        indexAliasName: process.env.ELASTIC_ALIAS_NAME
+      }  
+    },
+    // ...
+  }
+```
+## Ensuring connection to Elasticsearch
+When connected to Elasticsearch, the `Connected` field within the `Setup Information` screen shall display `true`.
+
+![image](https://github.com/geeky-biz/strapi-plugin-elasticsearch/assets/17068206/a0fe0d6c-95e9-4c3c-95e1-46209db113c7)
+
+## Configuring collections & attributes to be indexed
+The `Configure Collections` view displays the collections and the fields setup to be indexed.
+
+![image](https://github.com/geeky-biz/strapi-plugin-elasticsearch/assets/17068206/13ad3a24-02a6-4c86-8da2-e015ba9c18ea)
+
+From this view, individual collection can be selected to modify configuration:
+
+![image](https://github.com/geeky-biz/strapi-plugin-elasticsearch/assets/17068206/bdc1d674-a74f-4534-9b48-ad0e0eebaeea)
+
+## Configuring indexing for dynamic zone or component attributes
+To enable indexing content for attributes of type `component` or `dynamiczone`, additional information needs to be provided via JSON in the following format:
+
+```
+{
+  "subfields": [
+        {
+          "component": "<component name within schema.json>",
+          "field": "<field name from within that component>"
+        },
+        {...},
+        {...}
+      ]
+}
+```
+### Example 1:
+If we have an attribute called `seo_details` of type `component` like the following within our collection `schema.json`:
+```
+    "seo_details": {
+      "type": "component",
+      "repeatable": false,
+      "component": "metainfo.seo"
+    },
+```
+And, if we seek to index the contents of the `meta_description` field belonging to the component `seo`, our `subfields` configuration should be:
+```
+{
+  "subfields": [
+        {
+          "component": "metainfo.seo",
+          "field": "meta_description"
+        }
+      ]
+}
+```
+![image](https://github.com/geeky-biz/strapi-plugin-elasticsearch/assets/17068206/df1f7dba-2aa1-410e-a567-1de73156a020)
+
+### Example 2:
+If we have an attribute called `sections` of type `dynamiczone` within our collection `schema.json`:
+```
+    "sections": {
+      "type": "dynamiczone",
+      "components": [
+        "content.footer",
+        "content.paragraph",
+        "content.separator",
+        "content.heading"
+      ]
+    },
+...
+```
+And, if we seek to index the contents of the fields `title` for `content.heading` and `details` as well as `subtext` for `content.paragraph`, our `subfields` configuration should be:
+```
+{
+  "subfields": [
+        {
+          "component": "content.paragraph",
+          "field": "details"
+        },
+        {
+          "component": "content.paragraph",
+          "field": "subtext"
+        },
+        {
+          "component": "content.heading",
+          "field": "title"
+        }
+      ]
+}
+```
+The subfields JSON also supports multiple level of nesting:
+```
+{
+  "subfields": [
+        {
+          "component": "content.footer",
+          "field": "footer_link",
+          "subfields": [
+            {
+              "component": "content.link",
+              "field": "display_text"
+            }
+          ]
+        }
+      ]
+}
+```
+Note: Indexing of `relations` attributes isn't yet supported.
+
+## Exporting and Importing indexing configuration
+To enable backing up the indexing configuration or transferring it between various environments, these can be Exported / Imported from the `Configure Collections` view.
+
+![image](https://github.com/geeky-biz/strapi-plugin-elasticsearch/assets/17068206/6e099392-499e-4101-8f51-85b7eff8aa38)
+
+## Scheduling Indexing
+Once the collection attributes are configured for indexing, any changes to the respective collections & attributes is marked for indexing. The cron job (configured via `indexingCronSchedule`) makes actual indexing requests to the connected Elasticsearch instance. 
+
+- `Trigger Indexing` triggers the cron job immediately to perform the pending indexing tasks without waiting for the next scheduled run.
+- `Rebuild Indexing` completely rebuilds the index. It may be used if the Elasticsearch appears to be out of sync from the data within Strapi.
+
+![image](https://github.com/geeky-biz/strapi-plugin-elasticsearch/assets/17068206/71df02a9-8513-4a91-8e23-2b5f34495c20)
+
+Whenever a collection is configured for indexing, it may already have data that needs to be indexed. To facilitate indexing of the past data, a collection can be scheduled for indexing in the next cron run from the `Configure Collections` view:
+
+![image](https://github.com/geeky-biz/strapi-plugin-elasticsearch/assets/17068206/7f37453a-dc87-406a-8de0-0391018b7fb5)
+
+## Searching
+You may directly use the Elasticsearch search API or you may use the Search API exposed by the plugin (at `/api/elasticsearch/search`). The plugin search API is just a wrapper around the Elasticsearch search API that passes the query parameter to the Elasticsearch search API and returns the results coming from Elasticsearch:
+
+For example, the below API call would result into the Elasticsearch search API being triggered with the query 
+```
+`/api/elasticsearch/search?query=query%5Bbool%5D%5Bshould%5D%5B0%5D%5Bmatch%5D%5Bcity%5D=atlanta`
+```
+would result into the Elasticsearch search API being triggered with query
+```
+query[bool][should][0][match][city]=atlanta
+```
+The plugin's API would return the response from the Elasticsearch search API.
+
+Note: To use the `search` API (at `/api/elasticsearch/search`), you will have to provide access via `Settings` -> `Users & Permissions Plugin` -> `Roles` -> (Select adequate role) -> `Elasticsearch` -> `search`.
+
+### Extending Search API
+The recommended was to enhance the Search API is to write your own route and controller. Below is an example of how this can be achieved (this example adds pagination capability to the search API):
+
+- Within your setup, create `src/extensions/elasticsearch/strapi-server.js` with the following contents:
+
+```
+const { Client } = require('@elastic/elasticsearch')
+const qs = require('qs');
+
+let client = null;
+
+module.exports = (plugin) => {
+
+    client = new Client({
+        node: plugin.config.searchConnector.host,
+        auth: {
+          username: plugin.config.searchConnector.username,
+          password: plugin.config.searchConnector.password
+        },
+        tls: {
+          ca: plugin.config.searchConnector.certificate,
+          rejectUnauthorized: false
+        }
+    });
+
+    plugin.controllers['performSearch'].enhancedSearch = async (ctx) => {
+            try
+            {
+                const params = qs.parse(ctx.request.query)
+                const query = params.search;
+                const pagesize = params.pagesize;
+                const from = params.from;
+                const result= await client.search({
+                    index: plugin.config.indexAliasName,
+                    query: { "bool" : { "should" : [ { "match": { "content": "dummy"} } ] } },
+                    size: pagesize,
+                    from: from 
+                });
+                return result;
+            }
+            catch(err)
+            {
+                console.log('Search : elasticClient.enhancedSearch : Error encountered while making a search request to ElasticSearch.')
+                throw err;
+            }
+    }
+
+    plugin.routes['search'].routes.push({
+        method: 'GET',
+        path: '/enhanced-search',
+        handler: 'performSearch.enhancedSearch',
+      });
+  
+    
+    return plugin;
+};
+
+```
+
+- This will create a new route `/api/elasticsearch/enhanced-search` being served by the function defined above.
+- You can add / modify the routes and controllers as necessary.
+
+## Bugs
+For any bugs, please create an issue [here](https://github.com/geeky-biz/strapi-plugin-elasticsearch/issues).
+
+## About
+- This plugin is created by [Punit Sethi](https://punits.dev).
+- I'm an independent developer working on Strapi migrations, customizations, configuration projects (see [here](https://punits.dev/strapi-customizations/)).
+- For any Strapi implementation requirement, write to me at `punit@tezify.com`.

package/admin/src/components/Initializer/index.js

@@ -0,0 +1,26 @@
+/**
+ *
+ * Initializer
+ *
+ */
+
+import { useEffect, useRef } from 'react';
+import PropTypes from 'prop-types';
+import pluginId from '../../pluginId';
+
+const Initializer = ({ setPlugin }) => {
+  const ref = useRef();
+  ref.current = setPlugin;
+
+  useEffect(() => {
+    ref.current(pluginId);
+  }, []);
+
+  return null;
+};
+
+Initializer.propTypes = {
+  setPlugin: PropTypes.func.isRequired,
+};
+
+export default Initializer;

package/admin/src/components/PluginIcon/index.js

@@ -0,0 +1,12 @@
+/**
+ *
+ * PluginIcon
+ *
+ */
+
+import React from 'react';
+import { Search } from '@strapi/icons';
+
+const PluginIcon = () => <Search />;
+
+export default PluginIcon;

package/admin/src/components/SubNavigation/index.js

@@ -0,0 +1,48 @@
+import React from 'react';
+import { Connector } from '@strapi/icons';
+import { Box } from '@strapi/design-system';
+import {
+  SubNav,
+  SubNavHeader,
+  SubNavSection,
+  SubNavSections,
+  SubNavLink,
+} from '@strapi/design-system/v2';
+import { NavLink } from 'react-router-dom';
+import pluginId from "../../pluginId";
+
+export const SubNavigation = ({activeUrl}) => {
+  const links = [ {
+    id: 1,
+    label : 'Setup Information',
+    icon : Connector,
+    to : `/plugins/${pluginId}/home`,
+  },
+  {
+    id: 2,
+    label : 'Configure Collections',
+    icon : Connector,
+    to : `/plugins/${pluginId}/configure-collections`,
+  },
+{
+  id: 3,
+  label : 'Indexing Run Logs',
+  icon : Connector,
+  to : `/plugins/${pluginId}/view-indexing-logs`,
+}];
+  return (<Box style={{
+        height: '100vh'
+      }} background="neutral200">
+            <SubNav ariaLabel="Settings sub nav">
+              <SubNavHeader label="Strapi Elasticsearch" />
+              <SubNavSections>
+                <SubNavSection>
+                  {links.map(link => link.icon && <SubNavLink 
+                  as={NavLink} to={link.to} icon={link.icon} key={link.id} >
+                      {link.label}
+                  </SubNavLink>)}
+                </SubNavSection>
+              </SubNavSections>
+            </SubNav>
+        </Box>);
+}

package/admin/src/index.js

@@ -0,0 +1,63 @@
+import { prefixPluginTranslations } from '@strapi/helper-plugin';
+import pluginPkg from '../../package.json';
+import pluginId from './pluginId';
+import Initializer from './components/Initializer';
+import PluginIcon from './components/PluginIcon';
+
+const name = pluginPkg.strapi.name;
+
+export default {
+  register(app) {
+    app.addMenuLink({
+      to: `/plugins/${pluginId}`,
+      icon: PluginIcon,
+      intlLabel: {
+        id: `${pluginId}.plugin.name`,
+        defaultMessage: 'Elasticsearch',
+      },
+      Component: async () => {
+        const component = await import(/* webpackChunkName: "[request]" */ './pages/App');
+
+        return component;
+      },
+      permissions: [
+        // Uncomment to set the permissions of the plugin here
+        // {
+        //   action: '', // the action name should be plugin::plugin-name.actionType
+        //   subject: null,
+        // },
+      ],
+    });
+    app.registerPlugin({
+      id: pluginId,
+      initializer: Initializer,
+      isReady: false,
+      name,
+    });
+  },
+
+  bootstrap(app) {},
+  async registerTrads({ locales }) {
+    const importedTrads = await Promise.all(
+      locales.map((locale) => {
+        return import(
+          /* webpackChunkName: "translation-[request]" */ `./translations/${locale}.json`
+        )
+          .then(({ default: data }) => {
+            return {
+              data: prefixPluginTranslations(data, pluginId),
+              locale,
+            };
+          })
+          .catch(() => {
+            return {
+              data: {},
+              locale,
+            };
+          });
+      })
+    );
+
+    return Promise.resolve(importedTrads);
+  },
+};

package/admin/src/pages/App/index.js

@@ -0,0 +1,29 @@
+/**
+ *
+ * This component is the skeleton around the actual pages, and should only
+ * contain code that should be seen on all pages. (e.g. navigation bar)
+ *
+ */
+
+import React from 'react';
+import { Switch, Route, Redirect } from 'react-router-dom';
+import { AnErrorOccurred } from '@strapi/helper-plugin';
+import pluginId from '../../pluginId';
+import ConfigureCollectionList from '../ConfigureCollectionList';
+import ConfigureCollection from '../ConfigureCollection';
+import ViewIndexingRunLog from '../ViewIndexingRunLog';
+import Homepage from '../Homepage';
+const App = () => {
+  return (
+      <Switch>
+        <Route path={`/plugins/${pluginId}`} render={() => (<Redirect to={`/plugins/${pluginId}/home`} />)} exact />
+        <Route path={`/plugins/${pluginId}/home`} component={Homepage} exact />
+        <Route path={`/plugins/${pluginId}/configure-collections`} component={ConfigureCollectionList} exact />
+        <Route path={`/plugins/${pluginId}/configure-collections/:collectionName`} component={ConfigureCollection} exact />
+        <Route path={`/plugins/${pluginId}/view-indexing-logs`} component={ViewIndexingRunLog} />        
+        <Route component={AnErrorOccurred} />
+      </Switch>
+  );
+};
+
+export default App;