odac 0.9.0

package/docs/frontend/02-ajax-navigation/02-configuration.md

@@ -0,0 +1,370 @@
+# AJAX Navigation Configuration
+
+Learn how to configure and customize AJAX navigation in your CandyPack application.
+
+## Prerequisites
+
+Before configuring AJAX navigation, ensure your skeleton template is properly set up. See the [Quick Start guide](01-quick-start.md#skeleton-structure-required) for skeleton setup instructions.
+
+**Key requirements:**
+- Skeleton placeholders must be UPPERCASE and wrapped in HTML tags (e.g., `<main>{{ CONTENT }}</main>`)
+- Controller keys are lowercase (e.g., `content: 'home'`)
+- Frontend selectors target the HTML tags (e.g., `content: 'main'` targets `<main>` tag)
+
+**Mapping example:**
+- Skeleton: `<main>{{ CONTENT }}</main>`
+- Controller: `content: 'home'`
+- Frontend: `update: { content: 'main' }`
+
+## Configuration Options
+
+### Basic Configuration
+
+The simplest way to enable AJAX navigation:
+
+```javascript
+Candy.action({
+  navigate: 'main'  // Update <main> element
+})
+```
+
+### Full Configuration
+
+All available options:
+
+```javascript
+Candy.action({
+  navigate: {
+    // Which links to intercept
+    links: 'a[href^="/"]',  // Default: all internal links
+    
+    // Which elements to update
+    update: {
+      content: 'main',
+      header: 'header',
+      sidebar: '#sidebar'
+    },
+    
+    // Callback after navigation
+    on: function(page, variables) {
+      console.log('Navigated to:', page)
+      console.log('Server data:', variables)
+    }
+  }
+})
+```
+
+## Link Selectors
+
+### Default Behavior
+
+By default, all internal links (starting with `/`) are intercepted:
+
+```javascript
+navigate: true  // Uses 'a[href^="/"]'
+```
+
+### Custom Selectors
+
+Target specific links:
+
+```javascript
+navigate: {
+  links: 'nav a',  // Only navigation links
+  update: 'main'
+}
+```
+
+```javascript
+navigate: {
+  links: 'a.ajax-link',  // Only links with class
+  update: 'main'
+}
+```
+
+### Excluding Links
+
+Exclude specific links from AJAX navigation:
+
+```html
+<!-- Using data attribute -->
+<a href="/download.pdf" data-navigate="false">Download</a>
+
+<!-- Using CSS class -->
+<a href="/logout" class="no-navigate">Logout</a>
+```
+
+Both methods work automatically - no additional configuration needed!
+
+## Element Updates
+
+### Single Element
+
+Update one element:
+
+```javascript
+navigate: 'main'  // Shorthand
+// or
+navigate: {
+  update: 'main'
+}
+```
+
+### Multiple Elements
+
+Update multiple elements simultaneously:
+
+```javascript
+navigate: {
+  update: {
+    content: 'main',
+    header: 'header',
+    sidebar: '#sidebar',
+    breadcrumb: '.breadcrumb'
+  }
+}
+```
+
+The keys (content, header, etc.) must match the view parts defined in your controller:
+
+```javascript
+// In controller
+Candy.View.set({
+  header: 'main',
+  content: 'about',
+  sidebar: 'main'
+})
+```
+
+## Callbacks
+
+### Navigation Callback
+
+Execute code after each navigation:
+
+```javascript
+navigate: {
+  update: 'main',
+  on: function(page, variables) {
+    // page: current page name (e.g., 'about')
+    // variables: data from server
+    
+    // Update page title
+    document.title = variables.title || page
+    
+    // Track analytics
+    if (window.gtag) {
+      gtag('event', 'page_view', {
+        page_path: window.location.pathname
+      })
+    }
+    
+    // Update active navigation
+    updateActiveNav()
+  }
+}
+```
+
+### Page-Specific Actions
+
+Run code for specific pages:
+
+```javascript
+Candy.action({
+  navigate: {
+    update: 'main',
+    on: (page, vars) => console.log('Navigated to:', page)
+  },
+  
+  page: {
+    index: function(variables) {
+      console.log('Home page loaded')
+    },
+    about: function(variables) {
+      console.log('About page:', variables.title)
+    }
+  }
+})
+```
+
+## Disabling Navigation
+
+### Disable Completely
+
+```javascript
+Candy.action({
+  navigate: false  // No AJAX navigation
+})
+```
+
+### Disable for Specific Links
+
+```html
+<!-- Data attribute -->
+<a href="/download" data-navigate="false">Download</a>
+
+<!-- CSS class -->
+<a href="/logout" class="no-navigate">Logout</a>
+
+<!-- External links (automatic) -->
+<a href="https://example.com">External</a>
+```
+
+## Server-Side Configuration
+
+### Sending Variables
+
+In your controller, send data to the client:
+
+```javascript
+module.exports = function(Candy) {
+  // Set variables for AJAX responses
+  Candy.set({
+    title: 'About Page',
+    user: {name: 'John', role: 'admin'},
+    stats: {views: 1234}
+  }, true)  // true = include in AJAX
+  
+  Candy.View.skeleton('main')
+  Candy.View.set({
+    header: 'main',
+    content: 'about',
+    footer: 'main'
+  })
+}
+```
+
+### Accessing Variables
+
+Access server variables in your callback:
+
+```javascript
+navigate: {
+  update: 'main',
+  on: function(page, variables) {
+    console.log(variables.title)      // 'About Page'
+    console.log(variables.user.name)  // 'John'
+    console.log(variables.stats.views) // 1234
+  }
+}
+```
+
+## Advanced Examples
+
+### Loading Indicator
+
+Show a loading spinner during navigation:
+
+```javascript
+Candy.action({
+  navigate: {
+    update: 'main',
+    on: (page, vars) => {
+      hideLoadingSpinner()
+    }
+  },
+  
+  click: {
+    'a[href^="/"]': function(e) {
+      if (!this.hasAttribute('data-navigate') && 
+          !this.classList.contains('no-navigate')) {
+        showLoadingSpinner()
+      }
+    }
+  }
+})
+
+function showLoadingSpinner() {
+  document.getElementById('spinner').style.display = 'block'
+}
+
+function hideLoadingSpinner() {
+  document.getElementById('spinner').style.display = 'none'
+}
+```
+
+### Progress Bar
+
+Animated progress bar:
+
+```javascript
+let progressBar = document.getElementById('progress')
+
+Candy.action({
+  navigate: {
+    update: 'main',
+    on: () => {
+      progressBar.style.width = '100%'
+      setTimeout(() => {
+        progressBar.style.width = '0%'
+      }, 300)
+    }
+  },
+  
+  click: {
+    'a[href^="/"]': function() {
+      if (!this.hasAttribute('data-navigate')) {
+        progressBar.style.width = '30%'
+      }
+    }
+  }
+})
+```
+
+### Conditional Navigation
+
+Confirm before navigating:
+
+```javascript
+Candy.action({
+  navigate: {
+    update: 'main'
+  },
+  
+  click: {
+    'a[href^="/"]': function(e) {
+      if (hasUnsavedChanges() && 
+          !this.hasAttribute('data-navigate')) {
+        if (!confirm('You have unsaved changes. Continue?')) {
+          e.preventDefault()
+          e.stopPropagation()
+        }
+      }
+    }
+  }
+})
+```
+
+## Best Practices
+
+1. **Keep it Simple**: Start with minimal configuration
+2. **Progressive Enhancement**: Ensure links work without JavaScript
+3. **Loading States**: Always show loading indicators
+4. **Error Handling**: Handle failed requests gracefully
+5. **SEO**: Ensure content is accessible to search engines
+6. **Performance**: Only update necessary elements
+
+## Troubleshooting
+
+### Links Not Working
+
+- Check that `navigate` is enabled
+- Verify link selector matches your links
+- Check browser console for errors
+
+### Elements Not Updating
+
+- Ensure element selectors are correct
+- Verify view parts are defined in controller
+- Check that skeleton has correct placeholders
+
+### Variables Not Available
+
+- Confirm `Candy.set(data, true)` has `true` parameter
+- Check variables are set before `View.print()`
+
+## Next Steps
+
+- Learn about [Form Handling](../03-forms/01-form-handling.md)
+- Explore [API Requests](../04-api-requests/01-get-post.md)
+- Check [Advanced Usage](03-advanced-usage.md)