Theme Configuration Documentation

Overview

The Theme model provides comprehensive customization options for white-label instances of the Vibemap platform. Each theme controls the visual appearance, branding, and functional behavior of the platform for different organizations.

Table of Contents

1. Core Fields - Basic theme information and metadata
2. Visual Styling - Colors, branding, fonts, badges
3. Event Form Configuration - Event submission forms
4. Events Display Configuration - Event listing and display
5. Layout & Grid Display - Page layout and grid settings
6. Cards Configuration - Card appearance and content
7. Map Configuration - Comprehensive map settings
8. Filtering Configuration - Filter UI and behavior
9. Authentication - Login/signup options
10. Usage Examples - Code examples for common configurations
11. Best Practices - Recommended settings and guidelines

Quick Reference by Feature

Layout & View

• Grid Display: grid_columns, initial_view, show_left_panel
• Data Loading: shown_at_start, map_num_places_to_load

Cards

• Layout: card_style, hide_no_image_items
• Content: show_*_on_cards (15+ options for individual fields)
• Navigation: cards_open_to_website, cards_open_to_page

Map

• View: map_initial_lat/lng/zoom, map_style, initial_view
• Markers: map_marker_style, map_numbered_markers, map_cluster_markers
• Layers: map_show_boundary, map_show_heat_map, map_show_transit
• Interaction: map_scroll_zoom, map_cooperative_gestures, map_show_popups

Filters

• Display: show_filters_overall, filter_view_mode
• Types: show_tag_filters, show_category_filters, show_vibe_filters
• Behavior: filter_allow_multiple_selection, show_item_count_on_filters

---

Core Fields

Basic Information

Field	Type	Description
id	UUID	Unique identifier (auto-generated)
name	String (200)	Display name of the theme (unique)
slug	AutoSlug	URL-friendly identifier (auto-generated from name)
description	Text	Detailed description of the theme's purpose
created_at	DateTime	Timestamp of theme creation
updated_at	DateTime	Timestamp of last modification
icon	ImageField	Theme icon/logo file

---

Visual Styling

Color Scheme

These fields control the overall color palette of the interface.

Field	Type	Example	Description
color	String (50)	#333333	Primary text color
accent	String (50)	#FF6B6B	Primary accent color for buttons, links, highlights
secondary	String (50)	#4ECDC4	Secondary accent color for complementary elements
background	String (50)	#FFFFFF	Main background color
foreground	String (50)	#F7F7F7	Foreground/surface color for cards and panels

