Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
753 lines (522 loc) · 16.8 KB

GETTING_STARTED.md

File metadata and controls

753 lines (522 loc) · 16.8 KB

Getting Started Guide

Welcome! This guide will help you navigate the NavigationSplitView examples and choose the right learning path.

🎯 Quick Start (5 minutes)

  1. Open the project:

    open /path/to/SwiftUIExamples/SwiftUIExamples.xcodeproj

  2. Run the app (Cmd+R in Xcode)

  3. Try all four examples:

    • Click "Views Only" - Simplest pattern
    • Click "MVVM Pattern" - Production-ready pattern
    • Click "MVVM-C Pattern" - Navigation separation pattern
    • Click "VIPER Pattern" - Maximum separation

  4. Explore the 3-pane layout:

    • Select categories in the sidebar
    • Browse items in the content list
    • View details in the detail pane
    • Try the Settings category

📚 Documentation Map

Start Here

New to SwiftUI? → Start with ViewOnly_Architecture.md

Familiar with SwiftUI basics? → Jump to MVVM_Architecture.md

Need navigation separation? → Check out MVVMC_Architecture.md

Want maximum separation? → Check out VIPER_Architecture.md

Want the big picture? → Read README.md first

Need implementation details? → Check IMPLEMENTATION_SUMMARY.md

🗺️ Learning Paths

Path 1: Complete Beginner

graph LR
    A[README.md] --> B[ViewOnly_Architecture.md]
    B --> C[Run ViewOnly Example]
    C --> D[Read ViewOnly Code]
    D --> E[MVVM_Architecture.md]
    E --> F[Run MVVM Example]
    F --> G[Compare Implementations]

    style A fill:#e8f5e9
    style B fill:#fff4e1
    style C fill:#e1f5ff
    style D fill:#fff4e1
    style E fill:#f3e5f5
    style F fill:#e1f5ff
    style G fill:#fff4e1
Loading

Estimated Time: 2-3 hours

Steps:

  1. Read README.md (10 min)

    • Understand what both patterns offer
    • See the high-level comparison

  2. Read ViewOnly_Architecture.md (30 min)

    • Learn SwiftUI state management basics
    • Understand @State and @Binding
    • Study the architecture diagrams

  3. Run ViewOnly Example (15 min)

    • Open in Xcode and run
    • Interact with all features
    • Try adding/editing items

  4. Read ViewOnly Code (45 min)

    • Start with NavigationSplitViewViewOnlyContentView.swift
    • Follow the inline comments
    • Understand data flow with @Binding

  5. Read MVVM_Architecture.md (45 min)

    • Learn separation of concerns
    • Understand @Observable macro
    • Study ViewModel patterns

  6. Run MVVM Example (15 min)

    • See the same UI, different architecture
    • Try all features

  7. Compare Implementations (30 min)

    • Open files side-by-side
    • Compare state management approaches
    • Read DATA_FLOW_EXPLANATION.md

Path 2: SwiftUI Developer (Learning MVVM)

graph LR
    A[README.md] --> B[MVVM_Architecture.md]
    B --> C[Review @Observable]
    C --> D[Study ViewModels]
    D --> E[Compare with ViewOnly]
    E --> F[Build Your Own]

    style A fill:#e8f5e9
    style B fill:#f3e5f5
    style C fill:#e1f5ff
    style D fill:#fff4e1
    style E fill:#e1f5ff
    style F fill:#a5d6a7
Loading

Estimated Time: 1-2 hours

Steps:

  1. Skim README.md (5 min)

    • Get project overview

  2. Read MVVM_Architecture.md (40 min)

    • Focus on @Observable section
    • Study the architecture diagrams
    • Understand ViewModel responsibilities

  3. Study MVVMAppViewModel.swift (20 min)

    • See how central coordinator works
    • Understand property observation

  4. Compare ContentListViewModel with ViewOnly (20 min)

    • Open both implementations side-by-side
    • See how business logic moves to ViewModel
    • Compare state management

  5. Read DATA_FLOW_EXPLANATION.md (15 min)

    • Understand data flow differences

  6. Build Your Own (flexible)

    • Use MVVM example as template
    • Apply pattern to your project

