gatsby-source-flamelink
v3.0.4
Published
Gatsby source plugin for building websites using the Flamelink CMS as a data source
Downloads
16
Readme
Gatsby Source Plugin for Flamelink
Source plugin for pulling data into Gatsby v2 from Flamelink.
Install
npm install --save gatsby-source-flamelink
or
yarn add gatsby-source-flamelink
How to use
In order to use the plugin you need to configure it to point to the Firebase instance that is using Flamelink. To do this you will need to create a service account (if you haven't already) and download the JSON file for the service account. You will also need your Firebase configuration details. Once you have these details add the following to your config file:
// In your gatsby-config.js
plugins: [
{
resolve: 'gatsby-source-flamelink',
options: {
firebaseConfig: {
pathToServiceAccount: 'path/to/serviceAccountKey.json',
databaseURL: 'https://<DATABASE_NAME>.firebaseio.com',
storageBucket: '<PROJECT_ID>.appspot.com',
},
dbType: 'cf',
environment: 'production',
content: true,
populate: true,
navigation: true,
globals: true,
},
},
]
Debug
To see debug information in your terminal, you can optionally opt into these messages by setting the DEBUG
environment variable when starting Gatsby.
Log all error messages:
DEBUG=flamelink:error gatsby develop
Log all warning messages:
DEBUG=flamelink:warning gatsby develop
Log all info messages:
DEBUG=flamelink:info gatsby develop
Log all Flamelink messages:
DEBUG=flamelink:* gatsby develop
Options
firebaseConfig
Type: {Object}
The only mandatory config is the Firebase Config object which allows Flamelink to connect to your Firebase project. You must always specify the databaseURL
and storageBucket
, and then you have 2 options to specify the necessary credentials for the connection to take place:
- Specify the absolute path to your Firebase Service Account file as
pathToServiceAccount
- If you cannot reference your service account file, you can specify the individual fields instead:
{
projectId: '<PROJECT_ID>',
clientEmail: 'foo@<PROJECT_ID>.iam.gserviceaccount.com',
privateKey: '-----BEGIN PRIVATE KEY-----\n<KEY>\n-----END PRIVATE KEY-----\n',
}
Whichever is easiest to you, we're easy.
If you want to read up more about how to setup the Firebase admin SDK, go here. You don't need this, it is for more info if you are not familiar with the service account required.
dbType
Type: {String}
The type of Firebase database your are using. Can be one of cf
or rtdb
, for Cloud Firestore or Real-time Database respectively. Defaults to rtdb
.
{
dbType: 'rtdb'
}
environment
Type: {String}
The Flamelink environment. Defaults to production
.
{
environment: 'staging'
}
locales
Type: {Array}
The Flamelink locales. Defaults to whichever locales are available in your project.
{
locales: ['en-US']
}
globals
Type: {Boolean}
Whether your Flamelink project's globals should be included in the GraphQL server as allFlamelinkGlobals
. Defaults to true
.
{
globals: false
}
content
Type: {Boolean|Array}
Whether your Flamelink project's content should be included in the GraphQL server as allFlamelink{ContentType}Content
. Defaults to true
.
If value is set to true
, all available content types will be included.
For fine-grained control, you can specify an array of arrays for the specific content types you want, including any options, like: ['<contentType>', '<options>']
{
content: [
{ schemaKey: 'blog-posts', populate: true },
{ schemaKey: 'products', populate: ['image'] },
{ schemaKey: 'homepage', populate: false, fields: ['title', 'description'] },
]
}
Any options available for the SDK are also available here.
This example will be available in the Gatsby GraphQL server as
allFlamelinkBlogPostsContent
,allFlamelinkProductsContent
andallFlamelinkHomepageContent
respectively.
populate
Type: {Boolean|Array}
Whether your Flamelink project's relational and media content should be automatically populated or not. Defaults to true
.
IMPORTANT! If the
content
option is an array, this globalpopulate
option is ignored.
If value is set to true
, all available content will be populated to the deepest level possible, ie. get all the things!! This is by far the easiest option, just keep an eye on it if you find that the build gets too slow.
Alternatively, specify an array with specific fields to populate. This option is global for all content, so it might not be relevant for all content. You can also use the array-of-arrays option for content
if you need to specify different populate
options per content type. Take a look at the Flamelink SDK docs for more info on how the populate
option works.
{
populate: true
}
navigation
Type: {Boolean|Array}
Whether your Flamelink project's navigation menus should be included in the GraphQL server as allFlamelink{NavigationName}Navigation
. Defaults to true
.
If value is set to true
, all available content types will be included.
For fine-grained control, you can specify an array of arrays for the specific navigation menus you want, like: ['<key>', '<options>']
{
navigation: [
{ navigationKey: 'main', structure: 'nested' },
{ navigationKey: 'secondary', structure: 'list' },
]
}
This example will be available in the Gatsby GraphQL server as
allFlamelinkMainNavigation
andallFlamelinkSecondaryNavigation
respectively.
How to query your data
IMPORTANT! Since certain fields are reserved for internal use by Gatsby, the following fields are renamed in your data:
id => flamelink_id
children => flamelink_children
parent => flamelink_parent
fields => flamelink_fields
internal => flamelink_internal
__meta__ => flamelink___meta__
There is also an additional property, flamelink_locale
available on all content and navigation nodes which will be set to the particular locale you have specified for the entry.
Further, all flamelink_id
s are always strings.
For Cloud Firestore the "meta" field is _fl_meta_
.
For Realtime Database the "meta" field is flamelink__meta_
.
All queries below use flamelink__meta_
- replace this with _fl_meta_
when using Cloud Firestore.
Get Global data
query {
allFlamelinkGlobals {
edges {
node {
id
flamelink_id
adminEmail
dateFormat
siteTitle
tagline
timeFormat
timezone
flamelink__meta_ {
createdBy
createdDate
lastModifiedBy
lastModifiedDate
}
}
}
}
}
Get specific content type for a locale (Products for instance)
query {
allFlamelinkProductsContent(filter: { flamelink_locale: { eq: "en-US" } }) {
edges {
node {
flamelink_id
name
description
price
image {
flamelink_id
file
folderId
type
contentType
url
sizes {
height
quality
width
}
flamelink__meta_ {
createdBy
createdDate
lastModifiedBy
lastModifiedDate
}
}
}
}
}
}
Get navigation type for a specific locale (Main for instance)
query {
allFlamelinkMainNavigation(filter: { flamelink_locale: { eq: "en-US" } }) {
edges {
node {
id
flamelink_id
title
items {
attachment
component
cssClass
order
parentIndex
title
url
uuid
flamelink_id
flamelink_children {
attachment
component
cssClass
order
parentIndex
title
url
uuid
flamelink_id
}
}
}
}
}
}