Package com.oorian.html.layout

Class AppShellLayout

java.lang.Object
com.oorian.html.Element<AppShellLayout>
com.oorian.html.VisualElement<AppShellLayout>
com.oorian.html.StyledElement<AppShellLayout>
com.oorian.html.layout.PageLayout<AppShellLayout>
com.oorian.html.layout.AppShellLayout
All Implemented Interfaces:
ClientEventListener, MouseClickListener, EventListener
public class AppShellLayout extends PageLayout<AppShellLayout> implements MouseClickListener
A standard application shell layout with header, sidebar, content, and footer regions.

AppShellLayout is the backbone of dashboards, admin panels, and internal tools. It provides a consistent structure with optional regions that can be configured to match various application needs.

Structure:

 ┌──────────────────────────────────────┐
 │              Header                  │
 ├─────────┬────────────────────────────┤
 │         │                            │
 │ Sidebar │         Content            │
 │         │                            │
 │         │                            │
 ├─────────┴────────────────────────────┤
 │              Footer                  │
 └──────────────────────────────────────┘

Features:

  • Optional header, sidebar, and footer
  • Left or right sidebar positioning
  • Collapsible sidebar support
  • Sticky header option
  • Full viewport or parent-relative sizing

Usage:


 // Section-based layout (recommended) - nav items auto-generated
 AppShellLayout shell = new AppShellLayout();
 shell.header(navbar)
      .addSection("Dashboard", dashboardContent)
      .addSection("Reports", reportsContent)
      .addSection("Settings", settingsContent);

 // Programmatic navigation
 shell.showSection(1);  // Show "Reports"
 shell.showSection("settings");  // Show by ID

 // Manual mode (for custom sidebar)
 AppShellLayout shell = new AppShellLayout();
 shell.header(navbar)
      .sidebar(customNavigation)
      .content(mainContent)
      .footer(footerBar);

 // Full viewport with sticky header
 AppShellLayout app = new AppShellLayout();
 app.setFillViewport()
    .setStickyHeader()
    .header(header)
    .addSection("Home", homeContent)
    .addSection("Profile", profileContent);

 // Right sidebar variant
 AppShellLayout rightSidebar = AppShellLayout.withRightSidebar();
 rightSidebar.header(header)
             .sidebar(propertiesPanel)
             .content(editor);

 // Customize sidebar width
 shell.setSidebarWidth(280);
 shell.setSidebarWidth("20%");
