LONGPAGE and SWIPERPAGE Modes in Luban H5: A Complete Technical Guide

LONGPAGE renders all content as a single continuous vertical scroll, while SWIPERPAGE renders each page as a discrete horizontal slide using the Swiper library.

In the ly525/luban-h5 open-source H5 page builder, the rendering engine supports two distinct page modes that determine how end-users navigate through your design. Understanding the architectural differences between LONGPAGE and SWIPERPAGE is essential for optimizing user experience and performance in mobile-first H5 applications.

What Are LONGPAGE and SWIPERPAGE Modes in Luban H5?

Luban H5 abstracts page rendering through a mode flag stored in each page’s JSON configuration. The engine uses this flag to branch between two rendering strategies:

• LONGPAGE – Concatenates all layers and sections into a single DOM tree with standard document flow. The browser handles scrolling natively.
• SWIPERPAGE – Wraps each page in a Swiper slide container (swiper-container > swiper-slide), enabling touch-based horizontal navigation, pagination bullets, and programmatic slide control.

These modes are defined as constants in src/constants/script.js and consumed by the central renderer in src/engine/renderer.js.

Key Differences Between LONGPAGE and SWIPERPAGE

Feature	LONGPAGE	SWIPERPAGE
Navigation	Native vertical scroll	Horizontal swipe or button navigation
DOM Structure	Single continuous container	Multiple swiper-slide elements inside swiper-container
Transitions	None (instant scroll)	Configurable Swiper effects (fade, slide, cube, etc.)
Pagination	Browser scroll bar	Swiper pagination bullets or progress bar
Performance	Lighter DOM, ideal for content-heavy pages	Slightly heavier due to Swiper initialization, better for storytelling decks
Mobile UX	Standard scroll behaviour	Touch-optimized swipe gestures

How to Configure Page Modes in Luban H5

Page mode is declared in the page object within your project’s JSON schema. The editor persists this value under the mode key.

Defining LONGPAGE Mode

Set the mode property to "LONGPAGE" for continuous scroll layouts:

{
  "id": "page_001",
  "name": "Product Details",
  "mode": "LONGPAGE",
  "layers": [
    { "type": "image", "src": "hero.jpg", "y": 0 },
    { "type": "text", "content": "Features", "y": 800 }
  ]
}

Defining SWIPERPAGE Mode

Set the mode property to "SWIPERPAGE" for slide-based navigation:

{
  "id": "page_002",
  "name": "Onboarding Deck",
  "mode": "SWIPERPAGE",
  "swiperConfig": {
    "effect": "slide",
    "loop": false,
    "pagination": true
  },
  "layers": [ … ]
}

When the engine encounters SWIPERPAGE, it injects the Swiper initialization code into the generated HTML.

Rendering Implementation Details

The PAGE_MODE Enum

The canonical definitions reside in src/constants/script.js. This enum ensures type safety across the codebase:

// src/constants/script.js
export const PAGE_MODE = {
  LONGPAGE: 'LONGPAGE',
  SWIPERPAGE: 'SWIPERPAGE'
}

Renderer Logic

The central dispatcher in src/engine/renderer.js branches based on the mode property:

// src/engine/renderer.js
import { PAGE_MODE } from '@/constants/script'

function renderPage(page) {
  if (page.mode === PAGE_MODE.LONGPAGE) {
    return renderLongPage(page)
  }
  if (page.mode === PAGE_MODE.SWIPERPAGE) {
    return renderSwiperPage(page)
  }
  throw new Error(`Unknown page mode: ${page.mode}`)
}

function renderLongPage(page) {
  // Generates a single container with standard document flow
  const container = document.createElement('div')
  container.className = 'long-page-container'
  page.layers.forEach(layer => container.appendChild(renderLayer(layer)))
  return container
}

function renderSwiperPage(page) {
  // Generates swiper-container > swiper-slide structure
  const swiperContainer = document.createElement('div')
  swiperContainer.className = 'swiper-container'
  const wrapper = document.createElement('div')
  wrapper.className = 'swiper-wrapper'
  
  page.layers.forEach(layer => {
    const slide = document.createElement('div')
    slide.className = 'swiper-slide'
    slide.appendChild(renderLayer(layer))
    wrapper.appendChild(slide)
  })
  
  swiperContainer.appendChild(wrapper)
  // Swiper initialization script injected here
  return swiperContainer
}

When SWIPERPAGE is selected, the engine also injects the Swiper initialization script into the HTML <head>:

// Injected into generated HTML for SWIPERPAGE
new Swiper('.swiper-container', {
  direction: 'horizontal',
  loop: false,
  pagination: { el: '.swiper-pagination', clickable: true },
  navigation: { nextEl: '.swiper-button-next', prevEl: '.swiper-button-prev' }
})

Summary

• LONGPAGE produces a single, vertically scrolling document ideal for long‑form content and articles.
• SWIPERPAGE generates a Swiper‑based slide deck with horizontal navigation, perfect for presentations and onboarding flows.
• The mode is declared in the page JSON ("mode": "LONGPAGE" or "mode": "SWIPERPAGE") and processed by src/engine/renderer.js.
• src/constants/script.js exports the PAGE_MODE enum used throughout the codebase to ensure consistency.

Frequently Asked Questions

Can I mix LONGPAGE and SWIPERPAGE modes in the same Luban H5 project?

Yes. The mode is set per‑page, so a single project can contain multiple pages where some use LONGPAGE for content‑heavy sections and others use SWIPERPAGE for interactive galleries. The router simply loads each page with its respective renderer.

Which mode is better for mobile performance?

LONGPAGE generally yields better performance on low‑end devices because it avoids the overhead of the Swiper library and relies on native scrolling. SWIPERPAGE is still highly optimized, but the additional DOM wrappers and JavaScript event listeners make it slightly heavier; use it when the UX benefit of swipe navigation outweighs the marginal cost.

How do I add transition effects to SWIPERPAGE slides?

Transition effects are configured via the swiperConfig object in the page JSON. Set the effect property to "slide", "fade", "cube", "coverflow", or "flip". The renderer passes these options directly to the Swiper constructor in the generated HTML.

Where is the page mode configuration stored?

The mode is stored in the page object within the project’s JSON schema, typically under src/store/modules/page.js or the exported project JSON. When the engine runs, src/engine/renderer.js reads page.mode and branches accordingly, using the constants defined in src/constants/script.js.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}