go_blog/.claude/plans/nav_links_management.md

Navigation Links Management - Implementation Plan

Overview

Add a navigation links management feature that allows admins to configure custom links in the header navigation, with support for controlling whether links open in new windows.

Requirements Analysis

Based on exploration:

• User wants to add additional URLs next to "Home" in the header navigation
• Backend admin interface to manage these URLs
• Control over whether links open in new windows (target="_blank")
• The site uses a multi-language system (zh/en)

Current Architecture Patterns

Database Models

• Models are in /models/ directory
• Settings tables follow singleton pattern (ID=1) like SiteSetting, CommentConfig
• Support for multi-language via *Zh and *En fields
• Use GORM with auto-migration in models/db.go
• Config cache system exists (models/config_cache.go, models.LoadConfigCache(), models.RefreshConfigCache())

Handlers

• Settings handlers in handlers/settings.go
• Pattern: {Feature}SettingsPage() for GET, {Feature}SettingsSave() for POST
• Uses DefaultData(c) helper for common template data
• Multi-action POST pattern with action form field (see upload/download settings)
• Session-based user ID tracking via userIDFromSession()

Templates

• Admin templates in templates/admin/
• Settings pages follow consistent UI pattern (tabs, success messages)
• Header navigation in templates/layouts/base.html (lines 24-89)
• Current navigation shows: Logo/Title, Home link, Login/User dropdown

Routing

• Admin routes under /admin group with auth + admin middleware
• Settings routes: /admin/settings/site, /admin/settings/upload, etc.

i18n

• Translation keys in i18n/i18n.go
• Follows pattern: "feature_field_lang" or "feature_action"
• Both EN and ZH translations required

Proposed Implementation

1. Database Model: NavLink

Create models/nav_link.go:

type NavLink struct {
    ID        uint      `gorm:"primarykey"`
    TitleZh   string    `gorm:"size:100;not null"`     // Link text (Chinese)
    TitleEn   string    `gorm:"size:100;not null"`     // Link text (English)
    URL       string    `gorm:"size:512;not null"`     // Target URL
    OpenNew   bool      `gorm:"default:false"`         // Open in new window
    Enabled   bool      `gorm:"default:true"`          // Show/hide link
    Sort      int       `gorm:"default:0;index"`       // Display order
    CreatedAt time.Time
    UpdatedAt time.Time
    UpdatedBy uint      `gorm:"index"`
}

// Helper methods
func (n *NavLink) Title(lang string) string {
    // Return title for language with fallback
}

2. Database Migration

Add to models/db.go AutoMigrate():

• Add &NavLink{} to the migration list

3. Config Cache Integration

Update models/config_cache.go:

• Add NavLinks []NavLink field to cache struct
• Load nav links in LoadConfigCache()
• Make available to all handlers via middleware

4. Backend Handler

Add to handlers/settings.go:

// NavLinksSettingsPage - render nav links management page
func NavLinksSettingsPage(db *gorm.DB) gin.HandlerFunc

// NavLinksSettingsSave - handle actions: add, toggle, delete, reorder
func NavLinksSettingsSave(db *gorm.DB) gin.HandlerFunc

// Helper functions:
// - addNavLink()
// - toggleNavLink()
// - deleteNavLink()
// - reorderNavLink()

Actions via POST form field:

• action=add - create new link
• action=toggle - enable/disable link
• action=delete - remove link
• action=edit - update link details

5. Admin Template

Create templates/admin/settings_navlinks.html:

• Settings page with tab navigation matching existing pattern
• Form to add new links (Title ZH/EN, URL, Open in new window checkbox)
• List of existing links with:
  • Enable/disable toggle
  • Edit inline or modal
  • Delete button
  • Sort order controls (up/down arrows or drag)
• Success message display
• Consistent styling with other settings pages

6. Frontend Template Updates

Update templates/layouts/base.html:

• Modify navigation section (around line 36-42) to render nav links
• Loop through cached nav links after "Home" link
• Apply language-specific titles
• Add target="_blank" when OpenNew is true
• Maintain consistent styling with existing nav items

7. Routing

Add to main.go settings group (around line 110-121):

settings.GET("/navlinks", handlers.NavLinksSettingsPage(db))
settings.POST("/navlinks", handlers.NavLinksSettingsSave(db))

8. i18n Translations

Add to i18n/i18n.go for both EN and ZH:

"settings_navlinks_title": "Navigation Links"
"settings_navlinks_desc": "Manage custom links in the header navigation"
"navlinks_add": "Add Link"
"navlinks_title_zh": "Link Text (Chinese)"
"navlinks_title_en": "Link Text (English)"
"navlinks_url": "URL"
"navlinks_open_new": "Open in new window"
"navlinks_enabled": "Enabled"
"navlinks_edit": "Edit"
"navlinks_delete": "Delete"
"navlinks_confirm_delete": "Are you sure you want to delete this link?"
"navlinks_no_links": "No navigation links configured yet."

Implementation Order

1. Create database model (models/nav_link.go)
2. Update database migration (models/db.go)
3. Update config cache (models/config_cache.go)
4. Add i18n translations (i18n/i18n.go)
5. Create backend handlers (handlers/settings.go)
6. Create admin template (templates/admin/settings_navlinks.html)
7. Update frontend header (templates/layouts/base.html)
8. Add routes (main.go)
9. Test the feature

Design Decisions

Why not singleton table?

• Multiple nav links needed (vs single config)
• Better suited for a regular table with multiple rows
• Easier to add/remove/reorder individual links

Sort order implementation

• Use integer Sort field
• Lower numbers appear first
• Admin can adjust via up/down buttons or explicit number input

Cache integration

• Nav links loaded into cache at startup and on refresh
• Avoids DB query on every page load
• Consistent with existing upload/comment config pattern

Open in new window

• Boolean field OpenNew
• Renders as target="_blank" rel="noopener noreferrer" when true
• Security: always include rel="noopener noreferrer" with target="_blank"

Testing Checklist

• Create new nav link via admin
• Nav link appears in header navigation
• Correct language displayed based on user preference
• "Open in new window" works correctly
• Enable/disable toggle works
• Delete link works
• Sort order affects display order
• Links render correctly for logged-in and anonymous users
• Multiple links display properly
• External and internal URLs both work
• Mobile responsive layout maintained