Package com.oorian.html.layout

Class DocsLayout

java.lang.Object
com.oorian.html.Element<DocsLayout>
com.oorian.html.VisualElement<DocsLayout>
com.oorian.html.StyledElement<DocsLayout>
com.oorian.html.layout.PageLayout<DocsLayout>
com.oorian.html.layout.DocsLayout
All Implemented Interfaces:
ClientEventListener, MouseClickListener, EventListener
public class DocsLayout extends PageLayout<DocsLayout> implements MouseClickListener
A documentation-style layout with left navigation, main content, and right TOC.

DocsLayout provides the classic three-column documentation layout used by sites like Docusaurus, GitBook, and ReadTheDocs. The left column contains navigation, the center has the main content, and the right column shows a table of contents for the current page.

Structure:

 ┌────────┬─────────────────────────┬────────┐
 │        │                         │        │
 │  Nav   │        Content          │  TOC   │
 │        │                         │        │
 │ (Left) │       (Center)          │(Right) │
 │        │                         │        │
 └────────┴─────────────────────────┴────────┘

Features:

  • Sticky navigation and TOC columns
  • Responsive: TOC hides on tablet, Nav hides on mobile
  • Configurable column widths
  • Optional header area for breadcrumbs or page title
  • Scrollable content with fixed sidebars

Usage:


 // Section-based docs (recommended) - nav items auto-generated
 DocsLayout docs = new DocsLayout();
 docs.addSection("Getting Started", gettingStartedContent)
     .addSection("Installation", installationContent)
     .addSection("API Reference", apiReferenceContent);

 // With TOC
 docs.toc(tableOfContents);

 // Programmatic navigation
 docs.showSection(1);  // Show "Installation"
 docs.showSection("api-reference");  // Show by ID

 // Manual mode (for custom nav)
 DocsLayout docs = new DocsLayout();
 docs.nav(customNavigation)
     .content(articleContent)
     .toc(tableOfContents);

 // With custom widths
 DocsLayout docs = new DocsLayout();
 docs.setNavWidth(280)
     .setTocWidth(220);

 // With header
 docs.header(breadcrumbs);
