frint-preact
Preact package for FrintJS
Guide
Installation
With npm:
$ npm install --save preact frint-preact
Via unpkg CDN:
Usage
We start by importing the necessary functions from the library:
;;;
Now let's create our first Component:
{ return <div> <p>Hello World</p> </div> ;}
Now we need to create our Root App, and assign the previously defined Component as our root component for the App:
const RootApp = ;
Now that we have everything ready, we can instantiate our app, and render it:
windowapp = ;;
The code above asumes your page has an element with an id root
:
Regions
The library already ships with a Region
component, and a RegionService
.
We use the concept of regions for defining areas in our Components, where other Apps can load themselves in.
For example, imagine the Root component of our Root App above, we can define a Region named sidebar
as follows:
;; { return <div> <p>Hello World from Root App!</p> <Region name="sidebar" /> </div> ;}
That's just defining the Region only. Let's now create an App, and assign it to the sidebar
region:
; { return <p>I am App</p> ;} const App = ;
Now that we have our App defined, we can register it to our Root App:
windowapp;
Now when you refresh your browser, you would notice your App being rendered inside the Region sidebar
.
Region and data
It is possible that when defining the Region with a name, you would also want to pass some data to it, so that whenever an App gets rendered inside it, the App would be able to access that data.
From the above example of sidebar
Region, imagine us passing some data too via props:
{ const data = foo: 'bar' ; return <div> <p>Hello World from Root App!</p> <Region name="sidebar" data=data /> </div> ;}
That's only the Region
component's implementation part. How do we access it from our App now?
Enter RegionService
. This is a Service that we can pass in our App's providers list, allowing us to later have access to Region's props.
; const App = ;
Once your App is registered and rendered, you can get access to your App instance, which can then allow you to deal with Region's props:
const myApp = windowapp;const region = myApp; // Region's data as an Observableconst regionData$ = region; regionData$;
We will discuss more in details how to get Region's props in your App's components via observe
in the next section.
Observing components
We encourage everyone to write their components in as dumb way as possible. Meaning, we just pass the props, and Components just render them. Nothing more.
But real-world applications are complex, and data can come from anywhere, at any time, asynchronously.
Enter observe
. This is a function that we ship with the library for making your Components reactive.
A very simple example would be:
{ return <p>Interval: propsinterval</p> ;}
We just created a component, that prints out a prop called interval
. Nothing fancy there. But we wish the interval to update itself every second. Instead of handling it from within the Component, we can do it with observe
as follows:
;;; const MyObservedComponent = MyComponent;
We have just made our simple Component reactive, by wrapping it with observe
. Now it will continue to update the interval
prop every second until the Component has unmounted itself.
Observing Region's data
In previous example, we showed you how to access Region's data via RegionService
. Now let's see how we can pass it to your App's component too:
;;; const ObservedAppComponent = AppComponent;
When your App's component renders, latest props will be passed to it in this structure:
// will keep updating every second, interval: 1 // will update whenever sidebar Region's props change regionData: foo: 'bar'
Helper function for streaming props
As the number of observables grow, it might be difficult to maintain your observe
implementation. That's why we are also shipping a streamProps
function in the library to make it easier for you:
;; const MyObservedComponent = AppComponent;
The props available inside your Component would then be in this format:
interval: 1 regionData: foo: 'bar' key: 'value' myKey: 'myValue'
Multi-instance Apps
This is a use case where you have multiple instances of Region with the same name mounted in the DOM. And the apps rendered in them should have their own independent scoped instances too.
Think of a scenario where you have a TodoList, and you want a Region defined for each Todo item:
{ const todos = id: '1' title: 'First todo' id: '2' title: 'Second todo' id: '3' title: 'Third todo' ; return <ul> todos </ul> ;}
Now we may have an App that we want to be rendered in todo-item
Regions.
Let's create an App, that will receive the todo
object, and render the title in UPPERCASE format.
;;; { const todo = props; return <p>Todo in upper case: todotitle</p> ;} const ObservedAppComponent = AppComponent; const App = ;
Now comes the part of registering our App as a multi-instance app:
windowapp;
API
render
render(app, node)
Renders a Root App in target DOM node.
Arguments
app
(App
): The Root App instance.node
(Element
): The DOM Element where you want your App to render.
observe
observe(fn)(MyComponent)
Arguments
fn
(Function
): The function returning an Observable.- The
fn
accepts two arguments:app
: the instance of your Root App or the App in scopeprops$
: an Observable of props being passed by parent component (if any)
- It should return an
Observable
orObject
- The
Returns
Function
: that can be called with a Component to return an observed Component ready for embedding and rendering anywhere.
Region
Region
The Region component.
Props
name
(String
): The name of the Regiondata
(Object
): Data to be made available to rendered AppuniqueKey
(String
[optional]): Used when there are multiple Regions of the samename
. It prop must be unique and fixed throughout the whole app.className
(String
[optional]): The className used by Region wrapper element
RegionService
Exported from frint-component-handlers
.
streamProps
Exported from frint-component-utils
.
PreactHandler
PreactHandler
Handler for Preact, according to the spec defined in frint-component-utils
.