Forem: andrzejwp

How to move from WordPress to Jamstack using our Gatsby WordPress Starter

andrzejwp — Tue, 04 May 2021 07:59:17 +0000

This article originally appeared as a blog post on Flotiq.com

Let’s say that you are the owner of a WordPress site and you have heard about Jamstack, the “modern way” to build websites. You want to check if this approach is good for a WordPress replacement. Using Gatsby WordPress starter and migration tools you can test it in just a few minutes.

When you have a WordPress site with data, you could be worried about the migration, creating a new Gatsby template, and deploying your new site. These things can stop you from deciding to check the Jamstack way of developing your project. Let’s see how to move your WordPress to a Gatsby template without pain, in 2 simple steps.

Next, optionally, we set up the project live via Netlify, and configure Netlify Plugin in Flotiq, to simplify the build process to one-click action.

In the next steps, we assume that you have an account in Flotiq (click here to register for free).

Step 1: Migrate data to HeadlessCMS

The first step is to migrate your data to Headless CMS. We recommend using our migration tool. Go to the WordPress to Flotiq migration service, fill in the required data and start the import. This process will import your media, posts, pages, authors, tags and categories.

Check your Flotiq Account after the migration is done.

Now your data is stored in the Headless CMS and you can manage it in Flotiq. But we want to achieve more - let’s set up a brand new site based on this data.

Step 2: Setup starter locally

Now we can use our Gatsby Starter - WordPress Blog. For detailed instructions check the project’s GitHub repository.

Run the project from a template using Flotiq CLI. Type the following commands:

npm install -g flotiq-cli
flotiq start [flotiqApiKey] [yourProjectName] https://github.com/flotiq/gatsby-starter-wordpress-blog

The flotiqApKey is your Read and write API key to your Flotiq account, and yourProjectName is your custom project name.

This script will download the starter, add the required configuration to the .env file, install dependencies and run gatsby.

Wait a moment, and that’s it! Your site is now running at http://localhost:8000. To exit the process type Ctrl+C.

Next - start developing. Use your favourite IDE to edit project files. There are commands you would use to develop a project

gatsby develop - build again your site and expose it on the localhost:8000
gatsby clean - clear cached data (like posts, media)
gatsby build - build the site for production environment
gatsby serve - view the production site locally

To learn more about Gatsby development process check this tutorial.

Now you can develop and test your site, learn Gatsby and check the Flotiq features. You can also take the next extra steps to publish your site on the Internet.

Step 3: Deploy your site to Netlify (optional)

You can go live with your site in multiple ways. One way is to simply copy your files from the public directory (created after running Gatsby build) to your server. This fully static page will serve your content without a backend.

Another way is to use a deploy solution like Netlify. The benefit of this solution is that you can configure automatically build after pushing to the repository or even rebuilding directly from the Flotiq dashboard (using Netlify Plugin).

1. Create your project repository in GitHub

Netlify will use your repository to fetch files, run build commands and publish your website. Create an empty repository for your project:

2. Push your project to the newly created repository.

GitHub will show you tips to quickly set up your repository - follow the part …or push an existing repository from the command line. In projects directory type:

git remote add origin git@github.com:[accountName]/[projectName].git
git branch -M main
git push -u origin main

Now your files are stored in GitHub with all benefits of using version control.

3. Setup Netlify site

Now let’s publish our site. We will use Netlify for this step. To create a site go to the Netlify dashboard. We will create a site from the Git repository.

Click the New Site from Git.

Choose GitHub as the project source.

Find your new repository.

Add variable GATSBY_FLOTIQ_API_KEY with your flotiqApiKey (like we do in local setup, in the .env file).

Next, click the Deploy site button, and wait 2-3 minutes. When the status change, click on your new automatically generated address.

It’s your site, live on the Web. Congratulations!

You can change your site URL, or even bind your domain - for further information check the Netlify Docs.

Step 4: Use the Netlify plugin in Flotiq to deploy your site automatically (optional)

For now, every time when you push to the main branch, your site will rebuild automatically. That’s a convenient solution. But what if we want to rebuild the site every time when creating data in Flotiq? Follow these steps to enable the Build Site button in Flotiq.

Go back to the Netlify dashboard. Add a build hook in the Build & Deploy settings. The name of this webhook is up to you:

Once the hook is created, you get your custom website hook.

After these steps, you can not only manage your data in Flotiq Headless CMS. You can also trigger a rebuild of your site by clicking Build site.

Now your site is live, and you can easily manage the site content. You can take the benefits of Headless CMS and the Gatsby ecosystem.

Next steps

Use the data stored and managed in Flotiq in multiple ways, building other websites or mobile applications. Extend your project scope by adding new functionalities like e-commerce or a map with a store locator.

Migrate WordPress to Flotiq Headless CMS

andrzejwp — Mon, 30 Nov 2020 13:13:08 +0000

This article originally appeared as a blog post on Flotiq.com

TLDR;

Moving from WordPress to a headless CMS is a matter of time for many projects.
Trying new solutions is easier when you can rely on pure content.
Flotiq provides a one-click solution to migrate data from WordPress to our headless CMS.
After importing the data you can use Flotiq benefits - personal APIs, API docs, SDKs, Postman Collections, and so on.

Decision about migration

Once your project grows, you may start getting disappointed with WordPress. We've already talked about some common culprits of WordPress in our previous article.

When you already know you need more - you will want to try other systems. But what with your existing data, the endless hours spent building those hundreds of blogposts? This question often stops developers from making a decision to switch to other systems. They see a painful migration on the horizon.

Migration? Try our one-click tool

At Flotiq we understand our fellow developers and embrace the fear of migration. We created a simple tool for migrating your data from WordPress to our Headless CMS. All you need is your personal Flotiq Read And Write API Key and of course your WordPress Site address. Read on to see how easy it is.

1. Get your API Key

To create a Flotiq Account go to the register page. Next, copy your Read and Write API key from Flotiq Dashboard.

2. Use our migration service

