odac 0.9.0

package/docs/backend/07-views/05-conditionals.md

@@ -0,0 +1,290 @@
+## 🔀 Conditional Rendering
+
+Conditionals allow you to show or hide content based on conditions. This is essential for dynamic user interfaces.
+
+### Basic If Statement
+
+```html
+<candy:if condition="user.isAdmin">
+  <p>Welcome to the admin panel!</p>
+</candy:if>
+```
+
+The content inside the tag is only rendered if the condition is true.
+
+### If-Else Structure
+
+```html
+<candy:if condition="user.isLoggedIn">
+  <p>Welcome back, <candy var="user.name" />!</p>
+<candy:else>
+  <p>Please log in to continue.</p>
+</candy:if>
+```
+
+### If-ElseIf-Else Structure
+
+```html
+<candy:if condition="user.role === 'admin'">
+  <div class="admin-panel">
+    <p>You have full admin privileges</p>
+  </div>
+<candy:elseif condition="user.role === 'moderator'">
+  <div class="moderator-panel">
+    <p>You have moderator privileges</p>
+  </div>
+<candy:elseif condition="user.role === 'editor'">
+  <div class="editor-panel">
+    <p>You have editor privileges</p>
+  </div>
+<candy:else>
+  <div class="user-panel">
+    <p>You have regular user privileges</p>
+  </div>
+</candy:if>
+```
+
+### Condition Syntax
+
+Conditions use standard JavaScript expressions:
+
+```html
+<!-- Equality -->
+<candy:if condition="status === 'active'">Active</candy:if>
+
+<!-- Comparison -->
+<candy:if condition="age >= 18">Adult</candy:if>
+<candy:if condition="price < 100">Affordable</candy:if>
+
+<!-- Logical operators -->
+<candy:if condition="user.isVerified && user.isPremium">
+  Premium Verified User
+</candy:if>
+
+<candy:if condition="role === 'admin' || role === 'moderator'">
+  Staff Member
+</candy:if>
+
+<!-- Negation -->
+<candy:if condition="!user.isBanned">
+  Welcome!
+</candy:if>
+
+<!-- Existence check -->
+<candy:if condition="user">
+  User exists
+</candy:if>
+
+<!-- Array/String length -->
+<candy:if condition="items.length > 0">
+  You have items
+</candy:if>
+
+<!-- Method calls -->
+<candy:if condition="Candy.Auth.check()">
+  Logged in
+</candy:if>
+```
+
+### Practical Examples
+
+#### User Authentication Status
+
+```html
+<nav>
+  <candy:if condition="Candy.Auth.check()">
+    <a href="/profile">Profile</a>
+    <a href="/settings">Settings</a>
+    <a href="/logout">Logout</a>
+  <candy:else>
+    <a href="/login">Login</a>
+    <a href="/register">Register</a>
+  </candy:if>
+</nav>
+```
+
+#### Product Stock Status
+
+```html
+<div class="product">
+  <h3><candy var="product.name" /></h3>
+  <p class="price">$<candy var="product.price" /></p>
+  
+  <candy:if condition="product.stock > 10">
+    <span class="badge in-stock">In Stock</span>
+    <button>Add to Cart</button>
+  <candy:elseif condition="product.stock > 0">
+    <span class="badge low-stock">Only <candy var="product.stock" /> left!</span>
+    <button>Add to Cart</button>
+  <candy:else>
+    <span class="badge out-of-stock">Out of Stock</span>
+    <button disabled>Notify Me</button>
+  </candy:if>
+</div>
+```
+
+#### User Role-Based Content
+
+```html
+<div class="dashboard">
+  <h1>Dashboard</h1>
+  
+  <candy:if condition="user.role === 'admin'">
+    <div class="admin-section">
+      <h2>Admin Tools</h2>
+      <a href="/admin/users">Manage Users</a>
+      <a href="/admin/settings">System Settings</a>
+      <a href="/admin/logs">View Logs</a>
+    </div>
+  </candy:if>
+  
+  <candy:if condition="user.role === 'admin' || user.role === 'moderator'">
+    <div class="moderation-section">
+      <h2>Moderation</h2>
+      <a href="/moderate/posts">Review Posts</a>
+      <a href="/moderate/reports">Handle Reports</a>
+    </div>
+  </candy:if>
+  
+  <div class="user-section">
+    <h2>Your Content</h2>
+    <a href="/my-posts">My Posts</a>
+    <a href="/my-profile">My Profile</a>
+  </div>
+</div>
+```
+
+#### Form Validation Messages
+
+```html
+<form>
+  <div class="form-group">
+    <label>Email</label>
+    <input type="email" name="email" value="<candy var="email" />">
+    
+    <candy:if condition="errors && errors.email">
+      <span class="error"><candy var="errors.email" /></span>
+    </candy:if>
+  </div>
+  
+  <div class="form-group">
+    <label>Password</label>
+    <input type="password" name="password">
+    
+    <candy:if condition="errors && errors.password">
+      <span class="error"><candy var="errors.password" /></span>
+    </candy:if>
+  </div>
+  
+  <candy:if condition="success">
+    <div class="success-message">
+      <candy var="success" />
+    </div>
+  </candy:if>
+  
+  <button type="submit">Submit</button>
+</form>
+```
+
+#### Conditional CSS Classes
+
+```html
+<div class="user-card <candy:if condition="user.isPremium">premium</candy:if> <candy:if condition="user.isVerified">verified</candy:if>">
+  <h3><candy var="user.name" /></h3>
+  
+  <candy:if condition="user.isPremium">
+    <span class="badge">⭐ Premium</span>
+  </candy:if>
+  
+  <candy:if condition="user.isVerified">
+    <span class="badge">✓ Verified</span>
+  </candy:if>
+</div>
+```
+
+#### Nested Conditions
+
+```html
+<candy:if condition="user">
+  <candy:if condition="user.isActive">
+    <candy:if condition="user.subscription">
+      <candy:if condition="user.subscription.status === 'active'">
+        <div class="premium-content">
+          <h2>Premium Content</h2>
+          <p>Welcome, premium member!</p>
+        </div>
+      <candy:elseif condition="user.subscription.status === 'expired'">
+        <div class="renewal-notice">
+          <p>Your subscription has expired. Please renew to continue.</p>
+          <a href="/renew">Renew Now</a>
+        </div>
+      </candy:if>
+    <candy:else>
+      <div class="upgrade-notice">
+        <p>Upgrade to premium for exclusive content!</p>
+        <a href="/upgrade">Upgrade Now</a>
+      </div>
+    </candy:if>
+  <candy:else>
+    <div class="inactive-notice">
+      <p>Your account is inactive. Please contact support.</p>
+    </div>
+  </candy:if>
+<candy:else>
+  <div class="login-notice">
+    <p>Please log in to view this content.</p>
+    <a href="/login">Login</a>
+  </div>
+</candy:if>
+```
+
+#### Conditional Attributes
+
+```html
+<!-- Disabled button -->
+<button <candy:if condition="!canSubmit">disabled</candy:if>>
+  Submit
+</button>
+
+<!-- Selected option -->
+<select name="country">
+  <option value="tr" <candy:if condition="country === 'tr'">selected</candy:if>>Turkey</option>
+  <option value="us" <candy:if condition="country === 'us'">selected</candy:if>>USA</option>
+  <option value="uk" <candy:if condition="country === 'uk'">selected</candy:if>>UK</option>
+</select>
+
+<!-- Checked checkbox -->
+<input 
+  type="checkbox" 
+  name="terms" 
+  <candy:if condition="termsAccepted">checked</candy:if>
+>
+```
+
+### Best Practices
+
+1. **Keep conditions simple**: Complex logic should be in the controller
+2. **Use meaningful variable names**: Make conditions self-documenting
+3. **Avoid deep nesting**: Refactor complex nested conditions
+4. **Handle null/undefined**: Always check if objects exist before accessing properties
+
+**Good:**
+```javascript
+// Controller
+Candy.set('canEdit', user.isAdmin || user.id === post.authorId)
+```
+
+```html
+<!-- View -->
+<candy:if condition="canEdit">
+  <button>Edit</button>
+</candy:if>
+```
+
+**Avoid:**
+```html
+<!-- Too complex for a view -->
+<candy:if condition="(user && user.role === 'admin') || (user && post && user.id === post.authorId && !post.isLocked)">
+  <button>Edit</button>
+</candy:if>
+```

