Appearance

Homepage Settings ​

This guide covers how to select and configure your homepage, set it as default, and manage homepage widgets.

Table of Contents ​

  1. Accessing Homepage Settings
  2. Homepage Selection
  3. Setting Default Homepage
  4. Homepage Widget Management
  5. Adding Widgets
  6. Editing Widget Configuration
  7. Reordering Widgets
  8. Widget Visibility
  9. Removing Widgets
  10. Widget Types and Configuration
  11. Best Practices

Accessing Homepage Settings ​

From Admin Panel ​

  1. Log in to your admin panel
  2. Navigate to Settings → Pages → Homepage Selection
  3. Or go directly to: /admin/settings/pages/homepage-selector

Permissions Required ​

  • Manage Settings: manage-settings permission

Homepage Selection ​

The system comes with multiple pre-configured homepage templates designed for different industries. Each homepage has its own theme, color scheme, and widget configuration.

Viewing Available Homepages ​

  1. Navigate to Settings → Pages → Homepage Selection
  2. You'll see a grid of available homepage templates
  3. Each homepage card displays:
    • Thumbnail: Visual preview of the homepage
    • Name: Homepage template name
    • Description: Brief description of the template
    • Theme: Associated color scheme/theme
    • Widget Count: Number of widgets configured
    • Status: Whether it's set as default

Previewing a Homepage ​

  1. Click on any homepage card to select it
  2. Click the Preview button to view the homepage in a new tab
  3. Or click the Eye icon on the homepage card
  4. This opens the homepage at: /home/{id}

Homepage Information ​

Each homepage includes:

  • Theme Key: The color scheme identifier
  • Theme Colors: Primary, light, and dark color variants
  • Widget Configuration: Pre-configured widgets for that industry
  • Active Status: Whether the homepage is active

Setting Default Homepage ​

The default homepage is what visitors see when they visit your website's root URL (/). Only one homepage can be set as default at a time.

Method 1: Quick Set from Card ​

  1. Click on a homepage card to select it
  2. If the homepage is not already default, a "Set Default" button appears
  3. Click "Set Default" button
  4. Wait for the confirmation message

Method 2: Using Action Panel ​

  1. Click on a homepage card to open the action panel at the bottom
  2. Click the "Set as Default Homepage" button
  3. A confirmation message will appear

What Happens When Setting Default ​

When you set a homepage as default:

  1. Previous Default: The previously default homepage is automatically unset
  2. Theme Application: The homepage's associated theme/color scheme is applied to your entire website
  3. URL Routing: The homepage becomes accessible at the root URL (/)
  4. Visual Indicator: The homepage card shows an "Active" badge and purple border

Important Notes ​

  • Theme Change: Setting a new default homepage will change your website's color scheme globally
  • Widgets: The default homepage's widgets will be displayed on the frontend
  • Immediate Effect: Changes take effect immediately after confirmation

Homepage Widget Management ​

Widgets are the building blocks of your homepage. Each widget represents a section or component that appears on your homepage.

Accessing Widget Management ​

  1. Navigate to Settings → Pages → Homepage Selection
  2. Click on a homepage card
  3. Click the "Edit" button (or "Manage Widgets" in the action panel)
  4. Or go directly to: /admin/settings/pages/homepage/{homepageId}/widgets

Widget Management Interface ​

The widget management page shows:

  • Header: Homepage name and description
  • Add Widget Button: Add new widgets to the homepage
  • Active Widgets List: All widgets currently on the homepage
  • Widget Cards: Each widget displayed as a card with:
    • Widget icon and name
    • Visibility status (visible/hidden)
    • Configuration button
    • Delete button
    • Drag handle for reordering

Adding Widgets ​

Step 1: Open Add Widget Modal ​

  1. On the widget management page, click the "Add Widget" button (top right)
  2. A modal window opens showing available widgets

Step 2: Browse Available Widgets ​

Widgets are organized by categories:

  • Content: Blog, Products, Services, Events, Testimonials, Portfolio, Team, etc.
  • Marketing: Hero, CTA, Pricing, Stats, Newsletter, etc.
  • Social: Social Feed, etc.
  • Custom: Custom HTML, Video, Gallery, Map, Contact Form, etc.