Go to the WordPress to Flotiq migration service, fill in the required data you already have, and start the import. This process will import your posts, pages, tags, and categories. It takes care of your media also and will transfer it to your Flotiq Media Library.

3. That's it. Check your data in Flotiq

Now, check your Flotiq account. You will see new Content Type Definitions. Remember, that you can modify imported data and schemas to fit your needs.

Look over the imported data.

Instant benefits

Now, when your data is imported you can manage it in Flotiq. You can also go a step further. Once the content types are created, you now have access to:

personal API Doc,
personal SDKs,
personal Postman collection.

Below you can see the Postman Collection imported from your account, using your imported data. You can use it as a playground or share it with your team.

Next steps

Learn more about Flotiq Dashboard
Learn more about Flotiq Dynamic Content API
Create your site with Gatsby using our Gatsby Starters.
Try to migrate WordPress data using our Flotiq CLI.
If you have any questions let us know on the Discord channel.

Product showcase mobile app in React and Flotiq

andrzejwp — Tue, 15 Sep 2020 09:01:23 +0000

React-native mobile product showcase

This simple guide will show you how to adapt the Flotiq Mobile Expo application source code to work as a product showcase app.

You will build a mobile app that will let your users:

browse through the list of products,
read product details,
search through the product list.

The app will be synchronized with your Flotiq account, so you can use the CMS to add and update products and it will compile for Android and iOS phones, out of the box. The code changes required in this guide are minimal, but it might take some time to setup the working environment, both for Android and iOS.

Prerequisites

We encourage you to download the Flotiq mobile expo application from your Google Play or Apple App Store and connect it with your Flotiq account. This way you will understand how the application works and what you can expect.

The article assumes:

you already registered a free Flotiq account
you know how to retrieve your API keys.

Here are the remaining essentials:

Fork the application repo

Go to Flotiq Mobile Expo on GitHub and fork our repo. You will be making some changes to the code and it will be easier to keep track of it later on. Don't forget to give us a star if you find it useful!
Setup your workspace
- Install XCode on your Mac or
- Install Android Studio, for example through JetBrains Toolbox. Once installed - launch it and install an emulator with a recent Android Virtual Device
- Clone the git repository you just forked or use ours: git clone https://github.com/flotiq/flotiq-mobile-demo
- Install node dependencies in your project directory: npm install
- Start the iOS emulator npx react-native run-ios
- Or start the Android emulator npx react-native run-android
This should bring up the emulator and launch Flotiq app.

The screen you will see allows you to connect with your Flotiq account, but we will do this through a simple change in the source code.

If you have any issues - consult the README file in the application repo.

Code updates

Here are the steps needed to connect the app to your Flotiq account and simplify it, so it only displays the products.

Authenticate with your Flotiq API key

The code in the repository uses a login screen to authenticate with your API key. We won't need that for our Product Showcase application, but we still need to authenticate with the Flotiq API.

Login to the Flotiq dashboard
Create a scoped API key for the Product and Media content types
Copy the key.
Now save it in your React code, by adding the following line to the App.js file:

    import FlotiqNavigator from './app/navigation/FlotiqNavigator/FlotiqNavigator';
    import contentTypesReducer from './app/store/reducers/contentTypes';
    import authReducer from './app/store/reducers/auth';

    // Add this line after imports:
    AsyncStorage.setItem('flotiqApiKey', "<< YOUR FLOTIQ READ-ONLY API KEY HERE >>");

    enableScreens();

Once you save the file - the application should automatically reload in the emulator and the login screen should be skipped. You should now see the application's home screen:

Simplify navigation

For our Product Showcase app we would like to skip to the product list immediately, instead of showing the default Home screen and Content Type browser screen. To achieve that - you will need to update how the navigation is structured.

Open the StackNavigator.js file and make the necessary adjustments:

Remove the {{HomeStackScreen()}} line in the RootStackNavigator component,
Remove the entire Stack.Screen called ContentTypesScreen in the ContentTypesStackScreen constant,
Make the following adjustments in ContentTypeObjectsScreen.js
comment out the first line add the following constants:

    //const { contentTypeName, partOfTitleProps, withReachTextProps, refetchData, contentTypeLabel } = props.route.params;
    const contentTypeName = 'product'
    const partOfTitleProps = ['name']
    const withReachTextProps = ['description']
    const refetchData = true

Now, to properly hide the splash screen - add the following import statement:

    import SplashScreen from 'react-native-splash-screen';

and add the following useEffect() before the first one appearing in the file:

    useEffect(() => {
        if (!isLoading) {
            SplashScreen.hide();
        }
    }, [isLoading]);

Finally, in the contentTypeObjectsScreenOptions method - replace the screenTitle const with a static one:

    const screenTitle = "Products"

Here's the full list of changes that have to be made to simplify the original app, in case you missed something.

Effects

That's it! You should now see the product list immediately after the app has loaded:

Now, you can go and play with it or publish it straight to the App stores. The original application has already been approved by Apple and Google stores, so it should be a quick and easy task to get your app approved too!

Some ideas you can try:

add product images to the list,
modify the product detail screen,
remove add / edit content buttons.

Have fun, and tell us what you built!

Building a banner rotator with an admin interface

andrzejwp — Tue, 23 Jun 2020 13:48:01 +0000

This article was first posted as a Flotiq Deep-Dive.

This quick tutorial shows how you can build your own system that can rotate ads on your website. You can easily adapt it to many other solutions and several techniques shown here may come handy in different projects.

Requirements:

easy to use interface for administering ad banners,
banner admin system decoupled from website CMS,
option to group banners, for example vertical / horizontal,
no changes to existing Web CMS code.

Plan:

prepare a data model in Flotiq headless CMS,
generate a read-only API key,
write a simple script to load banners and display random one,
attach the minified script to the website.

1. The Content Type Definition

The first step will be to define the data model. In Flotiq you do that by creating a new Content Type Definition. You can start with something simple - Flotiq supports iterative development because you can change your Content Type Definitions any time and adjust them to changing needs.

