Forem: Malik Gabroun

Getting Started with Algolia API

Malik Gabroun — Mon, 22 Nov 2021 18:15:40 +0000

Introduction

In this course, you will learn how the Algolia API works by understanding its main components. The end goal is for you to be able to integrate Algolia into your application to deliver tailored, fast search experiences.

In the first half, you will learn how to build a full search experience using Algolia's search API and by utilising Algolia's InstantSearch library. In the second half, you will learn how to extend Algolia's widgets by building a custom search experience.

By the end of this course, you will have gained hands-on experience by building a fully functional search experience using Algolia.

You can check it out here

List of Contents

Below you can find the list of lessons you will learn in this course:

Overview of Algolia

Get introduced to Algolia and how it works.
Algolia Setup

Learn how to create an Algolia index, get Algolia API keys, and create new ones.
Sending Data to the Algolia Server

Learn how to send data to Algolia using API or Algolia's dashboard and interact with the sample code to see how we can push data using Algolia's API.
Managing Data with Algolia

Learn how to manage dataset configuration before sending it to Algolia using API or dashboard. Additionally, interact with the sample code to practice customising and sending dataset using Aloglia's API.
Managing Data by Adding Custom Ranking to Our Search Results

Learn how to manage results' ranking based on certain attributes using the API or dashboard. Additionally, interact with the sample code to practice customising the ranking before sending the dataset using Aloglia's API.
Composition of the Search Component

Break down the components of Algolia's InstantSearch in this lesson and understand what the search functionality is composed of.
Implementing a Search Box and Results Component

Discover what you can do with the SearchBox and Hits components and try them yourself in this lesson.
Implementing a Highlight Component

Explore how search results can be improved by adding the Highlight component.
Implementing the Stats component

Explore how we can improve search results and user experience by adding the number of hits based on user search by using the Stats component.
Implementing Filter and the Clear Filter Component

Explore how we can improve search results and user experience by adding a way to filter the dataset based on facets using the RefinementList component. Also, we add a way to clear applied filters using the ClearRefinements component.
Implementing the Pagination Component

Learn how to set a number of products that appear per page instead of showing all of them together and letting the user scroll endlessly.
Extending Algolia's Widgets

Discover what you can do with Algolia's connectors by extending Algolia's InstantSearch components.

You can find the course here

Syntax Highlighting in Gatsby MDX

Malik Gabroun — Wed, 19 Feb 2020 07:52:08 +0000

In this post, we will be looking into how to enable syntax highlighting for Gatsby MDX files using prism-react-renderer

first, we need to install a couple of modules

npm i prism-react-renderer @mdx-js/react

Then, we create the component which we will use in the <MDXProvider/> that is going to provide a wrapper replacement for our application.

const component = {
  pre: props => {
    const className = props.children.props.className || '';
    const matches = className.match(/language-(?<lang>.*)/);
    return (
      <Highlight
        {...defaultProps}
        code={props.children.props.children}
        language={
          matches && matches.groups && matches.groups.lang
            ? matches.groups.lang
            : ''
        }
      >
        {({ className, style, tokens, getLineProps, getTokenProps }) => (
          <pre className={className} style={style}>
            {tokens.map((line, i) => (
              <div {...getLineProps({ line, key: i })}>
                {line.map((token, key) => (
                  <span {...getTokenProps({ token, key })} />
                ))}
              </div>
            ))}
          </pre>
        )}
      </Highlight>
    );
  },
};

To render the code block we added in MDX file to show up on the page we will access props of the child component of <pre/> component as markdown code blocks get compiled into a <pre/> component wrapping the code component.
We can dive a level deeper to get the code by using props.children.props.children, as you can see from the screenshot below.

To get the language attribute of the code block rather than hardcoding the value we look into MDX code block as it comes through as a class name that will look like language-className (for example language-javascript).

To get the language defined in the code component in the MDX file, we will drill down at props.children.props.className, if there is no class name then we might have not put a language on our code block in which case we will default to empty strings.
Then we use a name capture group in regex with the name lang to get the language of the language-className. if there are matches

const matches = className.match(/language-(?<lang>.*)/);

