@newskit-render/standalone-components 0.28.1-alpha.0 → 0.28.2

package/README.md

@@ -16,15 +16,17 @@ For npm:
 
 ## Components
 
-1. Article recommendations
+## 1. Article recommendations
 
-- Endpoint `/api/recommendations` is used in the `core` package which returns a list on recommendations articles.
+- Endpoint `/api/recommendations` is used in the `core` package which returns a list of recommendations articles.
 
 - Endpoint accepts the following params
+
   - `articleId`
   - `userId`
 
 - Endpoint used in the following files in the `core` package
+
   - `packages/core/pages/[section]/[articleId]/[articleSlug].tsx`
   - `packages/core/pages/[section]/[articleId]/relatedArticles.tsx`
 
@@ -71,19 +73,9 @@ For npm:
     }
     ```
 
-2. Help-hub pages: the package provides 2 pages:
-
-- Search page: where the user is able to search their queries and see the most common questions.
-- Result page: displaying the relevant results based on the user query. To facilitate the search we are using Algolia.
-
-The Help-hub pages will work independent of other components and customized using the context.
+### How to use
 
-# How to use
-
-1. Article recommendations:
-   First, you need to fetch some article recommendations with the recommendationsProvider function, then iterate over the returned array and use the ArticleRecommendation component to display them.
-
-Example of use:
+First, you need to fetch some article recommendations with the recommendationsProvider function, then iterate over the returned array and use the ArticleRecommendation component to display them.
 
 ```typescript
 import React from 'react'
@@ -131,22 +123,197 @@ export async function getServerSideProps(context) {
 }
 ```
 
-2. Help-hub pages:
+## 2. Help-hub:
+
+Help - hub is a section of a website on which your customers can search for a specific problem and find some help to resolve it. It consists of three parts:
+
+1. Landing page: Where the user is able to search their queries and see the most common questions.
+2. Search results page: Displaying the relevant results based on the user query. To facilitate the search we are using Algolia.
+3. Help article page: Page displaying a specific search result.
 
-Example of use:
+The Help-hub pages will work independent of other components and are customized using the context.
+
+### Prerequisite
+
+Help-hub is designed to work only with Next.js, so make sure that your app is running with Next.js
+Before integrating Help-hub, you must ensure that you have an Algolia (Search API) account. If you don't have an account, please create one. After you have obtained an Algolia account, you need to insert the data in it (see docs: https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/#pushing-your-data-to-an-algolia-index). The data must follow the following format:
 
 ```typescript