Since one of the requirements is the ability to group banners together - we can create a single Content Type Definition that will reflect a Rotator which will be composed of an array of Banner objects. In our case we chose not to build a separate Banner type - we'll simply add the required properties using Flotiq's List field.

Here are the properties we will require:

Name (text)
Width (number)
Height (number)
Banners (list)
- Enabled (boolean)
- Image (media)
- Link (text)
- Title (text)

after adding that into a new Flotiq Content Type you should see the following:

Hit Save and you can start adding new Rotators!

2. Create an API Key

It's always recommended to use a scoped API key - that way access to content is restricted to specific Content Types and even if you add new data models in the future - your data will be safe.In our case - we will need access to 2 Content Types - Rotator and Media, so let's add a key for that purpose.

3. Build the rotator script

The rotator script should pull a particular rotator, randomly select one of the banners and display it in the target HTML container.

The HTML container can look like this:

<div data-rotator-id="__ROTATOR_ID__" 
     data-rotator-key="__FLOTIQ_SCOPED_READ_ONLY_KEY__">
</div>

and here's a very simple JavaScript that downloads the banner and shows it in the target container:

<script>
let initRotator = function (linkElement) {

    /* Build html element with banner */
    let createHtmlBanner = (src, title, link) => {
        let anchor = document.createElement("a");
        let image = document.createElement("img");
        anchor.href = link;
        anchor.title = title;
        image.src = src;
        image.alt = title;
        image.classList.add('img-responsive', 'img-fluid');
        anchor.append(image);
        return anchor;
    }

    /* Get elements data */
    const rotatorId = linkElement.getAttribute('data-rotator-id');
    const readOnlyKey = linkElement.getAttribute('data-rotator-key');

    /* Fetch data from Flotiq API */
    fetch(`https://api.flotiq.com/api/v1/content/rotator/${rotatorId}?hydrate=1&auth_token=${readOnlyKey}`)
        .then(response => response.json())
        .then(rotator => {
            let enabledBanners = rotator.Banners.filter((banner) => banner.enabled === true);
            let randomBanner = enabledBanners[Math.floor(Math.random() * enabledBanners.length)];
            if (enabledBanners.length) {
                linkElement.innerHTML = '';
                linkElement.append(createHtmlBanner(
                    `https://api.flotiq.com/image/${rotator.Width}x${rotator.Height}/${randomBanner.image[0].id}.${randomBanner.image[0].extension}`,
                    randomBanner.title,
                    randomBanner.link));
            }
        });
    }

/* Initialize rotators */
document.querySelectorAll('[data-rotator-id]').forEach((element) => {
    initRotator(element);
})
</script>

Who! That's not even 40 lines of code and we have a working ad rotator!

4. Simple CDN - GitHub + jsDelivr

One of the goals is to have a solution that will not change any CMS code and as such - can be used with any CMS tool. For that purpose we'll put the script on GitHub and serve through jsDelivr. How does this work?

Start with creating a public GitHub repo
Put the script in that repo
jsDelivr will do its magic

The only thing you need to do is prepare a correct URL. According to jsDelivr docs you can use https://cdn.jsdelivr.net/gh/[user]/[repo]@[version]/[file]. If you add .min.js to the URL - the CDN will automatically minify the file for you.

With that - we don't need to put the entire script on our website, it's enough to reference it. The full banner rotator setup is then reduced to pasting these lines in your HTML:

<div data-rotator-id="__ROTATOR_ID__" 
     data-rotator-key="__FLOTIQ_SCOPED_READ_ONLY_KEY__">
</div>
<script src="https://cdn.jsdelivr.net/gh/trzcina/flotiq-rotator@1/src/script.min.js" defer></script>

This code can be pasted in any CMS. Here's how it looks in BoltCMS

and Wordpress

Next Steps

The solution shown in this article meets the basic requirements and is ready to use.Possible next steps are:

ability to choose if the link should open in a new tab
sending out a click event to Google Analytics
ability to add AdSense ads to the Rotator.

Heads up! Try not to use ad or adv or banner in your paths and filenames. This way your chances of triggering AdBlock tools are lower!

Use Netlify, Zapier and Gatsby to instantly deploy your CMS content

andrzejwp — Thu, 30 Apr 2020 15:39:06 +0000

This article was originally posted as a Flotiq Deep Dive.

Overview

In this article, we'll setup an extremely powerful, yet totally effortless (and free!) deployment pipeline for your Gatsby websites. We'll use Netlify as a deployment target, so no servers required.

Why?

Gatsby is a static website generator. What that means is - your content won't update, unless you rebuild and redeploy your website. This might quickly become a bit of a pain if you're doing content updates often, or if the person doing these updates doesn't know how to rebuild your site.

You can easily set up GitHub hooks to update your website when your code changes, but that doesn't work for content changes.

Go explain to a copywriter that they need to gatsby build and npm run deploy every time they update the website's content!

What you want to have is an automated process that will publish the website once your content is updated.

This article covers step by step guide, how to:

Setup your data source using a Gatsby Starter and Flotiq
Setup your page deployment in Netlify
Setup an automation workflow in Zapier

In the end - whenever you update your page content in Flotiq, Zapier will trigger deploy process in Netlify to make sure your site is up to date!

Let's dive deep.

Prerequisites

Netlify Account (free) Sign up for Netlify
GitHub/Gitlab/Bitbucket account (free) Sign up for GitHub
Zapier account (free) Sign up for Zapier
Flotiq account (free) Register a Flotiq account here.

Grab one of our Gatsby Starters!

Head out to our Github repository and pick one of Gatsby starter projects. Let's use the popular Gatsby Recipes Starter.

gatsby new gatsby-starter-recipes https://github.com/flotiq/gatsby-starter-recipes.git
cd gatsby-starter-recipes

You can either build the Content Types yourself or use our predefined content

node ./example/importExample.js

This handy command will add 4 images and 2 recipes to your Flotiq account.

Each of our gatsby starters has a "Deploy to Netlify" button at the bottom of the README:

Click it:

Configure your Netlify site deploy

