Skip to content

Getting Started.md

Latest commit

 

History

History
80 lines (53 loc) · 3.8 KB

Getting Started.md

File metadata and controls

80 lines (53 loc) · 3.8 KB

Getting Started

This quick start guide will walk you through creating your first NextPage-enabled webpage and understanding the overview of all the components and how they work together.

🧠 Understanding Components And Workflow

The NextPage ecosystem is built around four core components: nodes, views, fields, and fallbacks.

  • Nodes are containers (like objects) that group related fields together to form a meaningful unit of content.

  • Views determine how a node is presented to the user. They define the visual layout and behavior of a node. Whether it’s a simple text block, a document with images, or an interactive component with input fields.

  • Fields define individual pieces of data. These represent the content within a node, such as titles, descriptions, images, or inputs.

  • Fallbacks are default fields defined in the <head> of the page. They act as a way to "patch" nodes when a specific field is missing from a node, or allows you to create a global node ensuring consistent rendering.

📥 Workflow

Once a node is defined on a page, it can be queried from another page using the NextPage query scheme.

<a href="https://example.com/webpage:node"> View Summary</a>

This triggers a process where:

  • The target page is loaded,
  • The specified node is located,
  • and its fields are parsed.

If any required fields based on the defined view are missing, the system will attempt to retrieve fallbacks from the <head> of the document.

If no suitable fallbacks are found, the query will return null, indicating the node couldn’t be rendered.

🗜️ Failover

If the queried node returns null, the system can optionally trigger a failover strategy, which involves sequentially searching through a predefined list of alternative nodes until a valid response is found.

For more details, refer to the Node Failover Strategy section.

🟢 Defining A Standard Node

Nodes represents the object that is returned from a query. To create a node you must define the "np-node" attribute inside an element in the body of the html.

<article np-node="primary">
    <h1>...</h1>
    <p> ... </p>
</article>

🤏 Minimum Requirements

Regardless of how a node is defined, whether standard or as a fallback, it must include at least a title and description field to be considered valid.

To ensure nodes never fail, we recommend defining fallback title and description fields. Then, define more specific fields within each individual node as needed.

This guarantees that even if a node is missing critical fields, it can still render using the fallbacks.

🫆 Reserved Names

When naming nodes, be aware that certain reserved names are used by the system to support the failover mechanism and ensure standardized querying.

It’s recommended to always use these reserved names where applicable and using custom names only for more specific or specialized use cases.

A full list of reserved names and details on the failover mechanism can be found in the Node section.

⛑️ Defining A Fallback Node

Fallbacks allow you to define global nodes or fields that act as patches for any specific node on the page.

These fallbacks are defined in the <head> and can use standard field names appended with np: in a meta tag.

<meta name="np:node" content="primary">
<meta name="np:title" content="...">
<meta name="np:description" content="...">

🧐 Querying The Node

To query a specific node from another page, simply append a colon (:) followed by the node’s name to the end of the target page’s URL.

<a href="https://example.com/webpage:primary"> View Summary</a>

Note: The node query string should always appear at the very end of the URL, even after any standard HTTP GET parameters.

⏮️ Back To Index