To enable syntax highlighting in MDX files by adding the following snippet below in gatsby-browser.js

import React from 'react';
import { MDXProvider } from '@mdx-js/react';
import Highlight, { defaultProps } from 'prism-react-renderer';

/* eslint-disable */
const component = {
  pre: props => {
    const className = props.children.props.className || '';
    const matches = className.match(/language-(?<lang>.*)/);
    return (
      <Highlight
        {...defaultProps}
        code={props.children.props.children}
        language={
          matches && matches.groups && matches.groups.lang
            ? matches.groups.lang
            : ''
        }
      >
        {({ className, style, tokens, getLineProps, getTokenProps }) => (
          <pre className={className} style={style}>
            {tokens.map((line, i) => (
              <div {...getLineProps({ line, key: i })}>
                {line.map((token, key) => (
                  <span {...getTokenProps({ token, key })} />
                ))}
              </div>
            ))}
          </pre>
        )}
      </Highlight>
    );
  },
};

export const wrapRootElement = ({ element }) => {
  return <MDXProvider components={component}>{element}</MDXProvider>;
};

Following the post you can find a starter repo here that shows usage of mdx pages and syntax highlighting

Originally posted at malikgabroun.com

How to Create Pages Dynamically in Gatsby Using MDX

Malik Gabroun — Sun, 02 Feb 2020 20:24:50 +0000

Originally posted at malikgabroun.com

In this post, we will be looking into how to create pages programmatically using MDX in Gatsby.

To get up and running, we need to install a couple of plugins

npm i gatsby-plugin-mdx @mdx-js/mdx @mdx-js/react

Then we need to configure gatsby-mdx inside gatsby-config.js

plugins: [
  {
    resolve: 'gatsby-plugin-mdx',
    options: {
      defaultLayouts: {
        default: require.resolve('./src/components/Layout.js'),
      },
    },
  },
];

So first we need to resolve the plugin gatsby-plugin-mdx because we also want to pass in options object which defines what layout that we want to use in our MDX files.

Note: require.resolve give us the absolute path name.

As a result, any MDX files that we load will be loaded into the Layout.js template that we defined in the gatsby-config.

Now that we have installed the plugin, the plugin will look for mdx files in the pages or posts directory which we defined in gatsby-config.

So to get the post pages into gatsby, we are going to use another plugin gatsby-source-filesystem

npm i gatsby-source-filesystem

to get them to the data layer so that we can access them.

The gatsby source file system is a way to use local files as part of the graphql data layer.

Once it gets installed, we need to update gatsby config to resolve source filesystem plugin

plugins: [
  {
    resolve: 'gatsby-plugin-mdx',
    options: {
      defaultLayouts: {
        default: require.resolve('./src/components/Layout.js'),
      },
    },
  },
  {
    resolve: 'gatsby-source-filesystem',
    options: {
      name: 'posts',
      path: `${__dirname}/content/posts`,
    },
  },
];

As a result, it will load anything that it finds in the path /content/posts as part of the data layer, and because we have gatsby MDX plugin installed it's going to look for MDX files and transform those into graphql nodes.

The whole reason for using MDX is because we want to add some sort of interactivity in the markup generated pages.

Now that we added configuration to look for files in the system and transform them to graphql nodes, we would need to generate those post files as pages programmatically using gatsby API createPages by configuring that in gatsby-node.js.

Gatsby in itself has a couple of available APIs that can be used to extend how gatsby works, inside of those you can export a function that is the same name as one of the hooks that gatsby looks for. As a result, gatsby will do those instructions at the build phase.

In this case, we want to create pages so we use exports.createPages and because we are going to load data we make the function async.