You'll now see a 3-step configuration process, that involves:

Connecting to your GitHub account
Setting up required parameters for deploy
Deploying your site

Connect your GitHub account and head on to the next step.

In the next view, you will be prompted to enter 3 parameters:

Repository name - this is where Netlify will create a new repository for you.
Flotiq API url - enter: https://api.flotiq.com
Your Flotiq read-only API Key.

We advise that you always create a scoped API key. Its disposable nature makes it a safer choice. More about Flotiq API Keys here

After filling in all the fields, hit the Save & Deploy button and wait for your site to build.

That's all! You will be redirected to your Netlify dashboard. You can check the build logs by clicking here:

Manage Netlify deploys using Zapier

By default, Netlify will observe any changes in your repository, so any push will trigger a build on Netlify. This is usually what you want because you might be pushing some new features to your website and you want them to automatically appear online.

But your website is not just the code in your repository. You want your content to be up to date too! We'll show you how to use Zapier to update your website every time you create new content.

Log in to Zapier
On your account dashboard, hover over the left sidebar and click Make a Zap.
As a trigger application, choose Flotiq, and for the event New Content Object.
Next, choose your Flotiq account and click Continue.
Choose your Content Type Definition from the list.
Click continue. You can skip the test phase and proceed to the next action.
Choose Netlify as an action application, and Start deploy as an event.
Sign in to your Netlify account and proceed further.
Select your site from the list. Alternatively, you can choose to clear build cache, but it will increase the build time.
In the last step, you can test if this action works properly. It will rebuild your site.

That's it

You're set! Click Turn the Zap On!. Now you can create a new entry in the Flotiq editor and see that your recipe will appear on your website in a moment.

Useful links

Learn more about building powerful integrations with Zapier and Flotiq:

More about Zapier Integrations in Flotiq

Or try one of the awesome Gatsby starters we've integrated with Flotiq:

Building a recipes website using Gatsby and Flotiq

andrzejwp — Tue, 21 Apr 2020 18:10:51 +0000

This article was originally posted as a Flotiq deep dive on using complex data structures

Introduction

When you're ready to take your headless CMS to the next level and start building data models that are a little more complex you'll find that standard, fixed data types will be too restrictive. Flotiq has always supported building relationships between Content Types, but sometimes that's not enough.

In this article we'll discuss a couple of particular problems you might encounter when designing a data model and later - when working with it. Accidentally - we'll also build a stunning website with your favorite culinary recipes (scrambled eggs, of course!).

A simple Recipe model you might find useful for a recipe website could look like this:

Name - text
Slug - text
Image - image
Description - rich text
Ingredients - rich text
Steps - rich text
Cooking time - number
Servings - number

For such a model - Flotiq would generate a form looking like this:

and your API docs would describe that model this way:

This model might be acceptable for very simple websites, but having the Ingredients and Steps entered as unstructured text (even if using HTML <li>) will soon become an issue.

Here's why:

No easy, programmatic, access to ingredients - eg. no way to build a shopping list out of it
Can't easily iterate through the recipe's steps - difficult to build an interactive UI, doesn't help with SEO either
People editing the content will use different formatting every time and the content will quickly become messy. You'll get entries like:

    2 eggs
    1 pinch of salt
    1 tbsp of butter

- Eggs: 2
- Salt: 1 pinch
- Butter: 1 tbsp

<ul>
    <li>2 eggs</li>
    <li>1 pinch of salt</li>
    <li>1 tablespoon of butter</li>
</ul>

and so on.

Solution

The problem of unstructured data can be solved using repeatable content fragments defined directly in a data model. It's a simple and convenient solution - both for developers modeling data and content editors as well.

Here's how you would go about it with Flotiq's list data type:

Benefits:

Less mess, providing structure without the need to create additional content types.
The list data type will render as a set of sub-forms - makes it easier for content editing.
Easier data access from the API - more readable data structure.
Easier to interpret complex data on the frontend.

Use case: Recipe content type

Now - let's apply the list data type to the recipes Content Type. Let's assume each step will include a description and an optional image and every ingredient - it's amount, unit, product name.

We can now extend the example mentioned above:

Name - text
Slug - text
Image - image
Description - richtext
Ingredients - a list of:
- amount - number
- unit - text
- product - text
Steps - a list of:
- description - textarea
- image - image
Cooking time
Servings

Your Content Type definition in Flotiq would then look like this:

and you would expect this in the API docs:

Yup, we know, we're drooling over Flotiq's API docs every time, too. And you know what? You don't need to write a line of code - the docs, just as your entire RESTful API are generated every time you change your model definitions!

And this is how the form for that Content Type would render:

We used the list datatype in this Gatsby & Flotiq recipes starter and you can see the results here. With this data model it's now really simple for a frontend developer to interpret that content on the website.

Experiment with the Gatsby starter

If you'd like to dig a little deeper into this recipe website, here's your quickstart:

Install gatsby
```
npm install -g gatsby
```

Start project from the template using Gatsby CLI

gatsby new gatsby-starter-recipes https://github.com/flotiq/gatsby-starter-recipes.git

Setup "Recipe" Content Type in Flotiq

Create your Flotiq.com account. Next, create the Recipe Content Type:

Note: You can also create Recipe using Flotiq REST API.

Configure application

The next step is to configure our application to know from where it has to fetch the data.

You need to create a file called .env inside the root of the directory, with the following structure:
```
GATSBY_FLOTIQ_BASE_URL="https://api.flotiq.com"
FLOTIQ_API_KEY="YOUR FLOTIQ API KEY"
```
Launch the Gatsby project

Navigate into your new site’s directory and start it up.
```
cd gatsby-starter-recipes
npm install
gatsby develop
```
Open the source code and start editing!

Your site is now running at http://localhost:8000!

Conclusions

Flotiq's list data type is an extremely easy to use solution for structuring your data. It organizes the content and makes it easy for content editors to build content, at the same time it's fully supported in the API and API docs.

Go play with the recipe website project - we've shared a Gatsby starter for that:

Build an e-commerce site with Gatsby, Snipcart and Flotiq

andrzejwp — Thu, 09 Apr 2020 09:44:38 +0000

Times are tough, so many businesses are trying to move their sales online. So - this time, we'll dive deep into building e-commerce with Snipcart, Flotiq and Gatsby.

We'll start with a fresh Flotiq account, build a Content Type Definition, hook it up with a Gatsby starter and finally - deploy it live using Heroku.

What you'll get:

A simple, but beautiful, functional e-commerce website with your own products, running live on the Internet.

What you'll need:

Flotiq account (free),
Snipcart account (free for testing), register here
Node.js & NPM installed
This repository
Heroku account (free) if you'd like to put it live.

Let's get started!

Prepare your Flotiq account

For this particular project - we'll use Flotiq to store the information about products - names, prices, etc.
There's a couple of simple steps that shouldn't take longer than 1 minute to complete.

Register an account, 30 seconds

The first thing you'll need is a free Flotiq account, register a free account in Flotiq. No payments, no credit cards, simply connect using your Github account or email.

Create your Content Type Definition, 30 seconds

The most crucial step - you have to tell Flotiq what kind of data you want to store in the system. What are the names of the content types and their properties.

When you first log in - it's going to be pretty empty. No content, nothing. Head over to the Type definitions screen.

Here you find a list of simple boilerplate content types, which are a great start if you're in a hurry.

Click on Product and then Save. You don't need to make any changes to get up and running with this project!

Create your content, 2 minutes

For this project to work - you have to create a couple of products. In the left sidebar click on Content → Products and click the Add new Product object button.

Enter the product detail.

You can upload your images or use our awesome Unsplash integration - head over to the Stock photos tab in the Media Library and browse through thousands of beautiful images.

Finally - click the Save button.

Repeat for as many products as you want.

Hint: If you'd like to programmatically import hundreds or thousands of products, instead of typing them by hand - you can use Flotiq's batch endpoints in your API. Read more about batch content creation in Flotiq.

Start your Gatsby project, 2 minutes

To make this extremely simple, we have prepared a Gatsby starter, that integrates with Flotiq as a data source for products. You will configure the project, install its dependencies and put the site live in no-time.

Clone the repo

Start by cloning the repository:

git clone https://github.com/flotiq/gatsby-starter-products

Configure Flotiq

Then, in the root folder of the repository create a file called .env. This file store the configuration for Flotiq and Snipcart. Put the following contents in the .env file:

GATSBY_FLOTIQ_BASE_URL="https://api.flotiq.com"
FLOTIQ_API_KEY="YOUR FLOTIQ API KEY"

You can find your Flotiq API keys in the user profile section of the interface:

Caution: We strongly recommend that you create a scoped API key (read more about API access), but for development, you can use the default Read Only key provided in the interface.

Check if it works!

It's as simple as that. You should be good to go. Install the NPM dependencies and start your gatsby project:

npm install
gatsby develop

You should now see your store at http://localhost:8000.

Start selling online

Yes, it is that simple.
You're almost ready to start selling; the final part is to configure Snipcart properly.

Configure Snipcart

Head over to Snipcart and in your account - retrieve your Public API Key.

Put that key in the .env file, so the file now looks like this:

GATSBY_FLOTIQ_BASE_URL="https://api.flotiq.com"
FLOTIQ_API_KEY="YOUR FLOTIQ API KEY"
SNIPCART_API_KEY="YOUR SNIPCART KEY"

and restart gatsby with gatsby develop.

Here's what you should now see, once you put an item in the cart:

Once you complete the checkout steps, you'll see the final screen:

But if you try to place the order from your local machine - it will end up looking like this:

So - if you want to test the integration entirely - it's time to put this site live!

Putting the website live using Heroku, 2 minutes

To make it super simple - we've prepared a button, that immediately put your project live on the Internet.

Press the button!

Once you log in to Heroku (you can use a free account for that) - you have to pick a domain name for your project. We used snipcart-flotiq.

and then copy the details from your .env file in the input fields

and hit Deploy app. In a minute (or two) - your app is live!

!!! hint
If you'd like to host this project under your own domain name, you can use the wonderful and free service provided by Cloudflare and this hack to add a custom domain to a free Heroku account. Normally - you would have to pay for that in Heroku, but hey - times are difficult.

Provide the domain name in Snipcart

While you're waiting for the deployment to finish - go to your Snipcart profile page and configure your domain name:

Verify the result

Result? You've successfully placed an order!

And you immediately see it in Snipcart, too.

Conclusions

You've successfully built and deployed an end-to-end e-commerce platform using no code, thanks to the tools and templates provided by Flotiq, Snipcart and Gatsby. While there are still many important things to consider before you launch your e-commerce - this is a great way to minimize the cost and effort required on the technical side.

As always - let us know how it worked for you!

This article was originally published as a Flotiq Deep Dive Start selling online with Snipcart, Flotiq, Gatsby and Heroku

Fast-track your Angular projects with a headless CMS library

andrzejwp — Wed, 01 Apr 2020 23:06:38 +0000

This article first appeared as a Flotiq Deep Dive on Angular 8 and Flotiq headless CMS

In this article we're going to show you how you can integrate a Flotiq SDK package in your Angular project in order to get full access to your content stored in Flotiq.

Using Flotiq's SDKs is the most convenient way to connect to a headless CMS system because your models are going to be exported exactly in the way you designed them. You will be able to use your IDE's built in code completion features and at the same time you will read and write content from your Flotiq Headless CMS account.

Prerequisites

Flotiq account
At least one your own Content Type in Flotiq (we will use Blogpost as an example)
Generated Angular package that you can download from your Flotiq Dashboard page.
Little knowledge of rxjs

Additional information: We used Angular 8.3.25 in this example, but it shouldn't be a problem if you use the newest one (for now it's Angular 9).

Overview

About packages

We decided to give developers a hand by automatically generating a library package that contains all the required elements to get you started with the Flotiq API. Thanks to Flotiq's adoption of the OpenAPI schema and the Open API Generator it is possible to work with various frameworks or programming languages.