Since:
2025
Version:
1.0
Author:
Marvin P. Warble Jr.
See Also:

  • Constructor Details

    • AppShellLayout

      public AppShellLayout()
      Constructs an AppShellLayout with default left sidebar.

    • AppShellLayout

      public AppShellLayout(AppShellLayout.SidebarPosition position)
      Constructs an AppShellLayout with the specified sidebar position.
      Parameters:
      position - the sidebar position (LEFT or RIGHT)

  • Method Details

    • initialize

      protected void initialize()
      Builds the element tree for the layout.
      Overrides:
      initialize in class StyledElement<AppShellLayout>

    • withRightSidebar

      public static AppShellLayout withRightSidebar()
      Creates a new AppShellLayout with right sidebar.
      Returns:
      a new AppShellLayout with right sidebar

    • header

      public AppShellLayout header(Element<?> header)
      Sets the header content.
      Parameters:
      header - the header element
      Returns:
      this AppShellLayout for method chaining

    • sidebar

      public AppShellLayout sidebar(Element<?> sidebar)
      Sets the sidebar content.
      Parameters:
      sidebar - the sidebar element
      Returns:
      this AppShellLayout for method chaining

    • content

      public AppShellLayout content(Element<?> content)
      Sets the main content area.
      Parameters:
      content - the content element
      Returns:
      this AppShellLayout for method chaining

    • footer

      public AppShellLayout footer(Element<?> footer)
      Sets the footer content.
      Parameters:
      footer - the footer element
      Returns:
      this AppShellLayout for method chaining

    • setSidebarWidth

      public AppShellLayout setSidebarWidth(int width)
      Sets the sidebar width.
      Parameters:
      width - the width in pixels
      Returns:
      this AppShellLayout for method chaining

    • setSidebarWidth

      public AppShellLayout setSidebarWidth(String width)
      Sets the sidebar width.
      Parameters:
      width - the width value (e.g., "260px", "20%", "16rem")
      Returns:
      this AppShellLayout for method chaining

    • setStickyHeader

      public AppShellLayout setStickyHeader()
      Makes the header sticky (fixed at top during scroll).
      Returns:
      this AppShellLayout for method chaining

    • setStickySidebar

      public AppShellLayout setStickySidebar(String top)
      Makes the sidebar sticky so it remains visible while the page content scrolls.

      When sticky sidebar is enabled, the layout switches from internal content scrolling to page-level scrolling. The sidebar stays fixed in the viewport while the content and footer scroll naturally.

      Parameters:
      top - the CSS top offset (e.g., "70px" to clear a navbar)
      Returns:
      this AppShellLayout for method chaining

    • setStickySidebar

      public AppShellLayout setStickySidebar(int top)
      Makes the sidebar sticky with a top offset in pixels.
      Parameters:
      top - the top offset in pixels
      Returns:
      this AppShellLayout for method chaining

    • setThinSidebarScrollbar

      public AppShellLayout setThinSidebarScrollbar(boolean thin)
      Enables or disables a thin scrollbar for the sidebar pane.

      When enabled, renders a narrow 4px scrollbar with no arrows, using native thin scrollbar support in Firefox and webkit pseudo-elements in Chrome/Safari/Edge.

      Parameters:
      thin - true to use a thin scrollbar, false for the default scrollbar
      Returns:
      this AppShellLayout for method chaining

    • setAutoHideSidebarScrollbar

      public AppShellLayout setAutoHideSidebarScrollbar(boolean autoHide)
      Enables or disables an auto-hiding thin scrollbar for the sidebar.

      When enabled, the scrollbar is hidden by default and appears when the user hovers over the sidebar. Implies thin scrollbar.

      Parameters:
      autoHide - true to auto-hide the scrollbar, false for default behavior
      Returns:
      this AppShellLayout for method chaining

    • setHeaderBackground

      public AppShellLayout setHeaderBackground(String color)
      Sets the header background color.
      Parameters:
      color - the background color
      Returns:
      this AppShellLayout for method chaining

    • setSidebarBackground

      public AppShellLayout setSidebarBackground(String color)
      Sets the sidebar background color.
      Parameters:
      color - the background color
      Returns:
      this AppShellLayout for method chaining

    • setContentBackground

      public AppShellLayout setContentBackground(String color)
      Sets the content area background color.
      Parameters:
      color - the background color
      Returns:
      this AppShellLayout for method chaining

    • setFooterBackground

      public AppShellLayout setFooterBackground(String color)
      Sets the footer background color.
      Parameters:
      color - the background color
      Returns:
      this AppShellLayout for method chaining

    • collapseSidebar

      public AppShellLayout collapseSidebar()
      Collapses the sidebar to hide it.
      Returns:
      this AppShellLayout for method chaining

    • expandSidebar

      public AppShellLayout expandSidebar()
      Expands the sidebar to show it.
      Returns:
      this AppShellLayout for method chaining

    • toggleSidebar

      public AppShellLayout toggleSidebar()
      Toggles the sidebar collapsed/expanded state.
      Returns:
      this AppShellLayout for method chaining

    • isSidebarCollapsed

      public boolean isSidebarCollapsed()
      Checks if the sidebar is currently collapsed.
      Returns:
      true if collapsed

    • setContentGap

      public AppShellLayout setContentGap(int gap)
      Sets the gap between sidebar and content.
      Parameters:
      gap - the gap in pixels
      Returns:
      this AppShellLayout for method chaining

    • setContentGap

      public AppShellLayout setContentGap(String gap)
      Sets the gap between sidebar and content.
      Parameters:
      gap - the gap value (e.g., "16px", "1rem")
      Returns:
      this AppShellLayout for method chaining

    • setContentPadding

      public AppShellLayout setContentPadding(int padding)
      Sets padding for the content area.
      Parameters:
      padding - the padding in pixels
      Returns:
      this AppShellLayout for method chaining

    • setContentPadding

      public AppShellLayout setContentPadding(String padding)
      Sets padding for the content area.
      Parameters:
      padding - the padding value (e.g., "1rem", "24px")
      Returns:
      this AppShellLayout for method chaining

    • setSidebarPadding

      public AppShellLayout setSidebarPadding(int padding)
      Sets padding for the sidebar.
      Parameters:
      padding - the padding in pixels
      Returns:
      this AppShellLayout for method chaining

    • setSidebarPadding

      public AppShellLayout setSidebarPadding(String padding)
      Sets padding for the sidebar.
      Parameters:
      padding - the padding value (e.g., "1rem", "16px")
      Returns:
      this AppShellLayout for method chaining

    • getHeaderPane

      public Div getHeaderPane()
      Returns the header pane for advanced customization.
      Returns:
      the header pane

    • getSidebarPane

      public Div getSidebarPane()
      Returns the sidebar pane for advanced customization.
      Returns:
      the sidebar pane

    • getContentPane

      public Div getContentPane()
      Returns the content pane for advanced customization.
      Returns:
      the content pane

    • getFooterPane

      public Div getFooterPane()
      Returns the footer pane for advanced customization.
      Returns:
      the footer pane

    • addSection

      public AppShellLayout addSection(String label, Element<?> content)
      Adds a section with the specified label and content.

      This creates a clickable nav item in the sidebar and adds the content to an internal Deck. Clicking the nav item will show the corresponding content.

      Parameters:
      label - the nav label for this section
      content - the content to display when this section is selected
      Returns:
      this AppShellLayout for method chaining

    • addSection

      public AppShellLayout addSection(String label, String id, Element<?> content)
      Adds a section with the specified label, ID, and content.

      This creates a clickable nav item in the sidebar and adds the content to an internal Deck. Clicking the nav item will show the corresponding content.

      Parameters:
      label - the nav label for this section
      id - optional ID for programmatic access (if null, generated from label)
      content - the content to display when this section is selected
      Returns:
      this AppShellLayout for method chaining

    • showSection

      public AppShellLayout showSection(int index)
      Shows the section at the specified index.
      Parameters:
      index - the section index (0-based)
      Returns:
      this AppShellLayout for method chaining

    • showSection

      public AppShellLayout showSection(String id)
      Shows the section with the specified ID.
      Parameters:
      id - the section ID
      Returns:
      this AppShellLayout for method chaining

    • getActiveSectionIndex

      public int getActiveSectionIndex()
      Returns the currently active section index.
      Returns:
      the active section index, or -1 if no section is active

    • getSectionCount

      public int getSectionCount()
      Returns the number of sections.
      Returns:
      the section count

    • onEvent

      public void onEvent(MouseClickedEvent event)
      Handles click events on nav items.
      Specified by:
      onEvent in interface MouseClickListener
      Parameters:
      event - the mouse click event

    • setNavItemGap

      public AppShellLayout setNavItemGap(int gap)
      Sets the gap between nav items.
      Parameters:
      gap - the gap in pixels
      Returns:
      this AppShellLayout for method chaining

    • setNavItemGap

      public AppShellLayout setNavItemGap(String gap)
      Sets the gap between nav items.
      Parameters:
      gap - the gap value (e.g., "8px", "0.5rem")
      Returns:
      this AppShellLayout for method chaining

    • getNavItems

      public VStack getNavItems()
      Returns the nav items container for customization.
      Returns:
      the nav items VStack

    • getContentDeck

      public Deck getContentDeck()
      Returns the content deck for advanced customization.
      Returns:
      the content Deck