Path 3: Experienced Developer (Quick Reference)

graph LR
    A[IMPLEMENTATION_SUMMARY.md] --> B[MVVM ViewModels]
    B --> C[Architecture Diagrams]
    C --> D[Apply Patterns]

    style A fill:#f3e5f5
    style B fill:#e1f5ff
    style C fill:#fff4e1
    style D fill:#a5d6a7
Loading

Estimated Time: 30-45 minutes

Steps:

  1. Read IMPLEMENTATION_SUMMARY.md (15 min)

    • Get complete overview
    • See architecture comparison
    • Review key technologies

  2. Study MVVM ViewModels (15 min)

    • MVVMAppViewModel.swift - Coordinator pattern
    • MVVMContentListViewModel.swift - CRUD operations
    • MVVMSidebarViewModel.swift - Navigation state

  3. Review Architecture Diagrams (10 min)

    • Mermaid diagrams in MVVM_Architecture.md
    • Data flow visualizations

  4. Apply to Your Project (flexible)

    • Copy patterns that fit your needs
    • Adapt ViewModels for your domain

Path 4: Advanced Developer (Learning VIPER)

graph LR
    A[VIPER_Architecture.md] --> B[Understand 5 Components]
    B --> C[Study Router]
    C --> D[Study Interactors]
    D --> E[Study Presenters]
    E --> F[Compare with MVVM]

    style A fill:#ffe0b2
    style B fill:#fff4e1
    style C fill:#e1f5ff
    style D fill:#f3e5f5
    style E fill:#e1f5ff
    style F fill:#a5d6a7
Loading

Estimated Time: 2-3 hours

Steps:

  1. Read VIPER_Architecture.md (60 min)

    • Understand all 5 components (V-I-P-E-R)
    • Study the architecture diagram
    • Learn when to use VIPER vs. MVVM

  2. Study the Router (20 min)

    • Read VIPERRouter.swift
    • See how it creates and wires modules
    • Understand navigation state management

  3. Study Interactors (30 min)

    • Read VIPERContentListInteractor.swift
    • See pure business logic separation
    • Compare with ViewModel business logic

  4. Study Presenters (30 min)

    • Read VIPERContentListPresenter.swift
    • See how it formats data from Interactor
    • Understand delegation to Router

  5. Run VIPER Example (15 min)

    • Same UI as MVVM, different architecture
    • Try all features

  6. Compare VIPER with MVVM (30 min)

    • Open files side-by-side
    • See business logic separation (Interactor vs. ViewModel)
    • Compare navigation (Router vs. ViewModel)
    • Understand complexity trade-offs

🔍 What to Look For

In ViewOnly Implementation

Key Concepts:

  • @State for local view state
  • @Binding for shared state between views
  • State lives in view hierarchy
  • Simple and direct

Files to Study:

Examples/ViewOnly/
├── NavigationSplitViewViewOnlyContentView.swift  ← Start here
├── NavigationSplitViewViewOnlySidebarView.swift  ← See @Binding usage
└── NavigationSplitViewViewOnlyContentListView.swift  ← Study state management

In MVVM Implementation

Key Concepts:

  • @Observable for automatic state tracking
  • ViewModels contain business logic
  • Views are thin UI layers
  • Testable and maintainable

Files to Study:

Examples/MVVM/
├── ViewModels/
│   ├── MVVMAppViewModel.swift              ← Start here (coordinator)
│   ├── MVVMContentListViewModel.swift      ← CRUD operations
│   └── MVVMSidebarViewModel.swift          ← Navigation state
└── Views/
    └── MVVMContentView.swift               ← See how Views use ViewModels

In VIPER Implementation

Key Concepts:

  • Five separate components (V-I-P-E-R)
  • Maximum separation of concerns
  • Router creates and wires modules
  • Interactor has ONLY business logic
  • Presenter has ONLY presentation logic
  • Most testable but most complex

Files to Study:

