odac 0.9.0

package/docs/backend/06-request-and-response/01-the-request-object-what-is-the-user-asking-for.md

@@ -0,0 +1,96 @@
+## 📥 The Request Object
+
+The `Candy.Request` object contains information about the user's incoming request.
+
+### Getting Request Parameters
+
+#### Using Candy.request() (Recommended)
+
+The easiest way to get request parameters is using `Candy.request()`:
+
+```javascript
+module.exports = async function (Candy) {
+  // Get parameter from GET or POST automatically
+  const userName = await Candy.request('name')
+  const userId = await Candy.request('id')
+  
+  return `Hello ${userName}!`
+}
+```
+
+**Specify Method (Optional):**
+
+```javascript
+module.exports = async function (Candy) {
+  // Get from GET parameters only
+  const searchQuery = await Candy.request('q', 'GET')
+  
+  // Get from POST parameters only
+  const formName = await Candy.request('name', 'POST')
+  
+  return `Searching for: ${searchQuery}`
+}
+```
+
+#### Direct Access
+
+You can also access request data directly:
+
+```javascript
+module.exports = function (Candy) {
+  // GET parameters (URL query string like ?id=123)
+  const userId = Candy.Request.get('id')
+  
+  // POST parameters (form data)
+  const userName = Candy.Request.post('name')
+  
+  return `User: ${userName}`
+}
+```
+
+### Request Properties
+
+*   `Candy.Request.method` - HTTP method ('GET', 'POST', etc.)
+*   `Candy.Request.url` - Full URL the user visited
+*   `Candy.Request.host` - Website's hostname
+*   `Candy.Request.ip` - User's IP address
+*   `Candy.Request.ssl` - Whether connection is SSL/HTTPS
+
+### Request Headers
+
+```javascript
+module.exports = function (Candy) {
+  const userAgent = Candy.Request.header('user-agent')
+  const contentType = Candy.Request.header('content-type')
+  
+  return `Browser: ${userAgent}`
+}
+```
+
+### Complete Example
+
+```javascript
+module.exports = async function (Candy) {
+  // Get request parameters
+  const productId = await Candy.request('id')
+  const quantity = await Candy.request('quantity') || 1
+  
+  // Check request method
+  if (Candy.Request.method === 'POST') {
+    // Handle form submission
+    const result = await processOrder(productId, quantity)
+    return { success: true, orderId: result.id }
+  }
+  
+  // Show product page
+  Candy.set({
+    productId: productId,
+    quantity: quantity
+  })
+  
+  Candy.View.set({
+    skeleton: 'main',
+    content: 'product.detail'
+  })
+}
+```

package/docs/backend/06-request-and-response/02-sending-a-response-replying-to-the-user.md

@@ -0,0 +1,40 @@
+## 📤 Sending a Response: Replying to the User
+
+Once you've processed the request, it's time to send something back. You've got a few options.
+
+#### The Simple Way: Just Return It!
+
+For many cases, you can just `return` a value from your controller. CandyPack is smart enough to figure out what to do.
+
+```javascript
+// Return some HTML
+module.exports = function (Candy) {
+  return '<h1>Welcome to the site!</h1>';
+}
+
+// Return some JSON for an API
+module.exports = function (Candy) {
+  return { status: 'success', message: 'Your data was saved!' };
+}
+```
+
+#### The Helper Functions: More Control
+
+Need a bit more control? The `Candy` object has your back.
+
+*   `Candy.return(data)`: Does the same thing as a direct return, but you can call it from anywhere in your function. It stops everything and sends the response immediately.
+*   `Candy.direct(url)`: Need to send the user to a different page? This function performs a redirect, telling the user's browser to go to a new URL.
+
+**Example:**
+```javascript
+module.exports = function (Candy) {
+  // If the user isn't logged in...
+  if (!Candy.Auth.isLogin()) {
+    // ...send them to the login page!
+    return Candy.direct('/login');
+  }
+
+  // Otherwise, give them their data.
+  Candy.return({ data: 'here is your secret stuff' });
+}
+```

package/docs/backend/07-views/01-the-view-directory.md