Step 3: Search for Widgets ​

  • Use the search box at the top of the modal to filter widgets
  • Search by widget name, description, or type

Step 4: Select a Widget ​

  1. Browse or search for the widget you want to add
  2. Click on the widget card
  3. The widget is immediately added to your homepage

Step 5: Configure the Widget (Optional) ​

After adding, you can:

  1. Click the Settings icon on the widget card
  2. Configure the widget settings (see Editing Widget Configuration)
  3. Or configure it later

Editing Widget Configuration ​

Each widget has specific configuration options. Here's how to edit them:

Opening Configuration Modal ​

  1. On the widget management page, find the widget you want to configure
  2. Click the Settings (gear) icon on the widget card
  3. A configuration modal opens

Configuration Options ​

The configuration modal includes:

1. Widget Visibility Toggle ​

  • Location: Top of the configuration modal
  • Purpose: Show or hide the widget on the homepage
  • Usage: Toggle the switch to enable/disable visibility
  • Note: Hidden widgets are not displayed on the frontend but remain in the list

2. Basic Configuration Fields ​

Common fields available for most widgets:

  • Title: Main heading for the widget section
  • Subtitle: Secondary heading or tagline
  • Description: Brief description text
  • Show CTA: Toggle to show/hide call-to-action button
  • CTA Text: Text for the call-to-action button
  • CTA URL: Link destination for the CTA button

3. Widget-Specific Configuration ​

Each widget type has unique configuration options:

Hero Widget ​
  • Title: Main hero heading
  • Subtitle: Supporting text
  • Description: Additional description
  • Background Image: Upload background image
  • Button Text: Primary CTA button text
  • Button URL: Primary CTA button link
  • Secondary Button Text: Optional second button
  • Secondary Button URL: Optional second button link
Blog Widget ​
  • Title: Section title
  • Post Count: Number of posts to display (1-12)
  • Category Filter: Select specific blog categories
  • Featured Only: Show only featured posts
  • Layout: Grid or slider layout
  • Columns: Number of columns (2-4)
Products Widget ​
  • Title: Section title
  • Product Limit: Number of products to display (1-12)
  • Product IDs: Select specific products (leave empty for all)
  • Category Filter: Filter by product categories
  • Featured Only: Show only featured products
  • Layout: Grid or slider
  • Columns: Number of columns (2-4)
Services Widget ​
  • Title: Section title
  • Service Count: Number of services to display
  • Category Filter: Filter by service categories
  • Layout: Grid or slider
  • Columns: Number of columns
Testimonials Widget ​
  • Title: Section title
  • Testimonial Limit: Number of testimonials to show
  • Testimonial IDs: Select specific testimonials
  • Autoplay: Enable automatic slider rotation
  • Autoplay Delay: Delay between slides (milliseconds)
Team Widget ​
  • Title: Section title
  • Member IDs: Select specific team members to display
  • Layout: Grid or slider
  • Columns: Number of columns
Pricing Widget ​
  • Title: Section title
  • Plan IDs: Select specific pricing plans
  • Category Filter: Filter by plan categories
  • Layout: Grid or slider
Stats Widget ​
  • Title: Section title
  • Stats: Array of statistics to display
    • Label: Stat label (e.g., "Happy Clients")
    • Value: Stat value (e.g., "1000+")
    • Percentage: Optional percentage value
    • Color: Display color
    • Description: Additional description
    • Icon: Icon identifier
  • Title: Section title
  • Source Type: Choose source:
    • Manual: Upload images manually
    • Portfolio: Use portfolio items
    • Products: Use product images
    • Causes: Use cause images (for non-profit)
  • Image Limit: Maximum number of images
  • Portfolio IDs: Select portfolios (if source is portfolio)
  • Product IDs: Select products (if source is products)
  • Cause IDs: Select causes (if source is causes)
  • Manual Images: Upload images manually (if source is manual)
Events Widget ​
  • Title: Section title
  • Event Limit: Number of events to display
  • Event IDs: Select specific events
  • Category Filter: Filter by event categories
  • Layout: Grid or slider
Newsletter Widget ​
  • Title: Section title
  • Description: Newsletter description
  • Placeholder Text: Input field placeholder
  • Button Text: Submit button text