Gatsby will give us a couple of utility methods such as actions, graphql helper and reporter(which can be used in case you want to put something in the console, it's a gatsby internal kind of console.log)

exports.createPages = async ({ actions, graphql, reporter }) => {
  const result = await graphql(`
    query {
      allMdx {
        nodes {
          frontmatter {
            path
          }
        }
      }
    }
  `);

  if (result.errors) {
    reporter.panic('failed to create posts ', result.errors);
  }

  const pages = result.data.allMdx.nodes;

  pages.forEach(page => {
    actions.createPage({
      path: page.frontmatter.path,
      component: require.resolve('./src/templates/postTemplate.js'),
      context: {
        pathSlug: page.frontmatter.path,
      },
    });
  });
};

In the createPage function we will use graphql helper to fetch the nodes from the data layer by passing a graphql query as you can see in the snippet above.

Then, we create the pages using actions.createPage as we loop through these pages that came back as an array to generate them programmatically as you can see in the screenshot below

actions.createPage takes an options object as a parameter that has 3 properties: path, component and context.
Path is what we have defined in the mdx frontmatter.
Component takes in the path to the template you want to use for these pages. Below is a sample snippet used as page template.

import { graphql } from 'gatsby';
import { MDXRenderer } from 'gatsby-plugin-mdx';
import React from 'react';

import Layout from '../components/Layout';

export const query = graphql`
  query($pathSlug: String!) {
    mdx(frontmatter: { path: { eq: $pathSlug } }) {
      frontmatter {
        title
        path
      }
      body
    }
  }
`;

const Post = ({ data: { mdx: post } }) => {
  const { title } = post.frontmatter;
  const { body } = post;
  return (
    <div>
      <Layout>
        <h1>{title}</h1>
        <MDXRenderer>{body}</MDXRenderer>
      </Layout>
    </div>
  );
};

export default Post;

Context takes in an object with pathSlug as its property which value is the page path.

Once we finish adding the above, now we can add interactivity to our MDX pages which would look like this

--------
path: '/blog/hello-world'
date: '2020/01/01'
title: 'Hello World'
summary: 'hello world post'
--------

import Counter from '../../../src/components/Counter';

Hello World

<Counter />

Following the post and you can find a starter repo here that shows usage of mdx pages

How to Create Pages Dynamically in Gatsby

Malik Gabroun — Wed, 24 Apr 2019 06:54:16 +0000

In this post, we will be looking into how you can create pages programmatically from data (markdown files) in Gatsby.

In order to create these pages dynamically from markdown, we will be looking into Gatsby's Node createPages API.

However, before we can do that, we need to install a couple of plugins that will source and transform markdown file in order for Gatsby to understand the markdown files path and its content, and be able to create those pages.

To create pages you would need to do the following to make it happen dynamically:

Reading markdown files and transform them

By installing the following plugins

npm install --save gatsby-source-filesystem gatsby-transformer-remark

We tell Gatsby about our content path with gatsby-source-filesystem from the filesystem by passing an options object that contains a variable and file path.

In addition, we can transform those markdown files content to HTML and frontmatter metadata to frontmatter by using gatsby-transformer-remark, which will transform those files into edges that contain node type of MarkdownRemark and each frontmatter fields into GraphQL fields that we can query later in our pages/component and map them at build time.

In order to read the markdown files path and transform them into GraphQL fields, we need to add the following config to our gatsby-config.js after installing the two plugins.

//gatsby-config.js
 `gatsby-transformer-remark`,
{
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `posts`,
        path: `${__dirname}/content/posts`, // for the path you can change it based on your preferred folder structure
      },
},

create page component (template) for markdown files

we need to create a page template component that will be mapped with data (available GraphQL fields that were transformed with gatsby-transformer-remark) using graphql at build time to create these pages dynamically.

In the following below, you can see a simplified example of the post template I am using for the blog posts. Note (you can create as many templates as you want)

import React from 'react';
import { graphql } from 'gatsby';

const Post = ({ data }) => {
  const { markdownRemark } = data;
  const { title, date } = markdownRemark.frontmatter;
  const { html, timeToRead } = markdownRemark;

  return (
    <div>
      <div className="post-wrapper">
        <Title>{title}</Title>
        <div>
          <p>{date}.</p>
          <p>{timeToRead} min read.</p>
        </div>
        <div className="blogpost" dangerouslySetInnerHTML={{ __html: html }} />
      </div>
    </div>
  );
};

Below we can see the specific data (GraphQL fields) are being pulled through and used in the template component above using out of the box GraphQL query.

