Open Sitez Documentation

Documentation main page

 

Open Sitez definition.osz

Routes Configuration

The definition.osz file in Open Sitez contains various sections to configure your website, including the "Routes" section. This section defines how URLs are mapped to specific content or functionality within your site. In this documentation, we'll provide a comprehensive overview of route configurations.

Introduction to Routes

Routes play a critical role in Open Sitez, allowing you to define how your website responds to different URLs. Each route is specified in the configuration with a unique name and a set of attributes that determine its behavior.

Route Types

Open Sitez supports several route types, each serving a specific purpose. With most plugins providing a type of route, I would recommend to checkout the plugins section for individual route types

Here are some common route types and their descriptions:

Page Route

• Type: page
• Description: Represents a static page route, typically used for displaying fixed content.

Blog Route

• Type: blog
• Description: Configures a dynamic blog route, which can display a collection of posts or articles. Blog routes often have attributes like "limit" and "feature" to control the number of posts displayed and specify the ID of the blog.

Redirect Route

• Type: redirect
• Description: Sets up redirection from one URL to another. Useful for forwarding visitors from old URLs to new ones.

Feed Route

• Type: feed
• Description: displays an rss or atom feed

Form Route (Work in Progress)

• Type: form
• Description: Defines a route for forms and user submissions. While still a work in progress, it allows you to handle user interactions and data submissions.

Route Configuration Examples

Let's explore various examples of route configurations, including examples for a few route type:

Static Page Route

This example defines a static page route named "default" that displays an HTML file named "index.html."

default:
  type: page
  content:
    type: include
    file: index.html

Dynamic Blog Route

This configuration sets up a dynamic blog route named "thoughts" with a limit of 20 posts and specifies the ID of the blog.

thoughts:
  type: blog
  limit: 20
  feature: 10

Redirect Route

This example creates a route named "old-page" that redirects visitors from "/old-page" to "/new-page/."

old-page:
  type: redirect
  redirect: /new-page/

Form Route (Work in Progress)

This section is under development and will be expanded upon in future releases.

Page Route Layouts

Page routes of the "page" type can specify layouts that define the structure of the page. Layouts can be shared among multiple pages. If a layout is not explicitly specified, Open Sitez will look for the default layout. Below is an example of how to specify a layout for a page route:

my-page:
  type: page
  layout: custom-layout
  content:
    type: include
    file: my-page-content.html

In this example, the "my-page" route specifies a custom layout named "custom-layout" for its page content. If "layout" is not provided, Open Sitez will use the default layout.

Additional Route Attributes

In addition to route type-specific attributes, you can use various attributes to customize the behavior of your routes. These attributes include:

• url: Defines the URL path to which the route responds.
• auth: Configures authentication settings for protected routes.
• content: Specifies the content to be displayed for the route.
• redirect: Defines the target URL for redirection.

These attributes allow you to create a wide range of customized routes tailored to your website's needs.

Authentication Options

Open Sitez provides flexible authentication options for protected routes. You can use either simple authentication or database-driven authentication, depending on your requirements.

Simple Authentication

This configuration defines a password-protected page route named "admin" using simple authentication. It includes two users, "aladdin" and "admin," with specific passwords and group assignments.

admin:
  type: page
  auth:
    type: simple
    users:
      aladdin:
        password: opensesame
      admin:
        password: badpassword
        group: admin

Database-Driven Authentication

You can extend authentication to use a database as the source for user information. This example demonstrates database-driven authentication with the "query" type, allowing you to customize options such as the database table and fields.

route:
   protected-route:
       auth:
            type: query
            table: users

Conclusion

The "Routes" section in the Open Sitez definition.osz configuration file is a powerful tool for defining how URLs are handled on your website. By understanding route types, attributes, and authentication options, you can create dynamic, secure, and user-friendly web experiences for your visitors.