Supported formats: Hex codes (#RRGGBB), CSS color names (red, blue), RGB/RGBA values

Number Badge Styling

Controls the appearance of numeric indicators on map markers and cards.

Field	Type	Example	Description
num_text_color	String (50)	#FFFFFF	Text color inside number badges
num_badge_size	Integer	24	Badge size in pixels
num_bg_color	String (50)	#FF6B6B	Badge background color
num_border_color	String (50)	#CC5555	Badge border color
num_theme	String (10)	light or dark	Theme variant for automatic contrast adjustments

Branding

Field	Type	Description
logo_url	URL	Full URL to organization's logo image
font_url	URL	Google Fonts or custom font stylesheet URL (e.g., https://fonts.googleapis.com/css2?family=Roboto)

---

Event Form Configuration

Controls the event submission form appearance and behavior.

Display Settings

Field	Type	Default	Description
event_form_title	String (255)	-	Custom title for the event submission form
event_form_message	Text	-	Instructional message shown on the form
event_form_show_vibe_points	Boolean	false	Display vibe point allocation interface
event_form_show_intro_message	Boolean	false	Show introductory message before form
event_form_header_color	String (50)	-	Header background color (hex or CSS color)

Form Behavior

Field	Type	Default	Description
event_form_link	URL	-	External URL to redirect form submissions (overrides built-in form)
event_form_city	String (100)	-	Default city pre-filled in location field
event_form_auto_tags	JSON Array	null	Tags automatically applied to submitted events Example: ["community", "local"]
event_form_required_fields	JSON Array	null	List of required field names Example: ["title", "date", "location"]
event_form_requires_approval	Boolean	false	Events require admin approval before publication

---

Events Display Configuration

Controls how events are displayed to end users.

Event List Settings

Field	Type	Default	Description
events_link	URL	-	Custom URL for "View All Events" link
events_link_newsletter	URL	-	Newsletter signup link shown in events section
events_show_only_event_tags	Boolean	false	Filter to show only event-specific tags
events_event_layout	String (50)	-	Layout style (e.g., columns, grid, list)
events_search_placeholder	String (100)	-	Placeholder text for event search box
events_open_in_new_tab	Boolean	false	Open event details in new browser tab

Event Filtering

Field	Type	Description
events_tag_auto	JSON Array	Tags to automatically filter/highlight Example: ["featured", "trending"]
events_vibes	JSON Array	Array of vibe slugs to display in filters Example: ["artsy", "chill", "energetic"]

Geographic & Related Events

Field	Type	Default	Description
events_clip_to_bounds	Boolean	false	Restrict events to theme's geographic boundary
events_related_events	Boolean	false	Show related events section
events_related_events_radius	Float	-	Search radius for related events (in miles)

Media Settings

Field	Type	Default	Description
events_randomize_images	Boolean	false	Randomize order of event images in galleries

---

Layout & Grid Display

Controls the overall layout and grid presentation of content.

Field	Type	Default	Description
grid_columns	Integer	3	Number of columns in grid view
show_date_range_selector	Boolean	false	Show date filter in the interface
shown_at_start	Integer	100	Initial number of items to display on page load
show_left_panel	Boolean	true	Display the left sidebar panel
initial_view	String (20)	map	Starting view mode: map or grid

---

Cards Configuration

Controls the behavior and appearance of place/event cards throughout the interface.

Card Layout & Behavior

Field	Type	Default	Description
card_style	String (20)	list	Card display style: list or carousel
cards_open_to_website	Boolean	false	Cards link directly to venue website instead of detail page
cards_open_to_page	String (500)	-	Custom URL pattern for card links Example: /places/{slug} or https://external.com/venue/{id}
cards_open_to_blank	Boolean	true	Open card links in new tab (target="_blank")
cards_use_dynamic_link	Boolean	false	Use dynamic Firebase/branch.io deep links
hide_no_image_items	Boolean	false	Hide items without images from card display

Card Styling

Field	Type	Description
cards_title_color	String (50)	Color of card title text (hex or CSS color)
button_text_color	String (50)	Text color for buttons on cards

Card Content Display

Control which information appears on cards.

Field	Type	Default	Description
show_title_on_cards	Boolean	true	Display title on cards
show_image_on_cards	Boolean	true	Display image on cards
show_category_on_cards	Boolean	true	Display category label on cards
show_description_on_cards	Boolean	false	Display description text on cards
show_address_on_cards	Boolean	true	Display address on cards
show_distance_on_cards	Boolean	false	Display distance from user location on cards
show_hours_on_cards	Boolean	false	Display operating hours on cards
show_phone_on_cards	Boolean	false	Display phone number on cards
show_website_on_cards	Boolean	false	Display website link on cards
show_rating_on_cards	Boolean	true	Display rating/review score on cards
show_price_on_cards	Boolean	false	Display price level indicator on cards
show_vibes_on_cards	Boolean	false	Display vibe tags on cards
show_tags_on_cards	Boolean	false	Display tags on cards
show_notes_on_cards	Boolean	false	Display user notes on cards
show_offers_on_cards	Boolean	false	Display special offers on cards
show_offers_first	Boolean	false	Show offers at top of card (above other content)
show_bookmark_button	Boolean	true	Display bookmark/save button on cards
subtitle_source	String (50)	category	Source for card subtitle: category, address, description, etc.

---

Map Configuration

Comprehensive settings for map display and interactions.

Initial Map View

Controls the default map position and orientation when first loaded.

Field	Type	Default	Description
map_initial_lat	Float	-	Override default center latitude
map_initial_lng	Float	-	Override default center longitude
map_initial_zoom	Float	12	Default zoom level (typically 1-20)
map_initial_bearing	Float	0	Default compass bearing in degrees (0-360)
map_initial_pitch	Float	0	Default tilt angle in degrees (0-60)
map_zoom_min	Float	1	Minimum allowed zoom level
map_zoom_max	Float	20	Maximum allowed zoom level

Map Appearance

Field	Type	Default	Description
map_style	String (50)	light	Map visual style: light, dark, streets, satellite, etc.
map_height_offset	Integer	0	Adjust map container height by N pixels (can be negative)

Map Interaction

Field	Type	Default	Description
map_scroll_zoom	Boolean	true	Enable/disable scroll wheel zooming
map_cooperative_gestures	Boolean	false	Require Ctrl+scroll for zoom (prevents accidental zoom while scrolling page)
map_fit_bounds	Boolean	true	Auto-fit map to show all content on load
map_fit_markers	Boolean	true	Auto-fit map to show all markers on load
map_padding	Integer	50	Padding in pixels around map when fitting to bounds
map_story_scroll	Boolean	false	Enable story scroll mode for narrative map experiences

Markers & Clustering

Field	Type	Default	Description
map_show_markers	Boolean	true	Display map markers for places/events
map_marker_style	String (20)	icons	Marker display style: images or icons
map_num_image_markers	Integer	50	Number of image markers to show before switching to icons (performance optimization)
map_numbered_markers	Boolean	false	Display numbers on markers corresponding to card order
map_shuffle_markers	Boolean	false	Randomize marker positions slightly to avoid perfect overlap
map_show_circle_markers	Boolean	false	Use simple circle/dot markers instead of icons
map_cluster_markers	Boolean	false	Enable marker clustering for high-density areas
map_marker_featured	JSON Object	-	Configuration for featured/highlighted markers Example: {"icon": "star", "color": "#FFD700", "size": 1.5}
map_show_featured_first	Boolean	false	Display featured items at top of lists and prioritize on map

Popups & Overlays

Field	Type	Default	Description
map_show_popups	Boolean	true	Show popups when clicking markers
map_should_include_tags	Boolean	false	Include tag information in map marker popups
map_show_map_cards	Boolean	false	Show card carousel on map (mobile view)
map_title_cards	JSON Object	-	Configuration for informational cards overlaid on map Example: {"position": "top-right", "cards": [{"title": "Welcome", "content": "..."}]}

Map Layers & Overlays

Field	Type	Default	Description
map_show_boundary	Boolean	false	Show geographic boundary overlay
map_show_heat_map	Boolean	false	Display heatmap layer based on place density/popularity
map_show_route	Boolean	false	Display route line on map
map_route_color	String (50)	-	Color for route lines on map
map_show_transit	Boolean	false	Display public transit layer
map_show_legend	Boolean	false	Display map legend/key

Boundary Styling

Controls the appearance of geographic boundaries on the map.

Field	Type	Default	Description
map_boundary_fill_color	Text	-	Boundary fill color (hex) or Mapbox expression (JSON array) Example: #FF6B6B or ["interpolate", ["linear"], ["zoom"], ...]
map_boundary_fill_opacity	Float (0-1)	0.2	Transparency of boundary fill (0=transparent, 1=opaque)
map_boundary_line_color	String (50)	-	Boundary border line color
map_boundary_line_opacity	Float (0-1)	1.0	Transparency of boundary line
map_boundary_line_weight	Integer	2	Boundary line thickness in pixels
map_boundary_line_dash_array	JSON Array	-	Dash pattern for boundary line Example: [5, 3] (5px dash, 3px gap)
map_boundary_show_labels	Boolean	false	Display labels for boundary regions

Data Loading

Field	Type	Default	Description
map_num_places_to_load	Integer	100	Number of places to load on map initially
map_clip_to_bounds	Boolean	false	Restrict displayed places/events to theme's geographic boundary

Additional Map Features

Field	Type	Default	Description
map_show_scroll_area	Boolean	false	Show scrollable area indicator for off-screen content

---

Filtering Configuration

Global filtering rules and UI controls applied across the theme.

Filter Display Settings

Field	Type	Default	Description
show_top_level_filters	Boolean	true	Display filters at top of interface
filter_view_mode	String (50)	sidebar	Layout mode for filters: dropdown, sidebar, panel, etc.
show_filters_overall	Boolean	true	Enable/disable all filtering functionality
show_item_count_on_filters	Boolean	true	Display count of items for each filter option
filter_allow_multiple_selection	Boolean	true	Allow selecting multiple filter options simultaneously

Filter Types

Control which filter categories are available to users.

Field	Type	Default	Description
show_tag_filters	Boolean	true	Show tag filtering options
show_category_filters	Boolean	true	Show category filtering options
show_vibe_filters	Boolean	false	Show vibe filtering options
show_neighborhood_filters	Boolean	false	Show neighborhood/geography filtering options
show_search_in_filters	Boolean	true	Show search bar within filter panel

Tag Filtering

Field	Type	Description
filters_tags_to_exclude	JSON Array	Tags that should be hidden from this theme Example: ["admin-only", "test"]
filters_tags_to_include	JSON Array	Whitelist of tags to show (if set, only these appear) Example: ["featured", "verified", "local"]
filters_tag_names	JSON Object	Custom display names for tags Example: {"lgbtq-friendly": "LGBTQ+ Friendly", "wheelchair": "♿ Accessible"}

Category Styling

Field	Type	Description
map_category_colors	JSON Object	Map category names to marker colors Example: {"restaurant": "#FF6B6B", "cafe": "#4ECDC4", "bar": "#95E1D3"}

---

Authentication

Field	Type	Default	Description
show_login	Boolean	true	Display login/signup options in the interface

---

Usage Examples

Example 1: Simple Color Theme

theme = Theme.objects.create(
    name="Ocean Blue",
    accent="#0077BE",
    secondary="#00A8E8",
    background="#F0F8FF",
    foreground="#FFFFFF",
    color="#333333"
)

Example 2: Event-Focused Configuration

theme = Theme.objects.create(
    name="Community Events",
    event_form_title="Submit Your Event",
    event_form_city="San Francisco",
    event_form_auto_tags=["community", "local"],
    event_form_required_fields=["title", "date", "location", "description"],
    event_form_requires_approval=True,
    events_vibes=["family-friendly", "outdoors", "cultural"],
    events_related_events=True,
    events_related_events_radius=5.0
)

Example 3: Map-Heavy Custom Theme

theme = Theme.objects.create(
    name="Neighborhood Guide",
    # Map initial view
    map_initial_lat=37.7749,
    map_initial_lng=-122.4194,
    map_initial_zoom=13,
    map_style="streets",

    # Boundary styling
    map_boundary_fill_color="#FF6B6B",
    map_boundary_fill_opacity=0.2,
    map_boundary_line_color="#CC5555",
    map_boundary_line_weight=3,
    map_show_boundary=True,

    # Map features
    map_show_heat_map=True,
    map_cluster_markers=True,
    map_numbered_markers=True,
    map_show_featured_first=True,

    # Category colors
    map_category_colors={
        "restaurant": "#E74C3C",
        "cafe": "#F39C12",
        "bar": "#9B59B6",
        "shop": "#3498DB"
    },

    # Filters
    filters_tags_to_include=["verified", "local-favorite"],
    show_category_filters=True,
    show_vibe_filters=True
)

Example 4: Minimal Card Display Theme

theme = Theme.objects.create(
    name="Clean & Simple",
    # Layout
    initial_view="grid",
    grid_columns=4,
    card_style="list",

    # Show only essential card information
    show_title_on_cards=True,
    show_image_on_cards=True,
    show_category_on_cards=True,
    show_address_on_cards=False,
    show_description_on_cards=False,
    show_rating_on_cards=False,
    show_vibes_on_cards=False,
    show_tags_on_cards=False,

    # Hide items without images
    hide_no_image_items=True,

    # Subtitle configuration
    subtitle_source="category"
)

Example 5: Feature-Rich Interactive Map

theme = Theme.objects.create(
    name="Interactive City Guide",
    # Initial view starts on map
    initial_view="map",

    # Map configuration
    map_style="dark",
    map_initial_zoom=12,
    map_cooperative_gestures=True,
    map_scroll_zoom=True,

    # Marker configuration
    map_marker_style="images",
    map_num_image_markers=100,
    map_show_circle_markers=False,
    map_cluster_markers=True,
    map_show_popups=True,

    # Show all layers
    map_show_boundary=True,
    map_show_heat_map=True,
    map_show_transit=True,
    map_show_legend=True,

    # Rich card display
    show_title_on_cards=True,
    show_image_on_cards=True,
    show_category_on_cards=True,
    show_description_on_cards=True,
    show_address_on_cards=True,
    show_rating_on_cards=True,
    show_vibes_on_cards=True,
    show_hours_on_cards=True,
    show_website_on_cards=True,

    # Advanced filters
    show_filters_overall=True,
    show_tag_filters=True,
    show_category_filters=True,
    show_vibe_filters=True,
    show_neighborhood_filters=True,
    show_item_count_on_filters=True,
    filter_allow_multiple_selection=True,
    filter_view_mode="sidebar"
)

---

API Methods

get_theme_by_slug(slug)

Retrieve a theme by its URL-friendly slug.

theme = Theme.get_theme_by_slug('ocean-blue')

get_users_associated_with_theme(theme, max_users=10)

Get users associated with a specific theme (excludes 'vibemap' default theme).

users = Theme.get_users_associated_with_theme('community-events', max_users=20)

get_themes_by_user_email(email)

Get all themes accessible to a user by their email address.

themes = Theme.get_themes_by_user_email('user@example.com')

---

Best Practices

Color Consistency

• Use a consistent color palette across accent, secondary, and related fields
• Ensure sufficient contrast between color (text) and background
• Test colors for accessibility (WCAG AA compliance recommended)
• Use map_category_colors for immediate visual categorization on maps

Event Configuration

• When using event_form_link, the external form should post back to Vibemap's API
• event_form_required_fields should match your form validation logic
• Set event_form_requires_approval=True for moderated communities

Map Optimization

• Use map_boundary_fill_opacity between 0.1-0.3 for subtle highlighting
• Set map_clip_to_bounds=True to improve performance for city-specific themes
• Enable map_cluster_markers=True for themes with high marker density (100+ places)
• Use map_num_image_markers to balance visual appeal with performance (recommended: 50-100)
• Set map_cooperative_gestures=True for content-heavy pages to prevent accidental zooming
• Use map_fit_bounds=True and map_fit_markers=True for automatic optimal viewport

Card Display Optimization

• Minimize visible card fields for cleaner, faster-loading interfaces
• Use hide_no_image_items=True for visually-focused themes
• Set subtitle_source to the most relevant secondary information for your use case
• Use card_style="carousel" for mobile-optimized experiences
• Show only essential information on cards; detailed info can appear on detail pages

Filter Configuration

• Enable filter_allow_multiple_selection=True for power users and complex searches
• Use show_item_count_on_filters=True to improve UX (users can see available options)
• Set filter_view_mode="sidebar" for desktop-first experiences
• Set filter_view_mode="dropdown" for mobile-first or minimal interfaces
• Balance number of filter types shown (tags, categories, vibes) with interface simplicity

Tag Management

• filters_tags_to_exclude takes precedence over filters_tags_to_include
• Use filters_tag_names to provide user-friendly labels without changing database slugs
• Keep auto-applied tags (event_form_auto_tags) minimal and relevant

Layout & Performance

• Use grid_columns=2 for mobile-optimized themes
• Use grid_columns=3-4 for desktop-optimized themes
• Set shown_at_start based on expected dataset size (smaller for slower connections)
• Set initial_view="map" for location-focused experiences
• Set initial_view="grid" for browsing/discovery experiences

---

Migration Notes

When creating new themes, ensure:

1. Organization profiles link to the theme via foreign key
2. Icon images are optimized (recommended: SVG or PNG < 50KB)
3. External URLs (logo_url, font_url, event_form_link) are HTTPS
4. JSON fields validate as proper JSON arrays/objects
5. Color hex codes include the # prefix

---

Related Models

• OrganizationProfile (accounts/models/organization.py): Links users to themes
• User (accounts/models/user.py): Users can be associated with multiple themes
• Event (api/models/events.py): Events inherit theme-based filtering and display rules
• Place (api/models/places.py): Places displayed according to theme map configuration

---

Future Enhancements

Potential additions to the Theme model (not yet implemented):

• Custom CSS injection for advanced styling
• Theme inheritance/composition (base themes + overrides)
• A/B testing configurations per theme
• Mobile-specific theme overrides
• Accessibility presets (high contrast, large text, etc.)

---

Complete Field Name Reference

All theme configuration fields organized alphabetically for quick lookup:

A-C

• accent, background, button_text_color
• card_style, cards_open_to_blank, cards_open_to_page, cards_open_to_website, cards_title_color, cards_use_dynamic_link
• color, created_at

E-G

• event_form_auto_tags, event_form_city, event_form_header_color, event_form_link, event_form_message, event_form_required_fields, event_form_requires_approval, event_form_show_intro_message, event_form_show_vibe_points, event_form_title
• events_clip_to_bounds, events_event_layout, events_link, events_link_newsletter, events_open_in_new_tab, events_randomize_images, events_related_events, events_related_events_radius, events_search_placeholder, events_show_only_event_tags, events_tag_auto, events_vibes
• filter_allow_multiple_selection, filter_view_mode
• filters_tag_names, filters_tags_to_exclude, filters_tags_to_include
• font_url, foreground
• grid_columns

H-N

• hide_no_image_items
• icon, id, initial_view
• logo_url
• map_boundary_fill_color, map_boundary_fill_opacity, map_boundary_line_color, map_boundary_line_dash_array, map_boundary_line_opacity, map_boundary_line_weight, map_boundary_show_labels
• map_category_colors, map_clip_to_bounds, map_cluster_markers, map_cooperative_gestures
• map_fit_bounds, map_fit_markers
• map_height_offset
• map_initial_bearing, map_initial_lat, map_initial_lng, map_initial_pitch, map_initial_zoom
• map_marker_featured, map_marker_style
• map_num_image_markers, map_num_places_to_load, map_numbered_markers
• map_padding
• map_route_color
• map_scroll_zoom, map_should_include_tags, map_show_boundary, map_show_circle_markers, map_show_featured_first, map_show_heat_map, map_show_legend, map_show_map_cards, map_show_markers, map_show_popups, map_show_route, map_show_scroll_area, map_show_transit
• map_shuffle_markers, map_story_scroll, map_style
• map_title_cards
• map_zoom_max, map_zoom_min
• name, num_badge_size, num_bg_color, num_border_color, num_text_color, num_theme

S-Z

• secondary, show_bookmark_button
• show_address_on_cards, show_category_on_cards, show_description_on_cards, show_distance_on_cards, show_hours_on_cards, show_image_on_cards, show_notes_on_cards, show_offers_first, show_offers_on_cards, show_phone_on_cards, show_price_on_cards, show_rating_on_cards, show_tags_on_cards, show_title_on_cards, show_vibes_on_cards, show_website_on_cards
• show_category_filters, show_date_range_selector
• show_filters_overall, show_item_count_on_filters
• show_left_panel, show_login
• show_neighborhood_filters
• show_search_in_filters
• show_tag_filters, show_top_level_filters
• show_vibe_filters
• shown_at_start, slug, subtitle_source
• updated_at

Total: 100+ configuration fields

---

Support

For questions about theme configuration:

• Review this documentation
• Check existing themes in Django admin: /admin/accounts/theme/
• Refer to frontend implementation in the web application codebase
• Contact the development team for advanced customization requests