Developers - Helpers
Helpers
Installation
To install the Perfection Helpers in your application, you can use the Helpers NPM package.
Install the NPM package as follows
- Npm
- Yarn
- Pnpm
- Bun
npm install @perfectiondev/oversite-helpers
yarn add @perfectiondev/oversite-helpers
pnpm i @perfectiondev/oversite-helpers
bun add -g @perfectiondev/oversite-helpers
Create a client
Before continuing, make sure you already have an .env
file wwhere you store your Perfection Site Name
, API Key
and Subscription ID
. This file should be localted at the root folder of your project.
Secondly, import @perfection/oversite-helpers
module and create a reusable oversiteHelpers
client as follow:
- Next.js
- Nuxt.js
import OH from "@perfectiondev/oversite-helpers";
export class oversiteHelpers {
static instances = new Map();
static init = async (pageId) => {
const helpers = oversiteHelpers.instances.get(pageId);
const isPreview = process.env.NEXT_PUBLIC_PERFECTION_PREVIEW == "true" ? true : false;
if (helpers) await helpers.usePage(pageId);
else {
const result = await OH.init({
apiKey: process.env.NEXT_PUBLIC_PERFECTION_API_KEY,
subscriptionId: process.env.NEXT_PUBLIC_PERFECTION_SUBSCRIPTION_ID,
siteName: process.env.NEXT_PUBLIC_PERFECTION_SITE_NAME,
pageId,
preview: isPreview,
});
await result.usePage(pageId);
oversiteHelpers.instances.set(pageId, result);
}
};
static section = { parts: (partsFn, sectionId) => (typeof partsFn === "function" ? partsFn(sectionId) : (selector, defaultClasses) => defaultClasses) };
}
export default defineNuxtRouteMiddleware(async (to) => {
const { $helpers } = useNuxtApp()
await $helpers.usePage(
typeof to.meta.pageId === 'string' ? to.meta.pageId : ''
)
})
import oversiteHelpers from '@perfectiondev/oversite-helpers'
export default defineNuxtPlugin(async () => {
const helpers = await oversiteHelpers.init({
apiKey: import.meta.env.VITE_PUBLIC_PERFECTION_API_KEY,
siteName: import.meta.env.VITE_PUBLIC_PERFECTION_SITE_NAME,
subscriptionId: import.meta.env.VITE_PUBLIC_PERFECTION_SUBSCRIPTION_ID,
preview: import.meta.env.VITE_PUBLIC_PERFECTION_PREVIEW === 'true',
})
return {
provide: { helpers },
}
})
Initialize the client
Lastly, load this file into your pages/routes, initiate it by passing the same unique pageId
set in your Page data-pf
attribute.
- Next.js (App Router)
- Next.js (Pages Router)
import { oversiteHelpers } from "./clients/oversiteHelpers";
export default async function Page() {
await oversiteHelpers.init("YOUR_PAGE_ID");
return; // Your code
}
import { oversiteHelpers } from "./clients/oversiteHelpers";
//On production, consider using getStaticProps + revalidate or caching https://nextjs.org/docs/pages/building-your-application/data-fetching/get-server-side-props#caching-with-server-side-rendering-ssr
export async function getServerSideProps() {
await oversiteHelpers.init("YOUR_PAGE_ID");
return; //Your code
}
export default function Home() {
return; //Your code
}
How to use
Get All Instances
Next, you need to get all the instances from your current page (with the same pageId
set in your Page data-pf
attribute)
const helpers = oversiteHelpers.instances.get("homepage");
Retrieve Section Styles
Now , it is time to retrieve styles for a given section with its sectionId
, you can do this by doing so:
const section = oversiteHelpers.section.parts(helpers.section.parts, "sectionId");
const section_outer = section("outer", "default_classes");
const section_inner = section("inner", "default_classes");
Retrieve Components Styles
For a component, get its styles by passing its groupId
and instanceId
, just do the following:
const component = helpers.component.parts("groupId", "instanceId");
const component_h2 = component("h2", "default_classes");
About Performances
For getting style changes, we recommended that your pages retrieve styles server-side
so that there is no impact on your live website otherwise this will be a bad user-experience with layout shifts.
If you're using a vanilla-renderer, we recommend using a template
. For other frameworks, you can check the integration examples above to see how it should be implemented.