Flamelink Extensions allow you to seamlessly integrate custom-built apps that require authentication to enhance your customers experience with Flamelink. Extensions can be built in the programming language of your choice, by you, your team or our specialist services team.
Sometimes a CMS with all of its bells and whistles is just not enough, and you require some custom features. Traditionally this problem would be solved in one of the following ways:
Search and install a plugin that almost does the trick (potentially introducing security risks) and does not allow you to tailor it to your specific needs.
Host an entire CMS solution on your own infrastructure in order to extend the source code. This requires that you conform to already established patterns and a pre-defined programming language (incurring infrastructure and resource costs).
Thankfully there is a better way... Flamelink Extensions
The possibilities are endless, you could build reporting tools for your e-commerce store, analytics dashboards, management tools, moderation tools, customer engagement tools, the list goes on and on.
In this article, we will be looking at building and hosting our own custom Sales Report. You can build your extension in the programming language or framework of your choice, but for this example, we will be using CSS, HTML and Javascript.
We can achieve this by completing the following:
Building our own custom extension and publishing it to the web
Set up an Extension type Custom Link in Flamelink
Note: In order to generate a Custom Authentication Token for your extension, you will need to ensure you have added a service account for your project.
Building our Sales Report app
Our app will query some sales-related data that resides outside of the Flamelink collections in our Cloud Firestore database (you can use either Cloud Firestore or Realtime Database, even connect to alternative databases if that is what you require) and generate a report based on the values we receive.
Note: NodeJS is required in order to complete the code setup.
The "$" in the section below indicate that the following text should be entered in your terminal excluding the "$".
1. Data Setup
We will need to create some sales data for our app to work. Below is a guide to add some entries to our Firestore database.
Create a new "sales" Collection
From your Firebase console, navigate to "Firestore" and add a new "sales" collection.
Each entry in the new "sales" collection should have the following properties
date: timestamp
lineItems: number
orderNumber: number
orderTotal: number
2. Code Setup
Now that we have added some sales data we can go ahead and focus on building and deploying our app.
Install the required Firebase tools from your terminal
$ npm install -g firebase-tools
Log in for the purposes of the Firebase CLI
Follow the prompts and select the Google account that has access to your Firebase project.
$ firebase login
Download the sample extension code
Create a new folder that will house the example code for our Sales Report app, and navigate to your new folder from your terminal
$ cd your-folder/sales-report
Clone the example code
$ git clone https://github.com/flamelink/extension-example.git .
Initialise Firebase
Follow the prompts in order to complete the setup. This example will only require Firebase hosting. Be sure to select the relevant project when prompted.
$ firebase init hosting
Select your project
Set the following options
Set up a sub-domain to host your Sales Report app
In the code snippet below replace {your-project-id} with your Firebase Project ID
Example firebase hosting:sites:create sales-report-cms-playground
$ firebase hosting:sites:create sales-report-{your-project-id}
Your new sub-domain can then be accessed on
sales-report-{your-project-id}.web.app
sales-report-{your-project-id}.firebaseapp.com
Create a target to use for deployments
In the code snippet below replace {your-project-id} with your Firebase Project ID
This will allow us to easily deploy our new app to our newly created sub-domain
$ firebase target:apply hosting sales-report sales-report-{your-project-id}
Lastly, we need to update our firebase.json file to add the target we created. The file is located in our sales report folder (your-folder/sales-report/firebase.json)
Simply replace the file contents of the firebase.json file with the code below:
{
"hosting": {
"ignore": [
"firebase.json",
"**/.*",
"**/node_modules/**"
],
"public": "public",
"rewrites": [
{
"destination": "/index.html",
"source": "**"
}
],
"target": "sales-report"
}
}
Read more about Firebase multi-sites
3. Deploy our new Sales Report app
Now that we have created some data, we can go ahead and deploy our app to our new custom domain.
$ firebase deploy --only hosting:sales-report
Once your deployment is complete, you can navigate to
https://sales-report-{your-project-id}.web.app and you should see the following message.
Note: in the event that you are faced with the default Firebase hosting page, try to add index.html to the end of your URL.
e.g. https://sales-report-{your-project-id}.web.app/index.html
Perfect, now all that is left to do is to set up our Custom link in Flamelink for our extension
Setting up a Custom Link for your extension
1. Navigate to "Settings" and select "Custom Links"
2. Click on the "Add Section" button and complete the details
Section: Name of the section in your main Flamelink navigation
Link Title: Name of the link that will be added to your new section
URI: The fully qualified URL of where your app will reside (you can use localhost URLs while developing your extension)
Type: Extension
Auth Token: Enabled (requires a service account)
Width: Percentage of the entire screen width that the container for your custom app should take up.
3. "Save" your new Custom link
You will notice a new section with your Custom links in your main Flamelink menu.
4. View your new extension within Flamelink
Simply click on the new "Sales Report" link to view your extension.
Congratulations! You have successfully created a Flamelink extension.
Bonus Section - Technical Details
Flamelink extensions allow you to authenticate users easily using Custom Auth Tokens. As mentioned, for extensions that require authentication, Flamelink requires you to provide a service account. This is used in order to generate a custom token that can be used to authenticate a user without the need for them to log in.
When you select to enable the "Auth Token" within your Custom link, Flamelink generates and passes this token in the URI provided for your custom app.
Example https://sales-report-cms-playground.web.app?fbAuthToken=xxx
Our example Sales Report app invokes a function in order to retrieve the value of the URL parameter.
This is then used to authenticate our user if they are not yet authenticated
Putting it all together
Utilising the "onAuthStateChanged" method provided by the Firebase SDK, we check to see if there is a current user and then generate our report. If no user is found, we attempt to sign the user in with the custom token.
If the user is successfully authenticated, our "onAuthStateChanged" function will run again and the report will be generated.