Contact Form Widget ​
  • Title: Section title
  • Description: Form description
  • Fields: Configure form fields
  • Submit Button Text: Submit button label
CTA Widget ​
  • Title: Section title
  • Description: CTA description
  • Button Text: CTA button text
  • Button URL: CTA button link
  • Background Color: Optional background color

Saving Configuration ​

  1. Make your changes in the configuration modal
  2. Click the "Save" button at the bottom of the modal
  3. Wait for the success confirmation
  4. The modal closes automatically

Image Uploads ​

For widgets that support images (Hero, Gallery, Slider, etc.):

  1. Click the "Upload" or "Choose File" button
  2. Select an image file from your computer
  3. The image preview appears immediately
  4. Click "Save" to upload and apply the image

Supported Formats: JPG, PNG, GIF, WebP Recommended Size: Varies by widget (check tooltips)

Reordering Widgets ​

Widgets appear on your homepage in the order they're listed in the widget management page. You can reorder them using drag and drop.

Method 1: Drag and Drop ​

  1. On the widget management page, locate the widget you want to move
  2. Click and hold the drag handle (grip icon) on the left side of the widget card
  3. Drag the widget up or down to the desired position
  4. Release the mouse button
  5. The widgets automatically reorder and save

Visual Feedback ​

  • While dragging, the widget becomes semi-transparent
  • A placeholder shows where the widget will be placed
  • Other widgets move to make space

Order Persistence ​

  • The new order is saved automatically
  • Changes take effect immediately on the frontend
  • The order is preserved even after page refresh

Widget Visibility ​

You can show or hide widgets without deleting them. This is useful for testing or temporarily hiding sections.

Toggle Visibility from Widget Card ​

  1. On the widget management page, find the widget
  2. Click the Eye icon (visible) or Eye Off icon (hidden)
  3. The visibility status toggles immediately
  4. A success message confirms the change

Toggle Visibility from Configuration ​

  1. Open the widget configuration modal
  2. Use the Widget Visibility toggle at the top
  3. Click Save to apply changes

Visual Indicators ​

  • Visible Widgets: Normal appearance, Eye icon visible
  • Hidden Widgets: Semi-transparent appearance, Eye Off icon visible
  • Hidden widgets are not displayed on the frontend but remain in the admin list

Removing Widgets ​

If you no longer need a widget on your homepage:

Step 1: Delete Widget ​

  1. On the widget management page, find the widget to remove
  2. Click the Trash icon on the widget card
  3. A confirmation dialog appears

Step 2: Confirm Deletion ​

  1. Review the confirmation message
  2. Click "OK" to confirm deletion
  3. Or click "Cancel" to keep the widget

Important Notes ​

  • Permanent Action: Deletion is permanent and cannot be undone
  • Configuration Lost: All widget configuration will be lost
  • Re-adding: You can add the widget again later, but you'll need to reconfigure it

Widget Types and Configuration ​

Content Widgets ​

These widgets display dynamic content from your CMS:

Blog Widget ​

Displays latest blog posts with filtering options.

Configuration:

  • Post count (1-12)
  • Category filtering
  • Featured posts only
  • Layout (grid/slider)
  • Column count

Products Widget ​

Shows featured products with category filtering.

Configuration:

  • Product limit (1-12)
  • Specific product selection
  • Category filtering
  • Featured products only
  • Layout and columns

Services Widget ​

Displays services with category options.

Configuration:

  • Service count
  • Category filtering
  • Layout and columns

Events Widget ​

Shows upcoming events with date filtering.

Configuration:

  • Event limit
  • Specific event selection
  • Category filtering
  • Layout options

Testimonials Widget ​

Displays customer testimonials in a slider.

Configuration:

  • Testimonial limit
  • Specific testimonial selection
  • Autoplay settings
  • Delay between slides

Team Widget ​

Shows team members with selection options.

Configuration:

  • Member selection
  • Layout and columns

Portfolio Widget ​

Displays portfolio items with category filtering.

Configuration:

  • Portfolio count
  • Category filtering
  • Layout options

Marketing Widgets ​

These widgets are designed for marketing and conversion:

Hero Widget ​

Main hero section with customizable content and images.

Configuration:

  • Title, subtitle, description
  • Background image
  • Primary and secondary CTA buttons
  • Button text and URLs