Examples/VIPER/
├── Router/
│   └── VIPERRouter.swift                   ← Start here (module coordinator)
├── Interactors/
│   ├── VIPERContentListInteractor.swift    ← Business logic
│   └── VIPERSidebarInteractor.swift
├── Presenters/
│   ├── VIPERContentListPresenter.swift     ← Presentation logic
│   └── VIPERSidebarPresenter.swift
├── Entities/
│   ├── VIPERListItem.swift                 ← Pure data models
│   └── VIPERSidebarCategory.swift
└── Views/
    └── VIPERContentView.swift              ← Dumb views

🎓 Concepts Explained

Understanding @State

// `@State` creates a source of truth owned by the view
@State private var items: [Item] = []

// SwiftUI automatically updates UI when this changes
items.append(newItem)  // UI updates!

When to use:

  • View needs to own and manage data
  • Data doesn't need to be shared with other views
  • Simple state management

Understanding @Binding

// `@Binding` creates a two-way connection to someone else's state
@Binding var selectedItem: Item?

// Changes flow both ways:
selectedItem = newItem      // Parent sees change
// Parent changes also update this view

When to use:

  • Sharing state between parent and child views
  • Child needs to read AND write parent's data
  • Simple data passing

Understanding @Observable

// `@Observable` makes a class trackable by SwiftUI
@Observable
class AppViewModel {
    var items: [Item] = []
    var selectedItem: Item?

    // All properties automatically tracked!
}

// In views:
@State private var viewModel = AppViewModel()
// SwiftUI updates view when ANY property changes

When to use:

  • Separating business logic from views
  • Managing complex state
  • Building testable code
  • Production applications

💡 Common Questions

Q: Which pattern should I use?

Use ViewOnly if:

  • Learning SwiftUI for the first time
  • Building a small, simple app
  • Prototyping quickly
  • You don't need automated testing

Use MVVM if:

  • Building a production application
  • Working in a team
  • Need unit testing
  • App will grow over time
  • Want clear separation of concerns

Use VIPER if:

  • Building a large, complex application
  • Large team (5+ developers)
  • Maximum testability required
  • Complex business logic
  • Multiple modules/features
  • Long-term maintenance (years)

Quick Decision Guide:

Simple app (< 10 screens)?          → ViewOnly
Moderate app (10-50 screens)?       → MVVM
Large app (50+ screens)?            → VIPER
Learning SwiftUI?                   → ViewOnly
Production app with testing?        → MVVM
Enterprise app with large team?     → VIPER

Q: Can I mix patterns?

Short answer: Not recommended within the same feature.

Better approach:

  • Keep patterns separate by feature/module
  • Choose one pattern for your project
  • Use ViewOnly for learning, MVVM for production

Q: What's the difference between @State and @Observable?

Aspect @State @Observable
Scope Single view Multiple views
Ownership View owns data ViewModel owns data
Logic Location In view In ViewModel
Testability Hard to test Easy to test
Best For Simple UI state Business logic

Q: Do I need to know Combine?

No! The @Observable macro (iOS 17+) replaces the need for Combine in most cases.

Old way (Combine):

class ViewModel: ObservableObject {
    @Published var items: [Item] = []  // Needs Combine
}

New way (@Observable):

@Observable
class ViewModel {
    var items: [Item] = []  // No Combine needed!
}

Q: Why separate Models, ViewModels, and Views?

Benefits:

  1. Testability

    • Test ViewModels without UI
    • Mock data with Models
    • Verify business logic independently

  2. Maintainability

    • Change UI without touching logic
    • Update logic without breaking UI
    • Clear responsibilities

  3. Reusability

    • Share ViewModels across platforms
    • Reuse Models in different contexts
    • Compose Views freely

  4. Collaboration

    • Team members work on different layers
    • Less merge conflicts
    • Clear ownership

🛠️ Hands-On Exercises

Exercise 1: Modify ViewOnly (Easy)

Goal: Add a new category

Steps:

  1. Open NavigationSplitViewViewOnlySidebarCategory.swift
  2. Add a new case to the enum: .shopping
  3. Update the switch statement in defaultContent
  4. Run and see your new category!

Time: 15 minutes

Exercise 2: Modify MVVM (Medium)

Goal: Add a priority field to items