Package overview

When we extract the downloaded package we will see some directories and typescript configuration files. We are interested mostly in only two positions:

/api directory, which contains services for every content type object definition as well as for some internal types like media and also for functionalities like graphQL and search.
/model directory, which has all Content Type Definitions that exists on your Flotiq account. They are implemented as exported interfaces with the following template body:

Example:

Package installation

Download Angular package from your account dashboard
In package directory run:

npm install
npm run build

This will create a dist directory, which will be used for installing your package in project.

Go to generated dist directory and run:

npm link

In your application directory:

npm install
npm install <path_to_your_package>/dist
npm link flotiq

And that's all. Basic setup is done!

IMPORTANT! There are known issues with npm link on Windows OS, but they only concern installed packages via path, not registry.

Package usage

In your project app.module.ts file import following classes:

In environments directory are two env files. Add your API_KEY as a key-value pair in your environtment.ts file, so it should look like this:

If you plan to deploy your application, remember to fill out environment.prod.ts file too!

Next, you have to export a function that will hold all needed configuration to work with Flotiq. You can include it in your app.module.ts file below the imports. As a minimum only your API_KEY is required:

For the final step add Flotiq ApiModule into providers array in your application AppModule. You must call fotRoot() function on ApiModule providing required configuration that you set step before:

ApiModule.forRoot(apiConfigFactory);

It's important to also import HttpClientModule from @angular/common/http. Otherwise you won't be able to make API calls to Flotiq.

Your @NgModule decorator should look like that after whole setup process:

Example Service (Blogpost)

Create a simple service file blogpost.service.ts

Export a class and provide an @Injectable() decorator, so you can inject other services into this service. Remember to import it from @angular/core.