CTA Widget ​

Call-to-action section for conversions.

Configuration:

  • Title and description
  • Button text and URL
  • Background color

Pricing Widget ​

Displays pricing plans.

Configuration:

  • Plan selection
  • Category filtering
  • Layout options

Stats Widget ​

Shows business statistics with icons.

Configuration:

  • Multiple stat items
  • Each stat: label, value, percentage, color, description, icon

Newsletter Widget ​

Newsletter signup form.

Configuration:

  • Title and description
  • Placeholder text
  • Button text

Custom Widgets ​

These widgets provide custom functionality:

Image gallery with multiple source options.

Configuration:

  • Source type (manual, portfolio, products, causes)
  • Image limit
  • Source-specific selections
  • Manual image uploads

Contact Form Widget ​

Contact form with configurable fields.

Configuration:

  • Title and description
  • Form fields configuration
  • Submit button text

Video Widget ​

Video embed section.

Configuration:

  • Video URL (YouTube, Vimeo, etc.)
  • Title and description
  • Autoplay settings

Map Widget ​

Google Maps integration.

Configuration:

  • Map location
  • Zoom level
  • Marker settings

Custom HTML Widget ​

Raw HTML content.

Configuration:

  • HTML content
  • Title (optional)

Best Practices ​

Homepage Selection ​

  1. Choose Industry-Appropriate Template: Select a homepage template that matches your business type
  2. Preview Before Setting Default: Always preview a homepage before setting it as default
  3. Theme Consistency: Remember that setting a default homepage applies its theme globally

Widget Management ​

  1. Start with Pre-configured Widgets: Use the widgets that come with each homepage template
  2. Add Widgets Gradually: Add widgets one at a time and test each addition
  3. Logical Order: Arrange widgets in a logical flow:
    • Hero section first
    • Key content sections in the middle
    • CTA or contact form at the end
  4. Test Visibility: Use the visibility toggle to test different widget combinations
  5. Mobile Responsiveness: Test your homepage on mobile devices after making changes

Widget Configuration ​

  1. Use Descriptive Titles: Make widget titles clear and descriptive
  2. Optimize Images: Compress images before uploading for better performance
  3. Limit Content Count: Don't display too many items (e.g., keep blog posts to 6-8)
  4. Test CTAs: Ensure all call-to-action buttons link to correct pages
  5. Category Filtering: Use category filters to show relevant content

Performance Tips ​

  1. Limit Widget Count: Too many widgets can slow down page load
  2. Optimize Images: Use compressed, web-optimized images
  3. Use Lazy Loading: Enable lazy loading for image-heavy widgets
  4. Cache Settings: Ensure caching is enabled for better performance

Content Strategy ​

  1. Hero Section: Make your hero section compelling with clear value proposition
  2. Content Flow: Arrange widgets to tell a story or guide users through your site
  3. CTAs: Include clear calls-to-action in relevant widgets
  4. Social Proof: Use testimonials and stats widgets to build trust
  5. Fresh Content: Regularly update dynamic content widgets (blog, products, events)

Troubleshooting ​

Widget Not Appearing on Frontend ​

Possible Causes:

  • Widget is hidden (check visibility toggle)
  • Widget configuration is incomplete
  • Cache needs to be cleared

Solutions:

  1. Check widget visibility status
  2. Verify widget configuration is saved
  3. Clear application cache
  4. Check browser cache

Widget Configuration Not Saving ​

Possible Causes:

  • Required fields not filled
  • File upload too large
  • Network issues

Solutions:

  1. Check for required field indicators
  2. Reduce image file size
  3. Check internet connection
  4. Try saving again

Homepage Not Updating After Setting Default ​

Possible Causes:

  • Cache not cleared
  • Browser cache
  • Route caching

Solutions:

  1. Clear application cache
  2. Clear browser cache
  3. Wait a few minutes for changes to propagate

Drag and Drop Not Working ​

Possible Causes:

  • JavaScript disabled
  • Browser compatibility
  • Page not fully loaded

Solutions:

  1. Enable JavaScript in browser
  2. Try a different browser
  3. Refresh the page and try again

Last Updated: 1/22/2026

Released under the MIT License.

Copyright © 2024 AI-Powered CMS