Steps:

  1. Update MVVMListItem.swift - add priority: String property
  2. Update MVVMContentListViewModel.swift - include priority in new items
  3. Update MVVMDetailView.swift - display priority
  4. Update MVVMInfoRow.swift - add priority field
  5. Run and test!

Time: 30 minutes

Exercise 3: Compare Patterns (Advanced)

Goal: Understand architectural differences

Steps:

  1. Implement same feature in both patterns:

    • Add "favorite" flag to items
    • Filter to show only favorites

  2. Compare:

    • Where does state live?
    • Where is logic implemented?
    • How many files did you touch?
    • Which was easier to test?

  3. Write notes on differences

Time: 1-2 hours

🔗 Quick Links

Documentation

Key Code Files

Entry Points:

  • TestyApp.swift - App setup
  • ImplementationSelectionView.swift - Example selector

ViewOnly:

  • NavigationSplitViewViewOnlyContentView.swift - Main view

MVVM:

  • MVVMContentView.swift - Main view
  • MVVMAppViewModel.swift - Central coordinator

🎯 Success Checklist

After completing your chosen learning path, you should be able to:

ViewOnly Pattern:

  • Explain what @State does
  • Use @Binding to share state
  • Create a 3-pane NavigationSplitView
  • Manage state within views
  • Handle user input with property wrappers

MVVM Pattern:

  • Explain what @Observable does
  • Create ViewModels with business logic
  • Separate concerns (Model/ViewModel/View)
  • Use ViewModels from Views
  • Design testable architecture

Both Patterns:

  • Build NavigationSplitView layouts
  • Support different content types
  • Handle multi-window on macOS
  • Understand data flow
  • Make informed architecture decisions

🚀 Next Steps

After Learning ViewOnly

  1. Read MVVM documentation
  2. Compare implementations side-by-side
  3. Build a small MVVM project
  4. Practice unit testing ViewModels

After Learning MVVM

  1. Apply to your own project
  2. Explore advanced patterns:
    • Repository pattern for data
    • Dependency injection
    • Coordinator pattern for navigation
  3. Build a complete app

Keep Learning

  • Apple's SwiftUI Tutorials: developer.apple.com/tutorials/swiftui
  • Swift by Sundell: swiftbysundell.com
  • Hacking with Swift: hackingwithswift.com
  • WWDC Videos: Search "SwiftUI" on developer.apple.com

💬 Need Help?

Understanding Issues

  1. Read inline code comments - Every file has detailed explanations
  2. Check architecture diagrams - Visual guides in documentation
  3. Compare patterns - See differences side-by-side
  4. Build and experiment - Change code and see what happens

Common Pitfalls

Pitfall 1: Mixing @State and @Observable

// ❌ Don't do this
@State var viewModel: MVVMAppViewModel  // Wrong wrapper!

// ✅ Do this
@State private var viewModel = MVVMAppViewModel()  // Correct!

Pitfall 2: Forgetting @Observable

// ❌ Without @Observable, views won't update
class ViewModel {
    var items: [Item] = []
}

// ✅ With @Observable, automatic tracking
@Observable
class ViewModel {
    var items: [Item] = []
}

Pitfall 3: Putting Logic in Views (MVVM)

// ❌ Logic in View
struct MyView: View {
    func calculateTotal() -> Double { ... }  // Wrong place!
}

// ✅ Logic in ViewModel
@Observable
class MyViewModel {
    func calculateTotal() -> Double { ... }  // Correct!
}

📊 Time Estimates

Task Time
Quick Start 5 minutes
Complete Beginner Path 2-3 hours
SwiftUI Developer Path 1-2 hours
Experienced Developer Path 30-45 minutes
Exercise 1 (Easy) 15 minutes
Exercise 2 (Medium) 30 minutes
Exercise 3 (Advanced) 1-2 hours

✨ Have Fun Learning

Remember:

  • Start simple - ViewOnly first if you're new
  • Experiment - Change code and see what happens
  • Read comments - Every file has explanations
  • Build things - Best way to learn
  • Compare patterns - See differences yourself

Happy coding! 🎉

Last Updated: 2025
Swift Version: 5.9+
Minimum iOS: 17.0
Minimum macOS: 14.0