@@ -0,0 +1,73 @@
+## 📁 View System Overview
+
+CandyPack's view system creates dynamic HTML pages by combining skeleton (layout) and view (content) files. This system provides a modular structure by keeping page layout and content separate.
+
+### Directory Structure
+
+Your project uses two main directories:
+
+- `skeleton/` - Main page skeletons (layout files)
+- `view/` - Page contents and components
+
+### Skeleton Files
+
+Skeleton files define the overall structure of your page. They contain the basic HTML structure including head and body, and host placeholders for content.
+
+Example: `skeleton/main.html`
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>My Website</title>
+    <meta name="description" content="Welcome to my website">
+    <link rel="stylesheet" href="/assets/css/style.css">
+</head>
+<body>
+    <header>
+        {{ HEADER }}
+    </header>
+    
+    <main>
+        {{ CONTENT }}
+    </main>
+    
+    <footer>
+        {{ FOOTER }}
+    </footer>
+</body>
+</html>
+```
+
+**Important Rules for Placeholders:**
+
+1. **Each placeholder must be wrapped in HTML tags** - This allows AJAX to identify and update specific sections
+2. **Never place placeholders directly next to each other** - Bad: `{{ HEADER }}{{ CONTENT }}`, Good: `<header>{{ HEADER }}</header><main>{{ CONTENT }}</main>`
+3. **Placeholders are uppercase** - `{{ HEADER }}`, `{{ CONTENT }}`, `{{ FOOTER }}`
+4. **Use semantic HTML tags** - `<header>`, `<main>`, `<footer>`, `<aside>`, `<nav>`, etc.
+
+**Why wrap in tags?**
+When using AJAX navigation, the system needs to identify which part of the page to update. HTML tags provide clear boundaries for each section.
+
+**Note:** Skeleton files currently support only view part placeholders (uppercase). For dynamic content like page titles, use a view part for the `<head>` section or set them in individual view files.
+
+### View Files
+
+View files contain the content that will be placed into the placeholders within the skeleton. They are organized under the `view/` directory.
+
+Example directory structure:
+
+```
+view/
+├── header/
+│   ├── main.html
+│   └── dashboard.html
+├── content/
+│   ├── home.html
+│   └── about.html
+└── footer/
+    └── main.html
+```
+
+

package/docs/backend/07-views/02-rendering-a-view.md

@@ -0,0 +1,179 @@
+## 🎨 Rendering Views
+
+In CandyPack, you use the `Candy.View` object to render views. There are two main approaches:
+
+### 1. Combining Skeleton and View Parts
+
+The most common usage is to select a skeleton and place view parts into it.
+
+```javascript
+module.exports = function (Candy) {
+  Candy.View
+    .skeleton('main')           // Use skeleton/main.html
+    .set('header', 'main')      // Place view/header/main.html into {{ HEADER }}
+    .set('content', 'home')     // Place view/content/home.html into {{ CONTENT }}
+    .set('footer', 'main')      // Place view/footer/main.html into {{ FOOTER }}
+}
+```
+
+### 2. Bulk Setting with Object
+
+You can set all view parts at once:
+
+```javascript
+module.exports = function (Candy) {
+  Candy.View.set({
+    skeleton: 'main',
+    header: 'main',
+    content: 'home',
+    footer: 'main'
+  })
+}
+```
+
+### 3. Subdirectories with Dot Notation
+
+View files can be organized in subdirectories. You can access them using dot notation:
+
+```javascript
+Candy.View.set({
+  skeleton: 'dashboard',
+  header: 'dashboard.main',      // view/header/dashboard/main.html
+  sidebar: 'dashboard.menu',     // view/sidebar/dashboard/menu.html
+  content: 'user.profile'        // view/content/user/profile.html
+})
+```
+
+### 4. Direct View Rendering from Routes
+
+You can render views directly from route files without using a controller:
+
+```javascript
+// route/www.js
+Candy.Route.page('/about').view({
+  skeleton: 'main',
+  header: 'main',
+  content: 'about',
+  footer: 'main'
+})
+```
+
+### 5. All Feature
+
+If you're using the same directory structure for all placeholders, you can use the `all()` method:
+
+```javascript
+Candy.View
+  .skeleton('main')
+  .all('home')  // view/home/header.html, view/home/content.html, view/home/footer.html
+```
+
+In this case, placeholders like `{{ HEADER }}`, `{{ CONTENT }}`, `{{ FOOTER }}` in the skeleton are automatically matched with `view/home/header.html`, `view/home/content.html`, `view/home/footer.html` files.
+
+### Setting Dynamic Page Titles and Meta Tags
+
+Since skeleton files only support view part placeholders, you have two approaches for dynamic titles:
+
+#### Approach 1: Include Head as a View Part
+
+Create a separate view part for the `<head>` section:
+
+**Skeleton (skeleton/main.html):**
+```html
+<!DOCTYPE html>
+<html lang="en">
+<div id="head">
+    {{ HEAD }}
+</div>
+<body>
+    <header>
+        {{ HEADER }}
+    </header>
+    
+    <main>
+        {{ CONTENT }}
+    </main>
+    
+    <footer>
+        {{ FOOTER }}
+    </footer>
+</body>
+</html>
+```
+
+**Note:** Each placeholder is wrapped in an HTML tag so AJAX can identify and update specific sections.
+
+**Head View (view/head/main.html):**
+```html
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{ Candy.pageTitle }}</title>
+    <meta name="description" content="{{ Candy.pageDescription }}">
+    <link rel="stylesheet" href="/assets/css/style.css">
+</head>
+```
+
+**Controller:**
+```javascript
+module.exports = async function (Candy) {
+  const productId = Candy.Request.get('id')
+  const product = await Candy.Mysql.table('products')
+    .where('id', productId)
+    .first()
+  
+  // Set dynamic title and description
+  Candy.pageTitle = product ? `${product.name} - My Store` : 'Product Not Found'
+  Candy.pageDescription = product ? product.short_description : ''
+  
+  Candy.product = product
+  
+  Candy.View.set({
+    skeleton: 'main',
+    head: 'main',        // Include dynamic head
+    header: 'main',
+    content: 'product.detail',
+    footer: 'main'
+  })
+}
+```
+
+#### Approach 2: Set Title in Content View
+
+Include the title tag in your content view:
+
+**Skeleton (skeleton/simple.html):**
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <link rel="stylesheet" href="/assets/css/style.css">
+</head>
+<body>
+    {{ CONTENT }}
+</body>
+</html>
+```
+
+**Content View (view/content/product.html):**
+```html
+<title>{{ Candy.product.name }} - My Store</title>
+
+<div class="product">
+    <h1>{{ Candy.product.name }}</h1>
+    <p>{{ Candy.product.description }}</p>
+</div>
+```
+
+**Note:** This approach is less clean but works for simple cases.
+
+### Important Notes
+
+- View files must have the `.html` extension
+- Skeleton files should be in the `skeleton/` directory, view files in the `view/` directory
+- Placeholders for view parts are written in uppercase: `{{ HEADER }}`, `{{ CONTENT }}`, etc.
+- View part names are specified in lowercase: `header`, `content`, etc.
+- Variables in skeleton/views are accessed via `Candy` object: `{{ Candy.variableName }}`
+- You don't need to use `return` from the controller, `Candy.View.set()` automatically initiates the rendering process