To make this service application-wide pass an parameter object {providedIn: 'root'} to Injectable decorator (it's a shortcut, you can also import and add your service to providers array in app.module.ts file)

Your file should like this:

Next, import your Blogpost model and ContentService provided by installed package.

import { ContentBlogpostService, Blogpost } from 'flotiq';

Next, create a constructor and add your ContentService

constructor(private blogpostApiService: ContentBlogpostService) {}

blogpostApiService is just example variable name, you can change it if you like.

Add a simple method (for example addBlogpost) which will take any value as an argument, but it's preferred that it has Blogpost model type.

addBlogpost(blogpost: Blogpost) {}

In the body return a result of ContentService function, so you can subscribe to it later and handle response and errors.

addBlogpost(blogpost: Blogpost) {
    return this.blogpostApiService.createblogpost(post);
}

It's important here to pass an object of type Blogpost here, because in other cases types will mismatch and Typescript will throw an error.

That's all! Implement the rest of methods and use your custom service in other parts of your application.

Look into your generated package to find what models and ContentServices where created for you and start developing!

Here is a small animation that shows you an example project based on generated package(To-do-list content type definition used) and Tailwind CSS:

Important information

When you start your application use npm start instead of ng serve. This will avoid confusion and incompatibility with your global installed angular-cli and it's dependencies with those specified in package.json file.

Conclusion

Generated package based on your OpenApiSchema is a powerful tool, that can speed up your development process a lot. You can install it in your project and don't worry anymore about writing API calls

Helpful links:

Learn how to get your own OpenApiSchema here.
Didn't find a package in a langauage or framework you love? No problem check this link to learn how to generate your own!

JAMstack full-text search with Flotiq search API

andrzejwp — Wed, 25 Mar 2020 16:33:19 +0000

This post was originally published as a Flotiq Search API deep dive

Overview

Flotiq provides a powerful full-text search capabilities by partially exposing the ElasticSearch (ES) engine inside Flotiq's search API. In order to provide the best Developer Experience we're not exposing ES directly, but wrapping it and stripping to leave only the essentials.

We still pass queries to ES, but to provide compatibility with the rest of the API we abstracted it one level higher into a wrapper that can allow us to do all the magic and still maintain Flotiq's natural simplicity.

In this article we will focus on search operations like:

Global Search (all content types)
Limited Search (particular content type)
Limited Search using filters (objects with specific attributes)
Results aggregation (a.k.a. faceted search)
Results ranking / scoring (using ES field boosting).

Remember to check our Flotiq Search API Documentation for more details and examples.

For this article's purpose we will use Postman to provide request examples and responses.

On the screenshots below you'll see values like api_url and content_type. These are our own Postman Global Variables so remember to change them to your own values if you want to test Search Feature.

Let's dive deep into it!

Global search

By default, you would probably want to find everything related to a entered query. This is what most of our competitors offer as well, so no surprises here.

To achieve that you have to pass the query parameter q. The result set will contain all entries in your Flotiq instance that match the query content.

The response object also contains:

total_count - number of found entries,
count - number of entries on current page,
total_pages - number of pages,
current_page - ehm, current page,
summary - object containing aggregates / buckets,
data - the array containing matched entries.

Limited search

The /api/v1/search endpoint also supports parameters that can narrow the search or limit display count per page:

limit - basic parameter for limiting per page results
content_type[] - narrow search area to specific Content Type Definition. Don't forget you have to add square brackets [] to a parameter name here. We have provided an example below:
fields[] - restrict to search only in specific field names ex. name, title

So if you'd like to narrow down the search to a specific content type, e.g. blogpost - it's as simple as adding content_type[]=blogpost to your search query.

Limited search using filters

We can also add a filter to our query to search for specific values in provided fields.

Remember, it must have the following syntax: filters[propertyName]=propertyValue.

If you want to have more filters then add more parameters using syntax above by separating them with & like this filters[status]=draft&filters[type]=post.

Results aggregation

This is, by far, one of the coolest features described in this article. Using this technique you'll be able to immediately build faceted search results that look like this

Simply add aggregate_by[]=value parameter to populate the summary object in your response - it will now contain the numbers of unique occurences per property value that you provided earlier.

The part of response that is interesting us in this case looks like in image below:

Increase search score by using ElasticSearch field boosting

And finally, probably the most sought after and extremely powerful features that will allow you to define how your search results should be ranked. With this technique you can decide what is more important in your search query and display desired result in an order that matches your defined importance.

Achieving it is - again - extremely simple. You only need to add fields weights using the fields parameter like ^3 or ^5 or whatever multiplier you want to set.

For example if you define your field boosting like this:
fields[]=category^2&fields[]=title^5

you basically say that entries matching your query in the title field will be considered more important than those, where the match is in category. The order of the results returned by the search endpoint will reflect that and you will also find the score assigned by ES in the score property for each entry.

The request above produces a response like the following:

Search score for text found in title

{
    ...
    "score": 5.0425596
}

Search score for text found in content

{
    ...
    "score": 2.0425596
}

Conclusion

Flotiq is built to be extremely easy to use, yet very powerful. Our search feature is trivial to use, but at the same time offers features that make us stand out from out competitors (see Headless CMS Full-text search comparison article). Using Flotiq's search you can now build a complex search engine into your apps without the need to worry about integrating with external solutions.

Headless CMS full-text search comparison

andrzejwp — Wed, 11 Mar 2020 12:41:32 +0000

This article originally appeared as a blog post on Flotiq.com

Most of the CMS systems on the market offer some level of support for full-text search, some of them are quite sophisticated, some are actually pretty poor. This article compares the search capabilities of Contentful, Prismic, Flotiq, Gentics Mesh, Cloud CMS and Butter CMS.

Prismic

Prismic offers a wide variety of search capabilities. It doesn't matter if you want to search within a single data type or in the entire database - you can use the same mechanisms and APIs.

Advantages of Prismic full-text search

Prismic's query predicates are a powerful, and easy to understand, concept and are supported by comprehensive documentation.

Prismic's docs also provide code snippets for many popular languages, which is also a plus.

Disadvantages of Prismic full-text search

It doesn't seem that Prismic provides any sort of scoring within the search results and the response is simply based on "match" or "no-match".

Contentful

Contentful also supports full-text searches through their API, but it seems very basic.

Advantages of Contentful full-text search

The search API is easy to use and understand.
Their API provides support for geo-based queries, useful for searching objects within a distance from a given location.

Disadvantages of Contentful full-text search

The search API is minimal and Contentful admits that in their documentation:

There are no aggregations or result scoring support.

Flotiq

Flotiq (yes, that's us ;) ) provides extensive full-text search capabilities by wrapping Elasticsearch in Flotiq APIs.

Advantages of Flotiq full-text search

Flotiq's full-text search is based on queries passed to Elasticsearch, which is a very powerful full-text search engine.
Flotiq wraps the ES API in order to provide better compatibility with the remaining parts of the API.
Search results are scored.
You can score each field individually, very convenient if you'd like to promote results where the match appears in a specific field, e.g. in the blog post title.
You can aggregate results by any of the fields, which makes it super easy you build faceted search results pages.

Disadvantages of Flotiq full-text search

Flotiq's documentation is still evolving.

Gentics Mesh & Cloud CMS

Gentics Mesh and Cloud CMS both provide direct access to ElasticSearch query API and so - offer a very powerful search mechanism.

Advantages of Gentics' and Cloud CMS' full-text search

Powerful search engine, based on ElasticSearch

Disadvantages of Gentics' and Cloud CMS' full-text search

You will need to educate yourself on ElasticSearch as Gentics seems to provide raw access to ES, instead of neatly wrapping its API into a set of methods that are familiar to their own users.

Contentstack

Contentstack provides a limited search API and recommends integrating with other services to provide full-text and ranked search results:

Advantages of Contentstack full-text search

They openly admit that you should use a dedicated search solution.

Disadvantages of Contentstack full-text search

Very limited.

Butter CMS

Butter CMS doesn't seem to care about search that much. They seem to only provide a search endpoint for their blog engine, and even that is very limited.

Advantages of Butter CMS full-text search

Can't think of anything, sorry.

Disadvantages of Butter CMS full-text search

Minimal support, only in the blog engine part.

Summary

Although most headless CMS solutions offer some kind of search - it's often constrained.

Having a powerful search engine, which is wrapped in a set of convenient APIs, seems a must in order to provide the end-users with search results that can be easily navigated, sorted and faceted. Yet, the most popular systems, like Contentful or ButterCMS, seem to ignore the problem and significantly limit the support for search.

The contending systems, like Cloud CMS, Flotiq or Gentics Mesh - offer better support for search by providing access to ElasticSearch, either directly (Gentics, Cloud) or by wrapping it into more straightforward and more familiar APIs (Flotiq).

Fun project - use voice to push content to Flotiq headless CMS

andrzejwp — Fri, 06 Mar 2020 16:39:53 +0000

This article was originally published on Flotiq blog

Teaser Video

Check video below that covers everything in this article:

Voice assistants

So far, there are two main voice assistants: Alexa and Google Assistant. They were invented to simplify our everyday tasks like answering simple questions, checking weather and so on. With technology progress the usage purpose of voice assistants is also expanding. With every day passing by, presence of voice assistants at work is more and more visible. You can use these to create meetings, to-do list, reminders, control smart home, take notes and so on.

At the beginning of 2020, Google Assistant appeared on the Zapier platform in Beta stage, so we decided to take this oportunity and create a flow that will allow our users to literally talk to Flotiq. That's what we call effortless content!

In this post we will cover only basis of this topic. At the end you can find a video where we show step-by-step how to make such integration to be able to insert data to Flotiq by talking to Google Assistant. Let's dive deep into it.

Prerequisites

For this integration to work you will have to meet following conditions:

Have a Google Account
Have a Zapier Account
Have a Flotiq Account
Created at least one own Content Type Definition in Flotiq
Have Google Assistant installed on your phone.

Enabling Zapier in Google Assistant

By default you can’t speak to Zapier in Google Assistant. You have to allow it by yourself. Go to Google Assistant Page, then hover over “What it can do” and click “Explore all actions”.

In the search box type "Zapier" and then click "Link" in the Zapier integration description page.

You can validate connection by going to "Authorized Apps" section in your Zapier account settings page.

For questions or doubts be sure to check Google Assistant FAQ in Zapier

Make a Zap / Use a Zap Template

To build the integration itself - follow these steps:

Click "Make a Zap" on your Zapier dashboard page,
For the triggering application select Google Assistant,
Enter a running phrase (word, sentence etc. - you will use it later in Google Assistant),
Enter prompt questions (recommended) that match your Content Type Definition fields (see video below for example),
Click Test&Review or Continue to let Zapier create sample object that will be used in Action step,
Select Flotiq as an application in Action step (it will select our only action, New Content Object, automatically),
Log in with your Flotiq API KEY (don't use the read only one!) ,
Select proper Content Type Definition from dropdown,
Match field values with response fields from trigger step,
You can avoid skip testing here, to prevent sending dummy data,
Click "Turn Zap On" and have fun!

Remember to check the video on the bottom of the page that provides a live example of everything mentioned here!

Conclusion

Voice assistans making a step into our worklife can be extremely helpful and can speed up solving various problems. Google Assistant presence in workflow automation systems is only the beginning and we can't wait to see what will grow of it.

Read more about our Zapier integration on Flotiq blog and in the Flotiq docs.

Headless CMS Contact forms with Serverless and Zapier

andrzejwp — Tue, 03 Mar 2020 15:11:17 +0000

This article was originally posted as a Flotiq Deep Dive, Contact form using Flotiq

Introduction

You can easily use headless CMS systems like Flotiq to store data from contact forms or other places where you collect information from your users. With Flotiq it's super easy to create Content Types, push new data to the system and integrate it with other systems through Zapier. Follow along for a complete, working example of how this can be done.

What you'll learn in this deep dive

Create a contact form with notifications, without backend code, in 10 minutes.

Steps:

Create a model in Flotiq
Create a simple form on your website
Zapier - sending notifications to email

Configuring Flotiq

Create a simple Content Type Definition "Contact Form".

We need a type with two attributes:

Field name	Field type	Additional attributes	Comments
email	email	Not required	Optional e-mail address of your guest
message	textarea	Required	The message

Here's how you would create that Content Type Definition using the Flotiq editor:

Once you save that Content Type - you can see the endpoints that were generated to support it in your API documentation (click "API doc" link in the menu):

Now you can manage contact form entries via Flotiq. Let's now create a contact form on your site to post data directly to the FLotiq API.

HTML Form implementation

We will use a simple HTML form. The code below code is a complete, working solution. You only need to replace the "FLOTIQ_TOKEN" variable. Here, we also use classes from the Bootstrap4 CSS framework, but it's optional.

<!-- form -->
<div class="container">
    <form id="contact_form">
        <div class="form-group">
            <label for="email">Email address</label>
            <input type="email" class="form-control" name="email" id="email">
        </div>
        <div class="form-group">
            <label for="message">Message</label>
            <textarea class="form-control" name="message" id="message"></textarea>
        </div>
        <button type="submit" class="btn btn-primary">Submit</button>
    </form>
</div>

We need also a few lines of javascript to pass data from our form to the Flotiq API:


<!-- we use jQuery to handle form data -->
<script src="https://code.jquery.com/jquery-3.4.1.min.js"
        integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo="
        crossorigin="anonymous"></script>

<script>

    // Handle form submit - push to Flotiq instead of default HTML Form action.
    $('#contact_form').on('submit', function (ev) {

        ev.preventDefault();

        // Prepare form data and generate id for Flotiq Content Object
        var formData = {
            id: Date.now() + '_' + Math.random().toString().substring(2),
            email: $(this).find('[name=email]').val(),
            message: $(this).find('[name=message]').val(),
        }

        // Caution! Other users can see your token, and can use it
        // not only for creating contact messages, but also for listing or
        // deleting. You can hide this token using Cloudflare
        // (see: https://flotiq.com/docs/Deep-Dives/securing-write-api-access/) or custom backend
        var FLOTIQ_TOKEN = '_YOUR_FLOTIQ_READ_WRITE_TOKEN_';

        $.ajax({
            method: 'POST',
            url: 'https://api.flotiq.com/api/v1/content/contact_form?auth_token=' + FLOTIQ_TOKEN,
            data: formData,
            dataType: 'json',
            success: function () {
                $("#contact_form").html("<h5 class='text-success'>Thank you for getting in touch!</h5>");
            },
            error: function (errorResponse, err) {
                if(errorResponse.status === 400) {
                    alert('Please fill all required fields');
                } else {
                    alert('Server error');
                }
            }
        });
    })

</script>

With the recent updates in Flotiq it's super simple to create a dedicated, scoped API key that will narrow down the access to a specific Content Type and a specific action.
For example - if you'd like to use the key for storing contact form entries, although the key is hidden in Cloudflare, we would recommend to set it up as follows:
Read more about How to secure a JAMstack app with Cloudflare workers

Now you can test if this form is sending data to your Contact Form type in Flotiq app.

Hooking-up Zapier e-mail notifications

If you want to receive emails when the form is submitted you can use Flotiq and Zapier integration. You can also adapt this step to push your contacts to other sources, e.g. CRM systems, Mailchimp, Google Sheets, whatever you like.

Log in or register in Zapier
Create a zap - select connection between Flotiq and Gmail (you can use other integrations if you want). It should look like:
Next you need to pass your Flotiq API Key in Choose Account section (it should be your global read-only API KEY),
In Customize content object section select "contact_form".

In the "Do this..." field you need to configure email address and content. See our example config:

That's all. You will now get an email notification about every message left through your Contact Form.

Read more about Flotiq & Zapier integration here

Set up your own integration with one of 1000+ systems here

Conclusion

It's super easy to create forms without any backend code.
Flotiq's Integration with Zapier allows you to use your data with many applications, check more ways to integrate with Flotiq
Contact form data will be available in your Flotiq account.