package/docs/backend/07-views/06-loops.md

@@ -0,0 +1,353 @@
+## 🔁 Loops and Iteration
+
+Loops allow you to repeat content for each item in an array or object. This is essential for displaying lists, tables, and collections.
+
+### For Loop
+
+The most common way to iterate over arrays and objects:
+
+```html
+<candy:for in="users" key="index" value="user">
+  <div class="user-card">
+    <h3><candy var="user.name" /></h3>
+    <p><candy var="user.email" /></p>
+  </div>
+</candy:for>
+```
+
+**Parameters:**
+- `in`: The array or object to loop through (required)
+- `key`: Variable name for the index/key (optional, default: "key")
+- `value`: Variable name for the value (optional, default: "value")
+
+### Iterating Over Arrays
+
+```javascript
+// Controller
+Candy.set('products', [
+  { name: 'Laptop', price: 999 },
+  { name: 'Mouse', price: 29 },
+  { name: 'Keyboard', price: 79 }
+])
+```
+
+```html
+<!-- View -->
+<div class="products">
+  <candy:for in="products" key="index" value="product">
+    <div class="product">
+      <span class="number"><candy var="index + 1" />.</span>
+      <h3><candy var="product.name" /></h3>
+      <p>$<candy var="product.price" /></p>
+    </div>
+  </candy:for>
+</div>
+```
+
+### Iterating Over Objects
+
+```javascript
+// Controller
+Candy.set('settings', {
+  theme: 'dark',
+  language: 'en',
+  notifications: true
+})
+```
+
+```html
+<!-- View -->
+<table>
+  <candy:for in="settings" key="settingKey" value="settingValue">
+    <tr>
+      <td><candy var="settingKey" /></td>
+      <td><candy var="settingValue" /></td>
+    </tr>
+  </candy:for>
+</table>
+```
+
+### While Loop
+
+Use while loops for conditional iteration:
+
+```html
+<script:candy>
+  let counter = 0;
+</script:candy>
+
+<candy:while condition="counter < 5">
+  <p>Item <candy var="counter + 1" /></p>
+  <script:candy>counter++;</script:candy>
+</candy:while>
+```
+
+**Note:** Be careful with while loops to avoid infinite loops. The condition must eventually become false.
+
+### Loop Control Statements
+
+#### Break
+
+Exit the loop early:
+
+```html
+<candy:for in="products" value="product">
+  <candy:if condition="product.stock === 0">
+    <p class="notice">Some products are out of stock</p>
+    <candy:break />
+  </candy:if>
+  <div><candy var="product.name" /></div>
+</candy:for>
+```
+
+#### Continue
+
+Skip to the next iteration:
+
+```html
+<candy:for in="users" value="user">
+  <candy:if condition="user.isBlocked">
+    <candy:continue />
+  </candy:if>
+  
+  <div class="user">
+    <h3><candy var="user.name" /></h3>
+    <p><candy var="user.email" /></p>
+  </div>
+</candy:for>
+```
+
+### Practical Examples
+
+#### Product List with Numbering
+
+```html
+<div class="product-list">
+  <h2>Our Products</h2>
+  
+  <candy:for in="products" key="i" value="product">
+    <div class="product-item">
+      <span class="number">#<candy var="i + 1" /></span>
+      <img src="<candy var="product.image" />" alt="<candy var="product.name" />">
+      <h3><candy var="product.name" /></h3>
+      <p class="price">$<candy var="product.price" /></p>
+      
+      <candy:if condition="product.discount">
+        <span class="discount">-<candy var="product.discount" />%</span>
+      </candy:if>
+    </div>
+  </candy:for>
+</div>
+```
+
+#### Table with Data
+
+```html
+<table class="users-table">
+  <thead>
+    <tr>
+      <th>#</th>
+      <th>Name</th>
+      <th>Email</th>
+      <th>Role</th>
+      <th>Status</th>
+    </tr>
+  </thead>
+  <tbody>
+    <candy:for in="users" key="index" value="user">
+      <tr>
+        <td><candy var="index + 1" /></td>
+        <td><candy var="user.name" /></td>
+        <td><candy var="user.email" /></td>
+        <td><candy var="user.role" /></td>
+        <td>
+          <candy:if condition="user.isActive">
+            <span class="badge success">Active</span>
+          <candy:else>
+            <span class="badge danger">Inactive</span>
+          </candy:if>
+        </td>
+      </tr>
+    </candy:for>
+  </tbody>
+</table>
+```
+
+#### Nested Loops
+
+```html
+<div class="categories">
+  <candy:for in="categories" value="category">
+    <div class="category">
+      <h2><candy var="category.name" /></h2>
+      
+      <div class="products">
+        <candy:for in="category.products" value="product">
+          <div class="product">
+            <h3><candy var="product.name" /></h3>
+            <p>$<candy var="product.price" /></p>
+          </div>
+        </candy:for>
+      </div>
+    </div>
+  </candy:for>
+</div>
+```
+
+#### Grid Layout
+
+```html
+<div class="grid">
+  <candy:for in="items" key="i" value="item">
+    <div class="grid-item">
+      <img src="<candy var="item.image" />" alt="<candy var="item.title" />">
+      <h3><candy var="item.title" /></h3>
+      <p><candy var="item.description" /></p>
+      
+      <!-- Add row break every 3 items -->
+      <candy:if condition="(i + 1) % 3 === 0">
+        <div class="row-break"></div>
+      </candy:if>
+    </div>
+  </candy:for>
+</div>
+```
+
+#### Filtering with Continue
+
+```html
+<div class="active-users">
+  <h2>Active Users</h2>
+  
+  <candy:for in="users" value="user">
+    <!-- Skip inactive users -->
+    <candy:if condition="!user.isActive">
+      <candy:continue />
+    </candy:if>
+    
+    <!-- Skip blocked users -->
+    <candy:if condition="user.isBlocked">
+      <candy:continue />
+    </candy:if>
+    
+    <div class="user-card">
+      <h3><candy var="user.name" /></h3>
+      <p><candy var="user.email" /></p>
+    </div>
+  </candy:for>
+</div>
+```
+
+#### Empty State Handling
+
+```html
+<div class="products-section">
+  <h2>Products</h2>
+  
+  <candy:if condition="products && products.length > 0">
+    <div class="products-grid">
+      <candy:for in="products" value="product">
+        <div class="product-card">
+          <h3><candy var="product.name" /></h3>
+          <p>$<candy var="product.price" /></p>
+        </div>
+      </candy:for>
+    </div>
+  <candy:else>
+    <div class="empty-state">
+      <p>No products found.</p>
+      <a href="/products/add">Add your first product</a>
+    </div>
+  </candy:if>
+</div>
+```
+
+#### Alternating Row Colors
+
+```html
+<table>
+  <candy:for in="items" key="i" value="item">
+    <tr class="<candy:if condition="i % 2 === 0">even<candy:else>odd</candy:if>">
+      <td><candy var="item.name" /></td>
+      <td><candy var="item.value" /></td>
+    </tr>
+  </candy:for>
+</table>
+```
+
+#### Limited Results with Break
+
+```html
+<div class="top-products">
+  <h2>Top 5 Products</h2>
+  
+  <script:candy>
+    let count = 0;
+  </script:candy>
+  
+  <candy:for in="products" value="product">
+    <candy:if condition="count >= 5">
+      <candy:break />
+    </candy:if>
+    
+    <div class="product">
+      <h3><candy var="product.name" /></h3>
+      <p>$<candy var="product.price" /></p>
+    </div>
+    
+    <script:candy>count++;</script:candy>
+  </candy:for>
+</div>
+```
+
+#### Pagination with While
+
+```html
+<script:candy>
+  const itemsPerPage = 10;
+  const currentPage = parseInt(Candy.Request.get('page')) || 1;
+  const startIndex = (currentPage - 1) * itemsPerPage;
+  const endIndex = startIndex + itemsPerPage;
+  let index = startIndex;
+</script:candy>
+
+<div class="items">
+  <candy:while condition="index < endIndex && index < items.length">
+    <div class="item">
+      <candy var="items[index].name" />
+    </div>
+    <script:candy>index++;</script:candy>
+  </candy:while>
+</div>
+```
+
+### Best Practices
+
+1. **Check for existence**: Always verify the array/object exists before looping
+2. **Use meaningful names**: Choose descriptive variable names for keys and values
+3. **Avoid complex logic**: Keep loop bodies simple, move complex logic to controllers
+4. **Handle empty states**: Always provide feedback when there are no items
+5. **Be careful with while**: Ensure while loops will eventually terminate
+
+**Good:**
+```javascript
+// Controller - prepare data
+Candy.set('activeUsers', users.filter(u => u.isActive))
+```
+
+```html
+<!-- View - simple loop -->
+<candy:for in="activeUsers" value="user">
+  <div><candy var="user.name" /></div>
+</candy:for>
+```
+
+**Avoid:**
+```html
+<!-- Too complex for a view -->
+<candy:for in="users" value="user">
+  <candy:if condition="user.isActive && !user.isBlocked && user.role !== 'guest'">
+    <div><candy var="user.name" /></div>
+  </candy:if>
+</candy:for>
+```