Pages

Introduction

In Fustak, each page is defined using two files: a .toml configuration file and a .js request handler file. The .toml file is responsible for configuring the page, while the .js file handles the requests for the page.

Default Page Configuration

To set default configurations for your pages, you can create a default page configuration file prefixed with _default`**, such as _default.page.toml. This default configuration can be overridden for individual pages.

Here is an example of the default page configuration:

[page.default]
file = "../_default.page.toml"

Page Builder Configuration

The page builder configuration specifies the path to the JavaScript file for the page and sets the URL path where the webpage will be accessible. This information is stored in the config database.

[page.builder]
page = "home.page.js"
path = "/"

Page Builder Headers Configuration

The page builder headers configuration allows you to configure the headers for the webpage's response.

[page.builder.headers]
Access-Control-Allow-Origin = "*"
Access-Control-Allow-Methods = "GET"
X-Frame-Options = "deny"

Page Template Configuration

The page template defines the HTML file used to render the page. The template can be defined in the page configuration file or in the default page configuration file.

[page.template]
path = "../_default.page.html"

Page Variables and Template Usage

The page definition is an essential component used by the template to dynamically substitute variables. Variables within the template are defined using the syntax {{ variable }}. System variables start with the prefix "fustak_", which is exclusive to the template and should be omitted when defining variables in the configuration.

The following default variables are available:

− fustak_metas: Represents the metadata associated with the page.
− fustak_links: Contains the links relevant to the page.
− fustak_head_scripts: Consists of scripts intended for the head section of the page. To include this variable, set "head = true" in the configuration.
− fustak_stylesheets: Refers to the stylesheets applied to the page.
− fustak_styles: Specifies the styles specific to the page.
− fustak_content: Represents the content to be displayed on the page.
− fustak_body_scripts: Contains scripts that should be placed at the end of the body section of the page.

Two mandatory variables are required for proper page rendering:

− fustak_styles: Used to define the styles for the page.
− fustak_content: Sets the content that will appear on the page.

Ensure that these two variables, fustak_styles and fustak_content, are included in your configuration.

Here is an example of the page definition configuration:

[page.definition]
title = "Home | Fustak"
canonical = "https://fustak.dev"
styles = ["../../../public/css/normalize.css", "../../../public/css/reset.css"]

[[page.definition.scripts]]
src = "dist/pages/counter.island.js)"
async = true

[page.definition.metas]
description = "Page Description"
keywords = "keyword1, keyword2"
"og:title" = "Page Title"
"og:type" = ""
"og:url" = ""
"og:image" = ""
"og:description" = "Page Description"
"og:site_name" = ""
"twitter:card" = ""
"twitter:site" = ""
"twitter:title" = "Page Title"
"twitter:description" = "Page Description"
"twitter:image" = ""
"twitter:image:alt" = ""

SSR framework

Our SSR (Server Side Rendering) framework is a solution that leverages JSX and MDX. It provides a straightforward approach for creating primitive UI components and applying styles to them using the component. The component is globally available and eliminates the need for additional dependencies.

The component allows you to utilize HTML attributes as CSS declarations, automatically generating utility classes based on these attributes. This seamless integration of CSS styles with your UI components simplifies the styling process.

To use the SSR framework and component, follow these steps:

1 . Create your UI components using JSX syntax.
2 . Apply styles to your components using the component.

3 . Use HTML attributes as CSS declarations within the component.

4 . The framework will generate corresponding utility classes based on the attributes.

By adopting this approach, you can efficiently create and style your UI components without managing additional dependencies.

Here's an example of creating a Box component using the component:

// Box.jsx
export function Box(props) {
    return <U tag="div" {...props} />;
}

And an example of creating a Button component with the component and importing HTML element attributes from the @fustak/s/attrs module:

// Button.jsx
import { button } from '@fustak/s/attrs';

export function Button({ children, ...props }) {
    return <U
        tag='button'
        type='button'
        attributes={button}
        background='#000'
        borderRadius='4px'
        color='#fff'
        padding='8px'
        style={{
            ':hover': {
                background: '#fff',
                color: '#000',
            },
        }}
        {...props}
    />;
}

Importing MDX or MD files and using them as components is allowed. The framework will automatically convert them to JSX for rendering.

By importing MDX or MD files as components, you can leverage the SSR framework's capabilities to render them on the server side and ensure they are converted to HTML. This allows you to include Markdown content seamlessly alongside your other UI components.

Here's an example of importing an MDX file and using it as a component:

// HomePage.jsx
import HomePageContent from "./mdx/home.page.content.mdx";

export function HomePage(props) {
  return (
    <main>
      <h1>Welcome home!</h1>
      <HomePageContent />
    </main>
  );
}

In this example, HomePageContent is imported from the MDX file home.page.content.mdx. You can then use HomePageContent as a regular JSX component within your page.

Page Deployment

To deploy a page, you can use the following command:

fustak pages [PATH]

The fustak pages command deploys all the pages. If a page has an island, it will deploy the island and create an asset in the dist folder. To deploy the asset to the server, use the following command:

fustak assets [PATH]

The fustak assets command deploys all the assets.

Islands should be placed in the islands folder inside the current page's folder. For example:

...
└── pages
    ...
    └── index
        ├── index-content.jsx
        ├── index.page.js
        ├── index.page.toml
        └── islands
            └── counter.island.jsx
            ...

Islands are responsible for managing the interactive parts of the page and are only used in the browser.

Currently, Fustak officially supports Preact. However, support for other frameworks is planned for the future.

To use Preact, import the preact-shim in the island component:

import "../../preact-shim";

For a complete example, you can refer to the tutorial-template repository.