-import React from 'react'
-import { SearchPage } from '@newskit-render/standalone-components'
-import Layout from '../../components/layout'
+{
+  title: string
+  objectID: string
+  content: string
+}
+```
 
-const HelpHub = () => (
-  <Layout>
-    <SearchPage />
-  </Layout>
-)
+### How to use
+
+#### 1. Credentials
+
+You need to have Algolia credentials as enviromnent variables:
+
+- ALGOLIA_API_KEY
+- ALGOLIA_APP_ID
+- ALGOLIA_INDEX
+
+#### 2. Implementation
+
+As said above, help hub consists of three pages and we will take a look on how to add each one of them individually. Standalone-components package exports page components and a provider function for each page.
+
+1. Help-Hub Landing page. As stated above, landing page will display the most read articles. For now these articles are hardcoded and need to be passed to the Landing page (see example below). These articles must be already imported in Algolia in order for them to work.
+
+```typescript
+import React, { useContext } from 'react'
+import newrelic from 'newrelic'
+import {
+  HelpHubLandingPage,
+  helpHubLandingPageProvider,
+} from '@newskit-render/standalone-components'
+import { createThemeDropdownObject } from '../../helpers/createThemeDropdownObject'
+import { AppContext } from '../../context'
+import { addCacheHeaders } from '../../helpers/addCacheHeaders'
+
+const mostReadArticles = [
+  {
+    title: 'Sign-in with Google',
+    objectID: 'sign-with-google',
+  },
+  {
+    title:
+      'I am trying to share an article via Google+ but an error message keeps appearing',
+    objectID:
+      'i-am-trying-to-share-an-article-via-google-but-an-error-message-keeps-appearing',
+  },
+  {
+    title: 'How will I find out if I have won a competition?',
+    objectID: 'how-will-i-find-out-if-i-have-won-a-competition',
+  },
+  {
+    title: 'How do I login/reset my password?',
+    objectID: 'how-do-i-login-reset-my-password',
+  },
+  {
+    title: 'How do I cancel or change my pack?',
+    objectID: 'how-do-i-cancel-or-change-my-pack',
+  },
+  {
+    title: 'Can I share my Times & Sunday Times iPad subscription access?',
+    objectID: 'can-i-share-my-times-sunday-times-ipad-subscription-access',
+  },
+]
+
+const LandingPage = (props) => {
+  const { theme, setTheme } = useContext(AppContext)
+  const themeDropdownObject = createThemeDropdownObject(setTheme)
+
+  return (
+    <HelpHubLandingPage
+      {...props}
+      context={{ mostReadArticles }}
+      customTheme={theme}
+      themeDropdownObject={themeDropdownObject}
+    />
+  )
+}
+
+export default LandingPage
+
+export const getServerSideProps = async (context) => {
+  newrelic.setTransactionName('HelpHubLandingPage')
+  console.warn('context:')
+  console.warn(context.req && context.req.headers)
+  addCacheHeaders(context.res)
 
-export default HelpHub
+  return helpHubLandingPageProvider()
+}
+```
+
+2. Help-hub Search Results page.
+
+example usage:
+
+```typescript
+import React, { useContext } from 'react'
+import newrelic from 'newrelic'
+import {
+  HelpHubResultsPage,
+  AlgoliaCredentials,
+  Hit,
+  helpHubResultsProvider,
+} from '@newskit-render/standalone-components'
+import { createThemeDropdownObject } from '../../helpers/createThemeDropdownObject'
+import { AppContext } from '../../context'
+import { addCacheHeaders } from '../../helpers/addCacheHeaders'
+
+const ResultsPage: React.FC<{
+  credentilas: AlgoliaCredentials
+  hits: Hit[]
+}> = (props) => {
+  const { theme, setTheme } = useContext(AppContext)
+  const themeDropdownObject = createThemeDropdownObject(setTheme)
+
+  return (
+    <HelpHubResultsPage
+      {...props}
+      customTheme={theme}
+      themeDropdownObject={themeDropdownObject}
+    />
+  )
+}
+
+export default ResultsPage
+
+export const getServerSideProps = async (context) => {
+  newrelic.setTransactionName('HelpHubResultsPage')
+  console.warn('context:')
+  console.warn(context.req && context.req.headers)
+
+  addCacheHeaders(context.res)
+
+  const results = await helpHubResultsProvider({ ...context })
+  return results
+}
+```
+
+3. Help-hub Help Article page. Article page uses next.js router to get the article parameter in order to fetch the article. The parameter is called title. That means that your path in Next routing system should look like this:
+
+`help-hub/article/[title]/index.tsx`
+
+Example use:
+
+```typescript
+import React, { useContext } from 'react'
+import newrelic from 'newrelic'
+import {
+  HelpHubArticlePage,
+  helpHubArticleProvider,
+} from '@newskit-render/standalone-components'
+import { createThemeDropdownObject } from '../../../../helpers/createThemeDropdownObject'
+import { AppContext } from '../../../../context'
+import { addCacheHeaders } from '../../../../helpers/addCacheHeaders'
+
+const ArticlePage = (props) => {
+  const { theme, setTheme } = useContext(AppContext)
+  const themeDropdownObject = createThemeDropdownObject(setTheme)
+
+  return (
+    <HelpHubArticlePage
+      {...props}
+      customTheme={theme}
+      themeDropdownObject={themeDropdownObject}
+    />
+  )
+}
+
+export const getServerSideProps = async (context) => {
+  newrelic.setTransactionName('HelpHubArticlePage')
+  console.warn('context:')
+  console.warn(context.req && context.req.headers)
+
+  addCacheHeaders(context.res)
+  return helpHubArticleProvider({ ...context })
+}
+export default ArticlePage
 ```
 
 .

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newskit-render/standalone-components",
-  "version": "0.28.1-alpha.0",
+  "version": "0.28.2",
   "description": "Newskit Render Standalone Components",
   "author": "",
   "license": "UNLICENSED",
@@ -81,7 +81,7 @@
     "@algolia/autocomplete-preset-algolia": "1.6.3",
     "@apollo/client": "3.4.16",
     "@newskit-render/api": "^0.36.0",
-    "@newskit-render/shared-components": "^0.66.1-alpha.0",
+    "@newskit-render/shared-components": "^0.66.1",
     "algoliasearch": "4.13.1",
     "cross-fetch": "3.1.5",
     "graphql": "15.6.0",