package/docs/backend/07-views/03-template-syntax.md

@@ -0,0 +1,181 @@
+## 🔧 Template Syntax Overview
+
+CandyPack uses a powerful template engine to create dynamic content in view files. The engine provides a clean, HTML-like syntax for displaying variables, conditionals, loops, translations, and more.
+
+> **Note:** CandyPack also supports legacy syntax (`{{ }}`, `{!! !!}`, `{{-- --}}`) for backward compatibility, but the new `<candy>` tag syntax is recommended for all new projects.
+
+### Quick Reference
+
+This page provides a quick overview of all available template features. For detailed documentation and examples, see the dedicated pages for each feature.
+
+### Variables (Controller Data)
+
+Display data passed from controllers using `Candy.set()`:
+
+```html
+<!-- HTML-safe output -->
+<candy var="username" />
+
+<!-- Raw HTML output -->
+<candy var="htmlContent" raw />
+
+<!-- String literals -->
+<candy>Hello World</candy>
+```
+
+**[→ Learn more about Variables](./03-variables.md)**
+
+### Request Data (Query Parameters)
+
+Access URL query parameters directly:
+
+```html
+<!-- Get query parameter from URL -->
+<!-- URL: /search?q=laptop -->
+<candy get="q" />
+<!-- Output: laptop -->
+```
+
+**Note:** `<candy get>` is for URL parameters. For controller data, use `<candy var>`.
+
+**[→ Learn more about Request Data](./04-request-data.md)**
+
+### Translations (i18n)
+
+Create multi-language applications:
+
+```html
+<!-- Basic translation -->
+<candy translate>Welcome</candy>
+
+<!-- With placeholders -->
+<candy translate>Hello <candy var="user.name" /></candy>
+
+<!-- With HTML preserved -->
+<candy translate raw>Click <a href="/help">here</a></candy>
+```
+
+**[→ Learn more about Translations](./07-translations.md)**
+
+### Comments
+
+Two types of comments for different purposes:
+
+```html
+<!--candy Backend comment (not rendered) -->
+
+<!--candy
+  Multi-line backend comment
+  Won't appear in output
+candy-->
+
+<!-- Regular HTML comment (rendered) -->
+```
+
+**[→ Learn more about Comments](./09-comments.md)**
+
+### Conditionals
+
+Show or hide content based on conditions:
+
+```html
+<candy:if condition="user.isAdmin">
+  <p>Admin panel</p>
+<candy:elseif condition="user.isModerator">
+  <p>Moderator panel</p>
+<candy:else>
+  <p>User panel</p>
+</candy:if>
+```
+
+**[→ Learn more about Conditionals](./05-conditionals.md)**
+
+### Loops
+
+Iterate over arrays and objects:
+
+```html
+<!-- For loop -->
+<candy:for in="users" key="index" value="user">
+  <div><candy var="user.name" /></div>
+</candy:for>
+
+<!-- While loop -->
+<candy:while condition="counter < 10">
+  <p><candy var="counter" /></p>
+</candy:while>
+
+<!-- Loop control -->
+<candy:break />
+<candy:continue />
+```
+
+**[→ Learn more about Loops](./06-loops.md)**
+
+### Backend JavaScript
+
+Execute JavaScript on the server during template rendering:
+
+```html
+<script:candy>
+  // Runs on SERVER before HTML is sent
+  let total = 0;
+  for (let item of cart) {
+    total += item.price * item.quantity;
+  }
+</script:candy>
+
+<p>Total: $<candy var="total" /></p>
+```
+
+**[→ Learn more about Backend JavaScript](./08-backend-javascript.md)**
+
+### Accessing the Candy Object
+
+Full access to the Candy object in templates:
+
+```html
+<candy:if condition="Candy.Auth.check()">
+  <p>User: <candy var="Candy.Auth.user().name" /></p>
+</candy:if>
+
+<p>URL: <candy var="Candy.Request.url" /></p>
+```
+
+### Complete Syntax Reference
+
+| Feature | Syntax | Documentation |
+|---------|--------|---------------|
+| Variable (Controller) | `<candy var="x" />` | [Variables](./03-variables.md) |
+| Raw HTML | `<candy var="x" raw />` | [Variables](./03-variables.md) |
+| String | `<candy>text</candy>` | [Variables](./03-variables.md) |
+| Query Parameter | `<candy get="key" />` | [Request Data](./04-request-data.md) |
+| Translation | `<candy translate>key</candy>` | [Translations](./07-translations.md) |
+| Translation Raw | `<candy translate raw>key</candy>` | [Translations](./07-translations.md) |
+| If | `<candy:if condition="x">` | [Conditionals](./05-conditionals.md) |
+| Elseif | `<candy:elseif condition="x">` | [Conditionals](./05-conditionals.md) |
+| Else | `<candy:else>` | [Conditionals](./05-conditionals.md) |
+| For | `<candy:for in="x" value="item">` | [Loops](./06-loops.md) |
+| While | `<candy:while condition="x">` | [Loops](./06-loops.md) |
+| Break | `<candy:break />` | [Loops](./06-loops.md) |
+| Continue | `<candy:continue />` | [Loops](./06-loops.md) |
+| JavaScript | `<script:candy>...</script:candy>` | [Backend JavaScript](./08-backend-javascript.md) |
+| Comment | `<!--candy ... candy-->` | [Comments](./09-comments.md) |
+
+### Legacy Syntax
+
+CandyPack also supports legacy syntax for backward compatibility:
+
+```html
+<!-- Variable output -->
+{{ username }}
+
+<!-- Raw HTML -->
+{!! htmlContent !!}
+
+<!-- Comments -->
+{{-- This is a comment --}}
+```
+
+**Note:** The new `<candy>` tag syntax is recommended for all new projects.
+