export const query = graphql`
  query($pathSlug: String!) {
    markdownRemark(frontmatter: { path: { eq: $pathSlug } }) {
      html
      frontmatter {
        title
        date
      }
      timeToRead
    }
  }
`;

programmatically create pages using gatsby's node createPages API

To create a new page, we need to do the following steps

Generate the slug (path) for the page using createPages API
create the page by mapping content (the transformed markdown file) to the page component template

In gatsby-node.js we export createPages API and pass it 2 arguments, graphql for finding the files and actions where createPage is a property of it.

The createPages function will return us a new promise due to the async nature of file creation (alternatively, you can use callback as per the example in gatsby docs).

In order to create these pages, we will need access to the page template using 'path.resolve'.

To change the status of promise to fulfilled, we will need to resolve it by calling graphql and pass it our query for allmarkdownremark with the path field included where we want our posts to live at. (this path field is the one we set in markdown frontmatter metadata).

Additionally, we pass a function to .then that will be invoked once status changed to fulfilled, where we pass our result value to this function. Result will contain a data object that will match our query as you can see in the screenshot.

In the function body, we will use foreach to iterate over each file node (edges are paths to the file system node) to extract the path from those nodes frontmatter.

you can console log node parameter and see the value returned for each markdown file from the query which will be similar to the screenshot below which will indicate what we can expect from the node content.

With path value available to us, now we can call the 'createPage' action which takes in 3 parameters, path for the page url, component to render (page template component) and context object that will be available to page component as a prop.
As we passing context object to template component we want our template to know the path to file which will be called pathslug because path is a reserved keyword and the value of the pathSlug will be the field supplied from node frontmatter. After createPage invocation, we will resolve the promise as you can see in the example below.

exports.createPages = ({ graphql, actions }) => {
  const { createPage } = actions;
  return new Promise((resolve, reject) => {
    // to create the page we need access to the blog post template
    const postTemplate = path.resolve('src/templates/postTemplate.js');
    resolve(
      graphql(
        `
          {
            allMarkdownRemark {
              edges {
                node {
                  frontmatter {
                    path
                  }
                }
              }
            }
          }
        `
      ).then(result => {
        if (result.errors) {
          console.log(result.errors);
          reject(result.errors);
        }
        result.data.allMarkdownRemark.edges.forEach(({ node }) => {
          // you can see node value in the screenshot
          const path = node.frontmatter.path;

          createPage({
            path,
            component: postTemplate,
            context: {
              /*
              the value passed in the context will be available for you to use in your page queries as a GraphQL variable, as per the template snippet */
              pathSlug: path,
            },
          });
          resolve();
        });
      })
    );
  });
};

You can see the result of the grapqhl query in the above snippet when ran in GraphiQl below

Here is a Demo of Gatsby createPages following the post and you can find the repo here

Gatsby Tip on Running Multiple Queries (GraphQL Aliases)

Malik Gabroun — Mon, 15 Apr 2019 05:03:43 +0000

Say you want to fetch specific data in one page based on an argument or a condition which can't be run using one query as you can't query the same field with different condition or argument. One way of doing that by using GraphQL aliases which you can use to rename the returned dataset to anything you want.

Example

export const query = graphql`
  query {
    post: allMarkdownRemark(
      limit: 3
      sort: { order: DESC, fields: [frontmatter___date] }
      filter: { frontmatter: { type: { ne: "portfolio" } } }
    ) {
      edges {
        node {
          timeToRead
          frontmatter {
            title
            path
            date(formatString: "DD MMMM YYYY")
            summary
            images
            tags
            type
          }
        }
      }
    }
    portfolio: allMarkdownRemark(
      sort: { order: DESC, fields: [frontmatter___date] }
      filter: { frontmatter: { type: { eq: "portfolio" } } }
    ) {
      edges {
        node {
          frontmatter {
            title
            path
            images
            tags
            type
          }
        }
      }
    }
    siteMetaData: site {
      siteMetadata {
        title
      }
    }
  }
`;

Looking at the above example, we can see the query I made will return multiple datasets by giving it an alias which allowed me to run multiple queries with different arguments and conditions to get the specific data object I needed as you can see in the screenshot.