Since:
2025
Version:
1.0
Author:
Marvin P. Warble Jr.
See Also:

  • Constructor Details

    • DocsLayout

      public DocsLayout()
      Constructs a DocsLayout with default column widths.

  • Method Details

    • initialize

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

    • content

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

    • toc

      public DocsLayout toc(Element<?> toc)
      Sets the table of contents (right sidebar) content.
      Parameters:
      toc - the table of contents element
      Returns:
      this DocsLayout for method chaining

    • header

      public DocsLayout header(Element<?> header)
      Sets the header content (shown above the main content).
      Parameters:
      header - the header element (breadcrumbs, page title, etc.)
      Returns:
      this DocsLayout for method chaining

    • setNavWidth

      public DocsLayout setNavWidth(int width)
      Sets the navigation column width.
      Parameters:
      width - the width in pixels
      Returns:
      this DocsLayout for method chaining

    • setNavWidth

      public DocsLayout setNavWidth(String width)
      Sets the navigation column width.
      Parameters:
      width - the width value (e.g., "260px", "20%")
      Returns:
      this DocsLayout for method chaining

    • setTocWidth

      public DocsLayout setTocWidth(int width)
      Sets the TOC column width.
      Parameters:
      width - the width in pixels
      Returns:
      this DocsLayout for method chaining

    • setTocWidth

      public DocsLayout setTocWidth(String width)
      Sets the TOC column width.
      Parameters:
      width - the width value (e.g., "200px", "15%")
      Returns:
      this DocsLayout for method chaining

    • noStickyNav

      public DocsLayout noStickyNav()
      Disables sticky positioning for the nav column.
      Returns:
      this DocsLayout for method chaining

    • noStickyToc

      public DocsLayout noStickyToc()
      Disables sticky positioning for the TOC column.
      Returns:
      this DocsLayout for method chaining

    • setNavBackground

      public DocsLayout setNavBackground(String color)
      Sets the navigation background color.
      Parameters:
      color - the background color
      Returns:
      this DocsLayout for method chaining

    • setContentBackground

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

    • setTocBackground

      public DocsLayout setTocBackground(String color)
      Sets the TOC background color.
      Parameters:
      color - the background color
      Returns:
      this DocsLayout for method chaining

    • setNavPadding

      public DocsLayout setNavPadding(int padding)
      Sets padding for the navigation area.
      Parameters:
      padding - the padding in pixels
      Returns:
      this DocsLayout for method chaining

    • setNavPadding

      public DocsLayout setNavPadding(String padding)
      Sets padding for the navigation area.
      Parameters:
      padding - the padding value (e.g., "1rem", "16px")
      Returns:
      this DocsLayout for method chaining

    • setContentPadding

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

    • setContentPadding

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

    • setTocPadding

      public DocsLayout setTocPadding(int padding)
      Sets padding for the TOC area.
      Parameters:
      padding - the padding in pixels
      Returns:
      this DocsLayout for method chaining

    • setTocPadding

      public DocsLayout setTocPadding(String padding)
      Sets padding for the TOC area.
      Parameters:
      padding - the padding value (e.g., "1rem", "16px")
      Returns:
      this DocsLayout for method chaining

    • setContentMaxWidth

      public DocsLayout setContentMaxWidth(String maxWidth)
      Sets a maximum width for the content area.
      Parameters:
      maxWidth - the maximum width (e.g., "800px", "60rem")
      Returns:
      this DocsLayout for method chaining

    • setTocHeader

      public DocsLayout setTocHeader(String text)
      Sets the TOC header text (e.g., "On this page").

      Call this before adding TOC headings to set a title for the TOC section.

      Parameters:
      text - the header text
      Returns:
      this DocsLayout for method chaining

    • addTocHeading

      public DocsLayout addTocHeading(Element<?> heading, StyledContainerElement<?> container)
      Adds a heading to the specified container and creates a corresponding TOC link.

      This method automatically:

      • Generates an anchor ID from the heading text
      • Sets the ID on the heading element
      • Adds the heading to the container
      • Creates a TOC link that scrolls to the heading when clicked

      Usage:

      
 Div content = new Div();
 docs.addTocHeading(new H2("Getting Started"), content);
 docs.addTocHeading(new H3("Installation"), content);
 docs.addTocHeading(new H3("Configuration"), content);
 docs.content(content);
      Parameters:
      heading - the heading element (H1, H2, H3, etc.)
      container - the container to add the heading to
      Returns:
      this DocsLayout for method chaining

    • addTocHeading

      public DocsLayout addTocHeading(Element<?> heading, StyledContainerElement<?> container, String anchorId)
      Adds a heading to the specified container and creates a corresponding TOC link with a custom ID.
      Parameters:
      heading - the heading element (H1, H2, H3, etc.)
      container - the container to add the heading to
      anchorId - optional custom anchor ID (if null, generated from heading text)
      Returns:
      this DocsLayout for method chaining

    • clearToc

      public DocsLayout clearToc()
      Clears the TOC and prepares for new TOC links.

      Call this when switching sections to reset the TOC for the new section's headings.

      Returns:
      this DocsLayout for method chaining

    • getTocItems

      public VStack getTocItems()
      Returns the TOC items container for customization.
      Returns:
      the TOC items VStack

    • setColumnGap

      public DocsLayout setColumnGap(int gap)
      Sets the gap between columns.
      Parameters:
      gap - the gap in pixels
      Returns:
      this DocsLayout for method chaining

    • setColumnGap

      public DocsLayout setColumnGap(String gap)
      Sets the gap between columns.
      Overrides:
      setColumnGap in class StyledElement<DocsLayout>
      Parameters:
      gap - the gap value (e.g., "24px", "2rem")
      Returns:
      this DocsLayout for method chaining

    • setNavBorder

      public DocsLayout setNavBorder(String border)
      Adds a border to the navigation column.
      Parameters:
      border - the border value (e.g., "1px solid #e0e0e0")
      Returns:
      this DocsLayout for method chaining

    • setTocBorder

      public DocsLayout setTocBorder(String border)
      Adds a border to the TOC column.
      Parameters:
      border - the border value (e.g., "1px solid #e0e0e0")
      Returns:
      this DocsLayout for method chaining

    • getNavPane

      public Div getNavPane()
      Returns the navigation pane for advanced customization.
      Returns:
      the navigation pane

    • getContentPane

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

    • getTocPane

      public Div getTocPane()
      Returns the TOC pane for advanced customization.
      Returns:
      the TOC pane

    • getHeaderPane

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

    • addSection

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

      This creates a clickable nav item 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 DocsLayout for method chaining

    • addSection

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

      This creates a clickable nav item 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 DocsLayout for method chaining

    • showSection

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

    • showSection

      public DocsLayout showSection(String id)
      Shows the section with the specified ID.
      Parameters:
      id - the section ID
      Returns:
      this DocsLayout 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 DocsLayout setNavItemGap(int gap)
      Sets the gap between nav items.
      Parameters:
      gap - the gap in pixels
      Returns:
      this DocsLayout for method chaining

    • setNavItemGap

      public DocsLayout setNavItemGap(String gap)
      Sets the gap between nav items.
      Parameters:
      gap - the gap value (e.g., "8px", "0.5rem")
      Returns:
      this DocsLayout 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