Back to library
API & Routes - Database
Hướng dẫn cho AI biết cách sử dụng database
Prompt Structure (Content)
# APPIFIO App Storage API - Complete AI Developer Guide
## 🚫 CRITICAL: THIS IS USAGE DOCUMENTATION
**AppStorageClient is PRE-BUILT and AUTO-INJECTED into your application.**
### Your Role:
- ✅ **USE** existing methods
- ✅ **CALL** `appifio_client.appifio_*()` functions
- ❌ **NEVER** define `class AppStorageClient`
- ❌ **NEVER** rewrite `appifio_*` methods
---
## 🌐 GLOBAL VARIABLES & FUNCTIONS (Auto-Injected by System)
### 1. Global Configuration Object
The system automatically injects this into every page:
```javascript
window.appifio = {
global: {
apps: {
url_name: "test-blog", // Current app URL name
api_url: "https://appifio.com/l/link/app_storage", // API endpoint
site_url: "https://appifio.com/", // Base site URL
api_key: "encoded_api_key_here" // Encoded API key
}
}
}
```
**Usage:**
```javascript
// Get URL name
const urlName = window.appifio.global.apps.url_name;
// Get site URL
const siteUrl = window.appifio.global.apps.site_url;
// Get API URL
const apiUrl = window.appifio.global.apps.api_url;
```
### 2. AppStorage Client Instance
The system creates `appifio_client` as a getter property:
```javascript
// ✅ CORRECT - appifio_client is always available (never undefined)
if (appifio_client && appifio_client.appifio_readFile) {
const result = await appifio_client.appifio_readFile('blog.json');
}
// ❌ WRONG - Don't check typeof appifio_client === 'undefined'
// It's a getter property, always exists (returns proxyClient if not ready)
```
**Important:** `appifio_client` may return a proxy client that queues calls until the real client is ready. Always check for method existence, not the variable itself.
### 3. Global Helper Functions
Available from `biolink_handler.php`:
```javascript
// Wait for AppStorage client to be ready
await window.waitForAppStorage();
// Callback when AppStorage is ready
window.onAppStorageReady((client) => {
console.log('Client ready:', client);
});
// Get client instance (may return proxy)
const client = window.getAppStorageClient();
// Get client with callback
await window.withClient(async (client) => {
await client.appifio_readFile('blog.json');
});
```
**Recommended Pattern:**
```javascript
// Wait for client to be ready
try {
if (typeof window.waitForAppStorage === 'function') {
await window.waitForAppStorage();
} else if (typeof window.onAppStorageReady === 'function') {
await new Promise((resolve) => {
window.onAppStorageReady(() => resolve());
});
} else {
// Fallback: wait for appifio_client methods
let retries = 0;
while ((!appifio_client || !appifio_client.appifio_readFile) && retries < 50) {
await new Promise(resolve => setTimeout(resolve, 100));
retries++;
}
}
} catch (error) {
console.warn('Error waiting for AppStorage:', error);
}
```
---
## 🔗 ABSOLUTE URL HANDLING
### ⚠️ CRITICAL: Base Tag Issue
The system uses a `<base>` tag that affects relative URLs. **Always use absolute URLs** for navigation links.
### Helper Function: Get Absolute URL
```javascript
function getAbsoluteUrl(path) {
// Get site URL from global config
let siteUrl = window.location.origin;
if (window.appifio && window.appifio.global && window.appifio.global.apps && window.appifio.global.apps.site_url) {
siteUrl = window.appifio.global.apps.site_url.replace(/\/$/, ''); // Remove trailing slash
}
// Get URL name
let urlName = '';
if (window.appifio && window.appifio.global && window.appifio.global.apps && window.appifio.global.apps.url_name) {
urlName = window.appifio.global.apps.url_name;
} else {
// Fallback: extract from current URL
const pathParts = window.location.pathname.split('/').filter(p => p);
urlName = pathParts[0] || '';
}
// Build absolute URL
return siteUrl + '/' + urlName + '/' + path.replace(/^\//, '');
}
// Usage examples:
const homeUrl = getAbsoluteUrl(''); // https://appifio.com/test-blog/
const blogUrl = getAbsoluteUrl('my-blog'); // https://appifio.com/test-blog/my-blog
const tagUrl = getAbsoluteUrl('tag/javascript'); // https://appifio.com/test-blog/tag/javascript
```
### Helper Function: Get URL Name
```javascript
function getUrlName() {
if (window.appifio && window.appifio.global && window.appifio.global.apps && window.appifio.global.apps.url_name) {
return window.appifio.global.apps.url_name;
}
// Fallback: extract from URL
const pathParts = window.location.pathname.split('/').filter(p => p);
return pathParts[0] || '';
}
```
### Example: Back Link with Absolute URL
```javascript
function updateBackLink() {
const backLink = document.getElementById('back-link');
if (backLink) {
const urlName = getUrlName();
let siteUrl = window.location.origin;
if (window.appifio && window.appifio.global && window.appifio.global.apps && window.appifio.global.apps.site_url) {
siteUrl = window.appifio.global.apps.site_url.replace(/\/$/, '');
}
// Use absolute path to avoid base tag issues
backLink.href = siteUrl + '/' + urlName + '/';
}
}
```
---
## ⚠️ CRITICAL CONCEPT 1: File Not Found is NORMAL
### Understanding First-Time Usage
**When reading a file that doesn't exist yet, the API returns `success: false`.**
This is **NORMAL** for first-time usage. You must handle this gracefully.
### ✅ CORRECT PATTERN: Always Initialize with Default Structure
```javascript
// ✅ CORRECT - Always start with default structure
async function loadBlogs() {
// 1. Initialize with default structure FIRST
let blogIndex = {
blogs: {},
metadata: {
total: 0,
last_updated: ''
}
}
// 2. Try to read existing file
try {
if (appifio_client && appifio_client.appifio_readFile) {
const result = await appifio_client.appifio_readFile('blog.json')
// 3. Only use data if read was successful
if (result && result.success) {
blogIndex = JSON.parse(result.data.content)
} else {
// File doesn't exist yet - this is OK!
console.log('blog.json not found, using empty structure')
}
}
} catch (error) {
// Also OK - file doesn't exist
console.log('blog.json not found:', error.message)
}
// 4. Continue with blogIndex (empty or loaded)
return blogIndex
}
```
### ❌ WRONG PATTERN: Don't Assume File Exists
```javascript
// ❌ WRONG - Will crash if file doesn't exist
const result = await appifio_client.appifio_readFile('blog.json')
const blogIndex = JSON.parse(result.data.content) // CRASH if result.success === false!
```
---
## ⚠️ CRITICAL CONCEPT 2: Routes are MANDATORY
### Understanding the Route System
**IMPORTANT: The system ONLY reads `index.html` by default!**
- ✅ URL: `/urlname/` → Reads: `index.html` (automatic)
- ❌ URL: `/urlname/blog-detail` → **NOTHING** (no file served)
- ✅ URL: `/urlname/blog-detail` → Reads: `blog/detail.html` (IF route exists)
### Why Routes are Required
**Without routes, only `index.html` works. ALL other URLs return 404!**
To make ANY other page work, you MUST:
1. Create the HTML file in filesystem
2. Add route mapping to `routes.json`
### Route System Architecture
```
User visits: /urlname/my-blog-post
↓
System checks: routes.json
↓
Finds: "my-blog-post" → { "file": "blog/detail.html" }
↓
Serves: blog/detail.html
↓
blog/detail.html reads data from blog.json
↓
Displays blog content
```
### ⚠️ CRITICAL: Nested Route Paths
**Route paths can contain slashes for nested routes:**
```javascript
// ✅ CORRECT - Nested routes work
await appifio_client.appifio_addRoute('tag/javascript', 'blog/tag.html', 'tag');
await appifio_client.appifio_addRoute('category/tech', 'blog/category.html', 'category');
// URL: /urlname/tag/javascript → Loads blog/tag.html
// URL: /urlname/category/tech → Loads blog/category.html
```
**The routing system extracts the full path after `urlname`:**
- URL: `/test-blog/tag/3123`
- Route path extracted: `tag/3123`
- Matches route in `routes.json`: `"tag/3123"`
### routes.json Structure
```json
{
"routes": {
"my-blog-post": {
"file": "blog/detail.html",
"type": "blog",
"enabled": true
},
"tag/javascript": {
"file": "blog/tag.html",
"type": "tag",
"enabled": true
},
"category/tech": {
"file": "blog/category.html",
"type": "category",
"enabled": true
}
},
"fallback": "index.html"
}
```
### ✅ MANDATORY: Always Create Routes
**Every time you create content, you MUST add a route!**
```javascript
// ❌ WRONG - No route created, URL won't work
await appifio_client.appifio_writeFile('blog.json', blogData)
// User visits /urlname/my-blog → 404 ERROR!
// ✅ CORRECT - Route created, URL works
await appifio_client.appifio_writeFile('blog.json', blogData)
await appifio_client.appifio_addRoute('my-blog', 'blog/detail.html', 'blog')
// User visits /urlname/my-blog → ✅ Works!
```
---
## 📚 AVAILABLE API METHODS
### A. TempDB Storage Operations (Data Files)
Store JSON data files like `blog.json`, `settings.json`:
```javascript
// Read file
const result = await appifio_client.appifio_readFile('blog.json')
if (result && result.success) {
const data = JSON.parse(result.data.content)
}
// Write file (creates if doesn't exist, overwrites if exists)
const saveResult = await appifio_client.appifio_writeFile('blog.json', JSON.stringify(data, null, 2))
if (!saveResult.success) {
console.error('Save failed:', saveResult.message)
}
// Delete file
await appifio_client.appifio_deleteFile('blog.json')
// List files
const files = await appifio_client.appifio_listFiles()
// File exists check
const exists = await appifio_client.appifio_fileExists('blog.json')
// Get file info
const info = await appifio_client.appifio_getFileInfo('blog.json')
```
### B. Filesystem Operations (HTML, Routes)
Store HTML files, routes.json in filesystem:
```javascript
// Read from filesystem
const result = await appifio_client.appifio_readFsFile('routes.json')
if (result && result.success) {
const routes = JSON.parse(result.data.content)
}
// Write to filesystem
await appifio_client.appifio_writeFsFile('routes.json', JSON.stringify(routes, null, 2))
// Delete from filesystem
await appifio_client.appifio_deleteFsFile('file.html')
// List filesystem files
const fsFiles = await appifio_client.appifio_listFsFiles()
// Get filesystem file info
const fsInfo = await appifio_client.appifio_getFsFileInfo('routes.json')
```
### C. Route Management (MANDATORY)
```javascript
// Add route (REQUIRED for every content)
const routeResult = await appifio_client.appifio_addRoute(
'my-blog-post', // Route path (can be nested: 'tag/javascript')
'blog/detail.html', // Target HTML file
'blog' // Route type (optional, for categorization)
)
if (!routeResult.success) {
console.warn('Failed to add route:', routeResult.message)
}
// Remove route (MANDATORY when deleting content)
const removeResult = await appifio_client.appifio_removeRoute('my-blog-post')
// Get all routes
const routesResult = await appifio_client.appifio_getRoutes()
if (routesResult.success && routesResult.data) {
const routes = routesResult.data.routes || {}
console.log('All routes:', routes)
}
```
### D. Helper Functions
```javascript
// Generate slug (supports Vietnamese)
const slug = appifio_client.appifio_generateSlug("Bài viết về AI")
// Returns: "bai-viet-ve-ai"
// Format datetime
const formatted = appifio_client.appifio_formatDateTime('2025-12-27 15:59:10', 'date')
// Returns: "27 Dec 2025"
// Format file size
const size = appifio_client.appifio_formatFileSize(1024)
// Returns: "1 KB"
// Get route slug from current URL
const currentSlug = appifio_client.appifio_getRouteSlug()
// Returns: "my-blog-post" for URL /urlname/my-blog-post
// Parse query parameters
const params = appifio_client.appifio_getQueryParams()
// Returns: { id: "123", page: "2" } for URL ?id=123&page=2
```
### E. Upload Operations
```javascript
// Upload image
const fileInput = document.getElementById('imageInput')
const uploadResult = await appifio_client.appifio_uploadImage(fileInput.files[0])
if (uploadResult.success) {
console.log('Image URL:', uploadResult.data.url)
}
// Upload file
const fileResult = await appifio_client.appifio_uploadFile(fileInput.files[0])
```
### F. Auxiliary Operations (Advanced)
These methods are available for more specific file manipulations.
```javascript
// 1. Copy File
// Copies 'source.json' to 'backup.json'
const copyResult = await appifio_client.appifio_copyFile('source.json', 'backup.json')
// 2. Rename File
// Renames 'old_name.json' to 'new_name.json'
const renameResult = await appifio_client.appifio_renameFile('old_name.json', 'new_name.json')
// 3. Search Files
// Search for files containing "keyword" in name or content
const searchResult = await appifio_client.appifio_searchFiles('keyword')
// Returns array of matching files
// 4. Read Specific Field (JSON Optimization)
// Only reads the "metadata.total" field from "blog.json" instead of downloading the whole file
// Useful for large JSON files
const fieldResult = await appifio_client.appifio_readField('blog.json', 'metadata.total')
// 5. Write Specific Field (JSON Optimization)
// Updates only "metadata.last_updated" in "blog.json"
const updateFieldResult = await appifio_client.appifio_writeField('blog.json', 'metadata.last_updated', '2025-12-31')
```
---
## 🎯 DATA STRUCTURE PATTERN: Single Index File
### ⚠️ CRITICAL CONCEPT
**Use ONE file to store ALL entries of the same type.**
### Example: Blog System with Tags and Categories
**Structure:**
```
TempDB Storage:
├── blog.json ← ALL blogs stored here
Filesystem:
├── routes.json ← Route mappings (MANDATORY)
├── index.html ← Main page
└── blog/
├── detail.html ← Blog detail page handler
├── tag.html ← Tag listing page handler
└── category.html ← Category listing page handler
```
**blog.json content:**
```json
{
"blogs": {
"1735302550000": {
"id": "1735302550000",
"title": "Bài viết về AI",
"slug": "bai-viet-ve-ai",
"author": "Admin",
"content": "<p>Nội dung đầy đủ của bài viết...</p>",
"excerpt": "Mô tả ngắn gọn...",
"tags": ["AI", "Technology", "JavaScript"],
"category": "Công nghệ",
"created_at": "2025-12-27 15:59:10",
"updated_at": "2025-12-27 15:59:10"
}
},
"metadata": {
"total": 1,
"last_updated": "2025-12-27 15:59:10"
}
}
```
**routes.json content (MANDATORY):**
```json
{
"routes": {
"bai-viet-ve-ai": {
"file": "blog/detail.html",
"type": "blog",
"enabled": true
},
"tag/javascript": {
"file": "blog/tag.html",
"type": "tag",
"enabled": true
},
"category/cong-nghe": {
"file": "blog/category.html",
"type": "category",
"enabled": true
}
},
"fallback": "index.html"
}
```
---
## 💻 COMPLETE IMPLEMENTATION EXAMPLES
### Example 1: Create Blog with Tags and Categories
```javascript
async function createBlog(title, author, content, tags = [], category = 'Uncategorized') {
try {
// STEP 1: Initialize with empty structure
let blogIndex = {
blogs: {},
metadata: { total: 0, last_updated: '' }
}
// STEP 2: Try to read existing file
try {
if (appifio_client && appifio_client.appifio_readFile) {
const result = await appifio_client.appifio_readFile('blog.json')
if (result && result.success) {
blogIndex = JSON.parse(result.data.content)
}
}
} catch (error) {
console.log('Creating new blog.json')
}
// STEP 3: Generate ID and slug
const blogId = Date.now().toString()
const slug = appifio_client.appifio_generateSlug(title)
// STEP 4: Create excerpt
const tempDiv = document.createElement('div')
tempDiv.innerHTML = content
const textContent = tempDiv.textContent || tempDiv.innerText || ''
const excerpt = textContent.substring(0, 150) + (textContent.length > 150 ? '...' : '')
// STEP 5: Create blog entry
const now = new Date().toISOString().slice(0, 19).replace('T', ' ')
blogIndex.blogs[blogId] = {
id: blogId,
title: title,
slug: slug,
author: author,
content: content,
excerpt: excerpt,
tags: tags,
category: category,
created_at: now,
updated_at: now
}
// STEP 6: Update metadata
blogIndex.metadata.total = Object.keys(blogIndex.blogs).length
blogIndex.metadata.last_updated = now
// STEP 7: Save to TempDB
const saveResult = await appifio_client.appifio_writeFile(
'blog.json',
JSON.stringify(blogIndex, null, 2)
)
if (!saveResult.success) {
throw new Error('Failed to save: ' + saveResult.message)
}
// STEP 8: MANDATORY - Add route for blog post
const routeResult = await appifio_client.appifio_addRoute(
slug,
'blog/detail.html',
'blog'
)
if (!routeResult.success) {
console.warn('Failed to add blog route:', routeResult.message)
}
// STEP 9: MANDATORY - Ensure routes for tags
await ensureTagRoutes(tags)
// STEP 10: MANDATORY - Ensure route for category
await ensureCategoryRoute(category)
console.log('Blog created successfully!')
return { success: true, blog: blogIndex.blogs[blogId] }
} catch (error) {
console.error('Error creating blog:', error)
return { success: false, error: error.message }
}
}
// Helper: Ensure tag routes exist
async function ensureTagRoutes(tags) {
if (!tags || tags.length === 0) return
if (!appifio_client || !appifio_client.appifio_addRoute) {
console.warn('AppStorage client not available')
return
}
for (const tag of tags) {
if (!tag || tag.trim() === '') continue
const tagSlug = appifio_client.appifio_generateSlug(tag)
if (!tagSlug) continue
const tagRoute = 'tag/' + tagSlug
// Check if route already exists
try {
const routesResult = await appifio_client.appifio_getRoutes()
if (routesResult.success && routesResult.data) {
const routes = routesResult.data.routes || {}
if (routes[tagRoute]) {
console.log('Tag route already exists:', tagRoute)
continue
}
}
// Create route for tag
const routeResult = await appifio_client.appifio_addRoute(
tagRoute,
'blog/tag.html',
'tag'
)
if (routeResult.success) {
console.log('Tag route created:', tagRoute)
} else {
console.warn('Failed to create tag route:', tagRoute, routeResult.message)
}
} catch (error) {
console.error('Error creating tag route:', tag, error)
}
}
}
// Helper: Ensure category route exists
async function ensureCategoryRoute(category) {
if (!category || category.trim() === '') return
if (!appifio_client || !appifio_client.appifio_addRoute) {
console.warn('AppStorage client not available')
return
}
const categorySlug = appifio_client.appifio_generateSlug(category)
if (!categorySlug) return
const categoryRoute = 'category/' + categorySlug
// Check if route already exists
try {
const routesResult = await appifio_client.appifio_getRoutes()
if (routesResult.success && routesResult.data) {
const routes = routesResult.data.routes || {}
if (routes[categoryRoute]) {
console.log('Category route already exists:', categoryRoute)
return
}
}
// Create route for category
const routeResult = await appifio_client.appifio_addRoute(
categoryRoute,
'blog/category.html',
'category'
)
if (routeResult.success) {
console.log('Category route created:', categoryRoute)
} else {
console.warn('Failed to create category route:', categoryRoute, routeResult.message)
}
} catch (error) {
console.error('Error creating category route:', category, error)
}
}
```
### Example 2: Delete Blog (with Route Removal)
```javascript
async function deleteBlog(blogId) {
if (!confirm('Bạn có chắc muốn xóa bài viết này?')) {
return
}
try {
// STEP 1: Read current data
if (!appifio_client || !appifio_client.appifio_readFile) {
throw new Error('AppStorage client not available')
}
const result = await appifio_client.appifio_readFile('blog.json')
if (!result || !result.success) {
throw new Error('Blog index not found')
}
const blogIndex = JSON.parse(result.data.content)
// STEP 2: Check if blog exists
if (!blogIndex.blogs[blogId]) {
throw new Error('Blog not found')
}
// STEP 3: Get slug (for route removal)
const slug = blogIndex.blogs[blogId].slug
// STEP 4: Remove from index
delete blogIndex.blogs[blogId]
// STEP 5: Update metadata
const now = new Date().toISOString().slice(0, 19).replace('T', ' ')
blogIndex.metadata.total = Object.keys(blogIndex.blogs).length
blogIndex.metadata.last_updated = now
// STEP 6: Save to TempDB
const saveResult = await appifio_client.appifio_writeFile(
'blog.json',
JSON.stringify(blogIndex, null, 2)
)
if (!saveResult.success) {
throw new Error('Failed to save: ' + saveResult.message)
}
// STEP 7: MANDATORY - Remove route
if (appifio_client.appifio_removeRoute) {
const routeResult = await appifio_client.appifio_removeRoute(slug)
if (!routeResult.success) {
console.warn('Route removal failed:', routeResult.message)
} else {
console.log('Route removed:', slug)
}
}
console.log('Blog deleted successfully')
alert('Đã xóa bài viết thành công')
return { success: true }
} catch (error) {
console.error('Error deleting blog:', error)
alert('Lỗi: ' + error.message)
return { success: false, error: error.message }
}
}
```
### Example 3: Blog Detail Page (blog/detail.html)
```html
<!DOCTYPE html>
<html lang="vi">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Blog Detail</title>
<style>
body { font-family: Arial, sans-serif; max-width: 800px; margin: 0 auto; padding: 20px; }
.blog-header { border-bottom: 2px solid #333; padding-bottom: 20px; margin-bottom: 20px; }
.blog-meta { color: #666; font-size: 0.9em; margin-top: 10px; }
.blog-content { margin-top: 30px; }
.blog-tags { margin-top: 30px; }
.tag { display: inline-block; background: #e0e0e0; padding: 5px 10px; margin-right: 5px; border-radius: 3px; }
.loading { text-align: center; padding: 50px; }
.error { color: red; text-align: center; padding: 50px; }
</style>
</head>
<body>
<div id="loading" class="loading">Đang tải...</div>
<div id="error" class="error" style="display: none;">Không tìm thấy bài viết</div>
<div id="blog-container" style="display: none;">
<div class="blog-header">
<h1 id="blog-title"></h1>
<div class="blog-meta">
<span id="blog-author"></span> •
<span id="blog-date"></span>
</div>
</div>
<div class="blog-content" id="blog-content"></div>
<div class="blog-tags" id="blog-tags"></div>
<div style="margin-top: 50px;">
<a id="back-link" href="#">← Quay lại trang chủ</a>
</div>
</div>
<script>
// Helper: Get URL name
function getUrlName() {
if (window.appifio && window.appifio.global && window.appifio.global.apps && window.appifio.global.apps.url_name) {
return window.appifio.global.apps.url_name;
}
const pathParts = window.location.pathname.split('/').filter(p => p);
return pathParts[0] || '';
}
// Helper: Update back link with absolute URL
function updateBackLink() {
const backLink = document.getElementById('back-link');
if (backLink) {
const urlName = getUrlName();
let siteUrl = window.location.origin;
if (window.appifio && window.appifio.global && window.appifio.global.apps && window.appifio.global.apps.site_url) {
siteUrl = window.appifio.global.apps.site_url.replace(/\/$/, '');
}
// Use absolute path to avoid base tag issues
backLink.href = siteUrl + '/' + urlName + '/';
}
}
// Wait for AppStorage to be ready
document.addEventListener('DOMContentLoaded', async function() {
try {
updateBackLink();
// Wait for AppStorage
if (typeof window.waitForAppStorage === 'function') {
await window.waitForAppStorage();
} else if (typeof window.onAppStorageReady === 'function') {
await new Promise((resolve) => {
window.onAppStorageReady(() => resolve());
});
} else {
let retries = 0;
while ((!appifio_client || !appifio_client.appifio_readFile) && retries < 50) {
await new Promise(resolve => setTimeout(resolve, 100));
retries++;
}
}
// Get slug from URL
// URL format: /urlname/slug
const pathParts = window.location.pathname.split('/').filter(p => p);
let slug = '';
// Skip urlname, get the next part
if (pathParts.length >= 2) {
const secondPart = pathParts[1];
// If not 'tag' or 'category', it's a blog slug
if (secondPart !== 'tag' && secondPart !== 'category') {
slug = secondPart;
}
}
console.log('Loading blog with slug:', slug);
if (!slug) {
showError('Không tìm thấy bài viết');
return;
}
// Load blog.json
if (!appifio_client || !appifio_client.appifio_readFile) {
showError('AppStorage không khả dụng');
return;
}
const result = await appifio_client.appifio_readFile('blog.json');
if (!result || !result.success) {
showError('Không tìm thấy dữ liệu blog');
return;
}
const blogIndex = JSON.parse(result.data.content);
// Find blog by slug
const blog = Object.values(blogIndex.blogs).find(b => b.slug === slug);
if (!blog) {
showError('Không tìm thấy bài viết');
return;
}
// Display blog
displayBlog(blog);
} catch (error) {
console.error('Error loading blog:', error);
showError('Lỗi: ' + error.message);
}
});
function displayBlog(blog) {
document.getElementById('loading').style.display = 'none';
document.getElementById('blog-container').style.display = 'block';
document.getElementById('blog-title').textContent = blog.title;
document.getElementById('blog-author').textContent = 'Tác giả: ' + blog.author;
// Format date
let dateStr = blog.created_at;
if (appifio_client && appifio_client.appifio_formatDateTime) {
dateStr = appifio_client.appifio_formatDateTime(blog.created_at, 'date');
}
document.getElementById('blog-date').textContent = dateStr;
// Content
document.getElementById('blog-content').innerHTML = blog.content;
// Tags with links
if (blog.tags && blog.tags.length > 0) {
const urlName = getUrlName();
let siteUrl = window.location.origin;
if (window.appifio && window.appifio.global && window.appifio.global.apps && window.appifio.global.apps.site_url) {
siteUrl = window.appifio.global.apps.site_url.replace(/\/$/, '');
}
const tagsHtml = blog.tags.map(tag => {
const tagSlug = appifio_client.appifio_generateSlug(tag);
const tagUrl = siteUrl + '/' + urlName + '/tag/' + tagSlug;
return `<a href="${tagUrl}" class="tag">${escapeHtml(tag)}</a>`;
}).join('');
document.getElementById('blog-tags').innerHTML = 'Tags: ' + tagsHtml;
}
}
function showError(message) {
document.getElementById('loading').style.display = 'none';
const errorDiv = document.getElementById('error');
errorDiv.textContent = message;
errorDiv.style.display = 'block';
}
function escapeHtml(text) {
const div = document.createElement('div');
div.textContent = text;
return div.innerHTML;
}
</script>
</body>
</html>
```
### Example 4: Tag Listing Page (blog/tag.html)
```html
<!DOCTYPE html>
<html lang="vi">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Tag: JavaScript</title>
<style>
body { font-family: Arial, sans-serif; max-width: 800px; margin: 0 auto; padding: 20px; }
.blog-item { border-bottom: 1px solid #eee; padding: 20px 0; }
.blog-item h3 { margin: 0 0 10px 0; }
.blog-item a { text-decoration: none; color: #333; }
.blog-meta { color: #666; font-size: 0.9em; }
.loading { text-align: center; padding: 50px; }
.error { color: red; text-align: center; padding: 50px; }
</style>
</head>
<body>
<div id="loading" class="loading">Đang tải...</div>
<div id="error" class="error" style="display: none;"></div>
<div id="content" style="display: none;">
<h1 id="tag-title">Bài viết với thẻ</h1>
<div id="blog-list"></div>
<div style="margin-top: 30px;">
<a id="back-link" href="#">← Quay lại trang chủ</a>
</div>
</div>
<script>
// Helper functions
function getUrlName() {
if (window.appifio && window.appifio.global && window.appifio.global.apps && window.appifio.global.apps.url_name) {
return window.appifio.global.apps.url_name;
}
const pathParts = window.location.pathname.split('/').filter(p => p);
return pathParts[0] || '';
}
function updateBackLink() {
const backLink = document.getElementById('back-link');
if (backLink) {
const urlName = getUrlName();
let siteUrl = window.location.origin;
if (window.appifio && window.appifio.global && window.appifio.global.apps && window.appifio.global.apps.site_url) {
siteUrl = window.appifio.global.apps.site_url.replace(/\/$/, '');
}
backLink.href = siteUrl + '/' + urlName + '/';
}
}
function generateSlug(text) {
if (!text) return '';
if (appifio_client && appifio_client.appifio_generateSlug) {
return appifio_client.appifio_generateSlug(text);
}
return text.toLowerCase()
.normalize('NFD')
.replace(/[\u0300-\u036f]/g, '')
.replace(/[^\w\s-]/g, '')
.replace(/\s+/g, '-')
.replace(/-+/g, '-')
.replace(/^-+|-+$/g, '');
}
function escapeHtml(text) {
const div = document.createElement('div');
div.textContent = text;
return div.innerHTML;
}
// Main script
document.addEventListener('DOMContentLoaded', async function() {
try {
updateBackLink();
// Get tag slug from URL
// URL format: /urlname/tag/tag-slug
const pathParts = window.location.pathname.split('/').filter(p => p);
let tagSlug = '';
const tagIndex = pathParts.indexOf('tag');
if (tagIndex !== -1 && pathParts.length > tagIndex + 1) {
tagSlug = pathParts[tagIndex + 1];
}
console.log('Loading blogs with tag slug:', tagSlug);
if (!tagSlug) {
showError('Không tìm thấy thẻ');
return;
}
// Wait for AppStorage
if (typeof window.waitForAppStorage === 'function') {
await window.waitForAppStorage();
} else if (typeof window.onAppStorageReady === 'function') {
await new Promise((resolve) => {
window.onAppStorageReady(() => resolve());
});
} else {
let retries = 0;
while ((!appifio_client || !appifio_client.appifio_readFile) && retries < 50) {
await new Promise(resolve => setTimeout(resolve, 100));
retries++;
}
}
await loadTagBlogs(tagSlug);
} catch (error) {
console.error('Error:', error);
showError('Lỗi khi tải bài viết');
}
});
async function loadTagBlogs(tagSlug) {
try {
let blogIndex = { blogs: {}, metadata: { total: 0 } };
if (appifio_client && appifio_client.appifio_readFile) {
const result = await appifio_client.appifio_readFile('blog.json');
if (result && result.success) {
blogIndex = JSON.parse(result.data.content);
} else {
showError('Không tìm thấy dữ liệu blog');
return;
}
} else {
showError('AppStorage không khả dụng');
return;
}
// Filter blogs by tag
const tagBlogs = Object.values(blogIndex.blogs).filter(blog => {
if (!blog.tags || !Array.isArray(blog.tags)) return false;
return blog.tags.some(tag => {
const tagSlugNormalized = generateSlug(tag);
return tagSlugNormalized === tagSlug;
});
});
if (tagBlogs.length === 0) {
showError('Không tìm thấy bài viết nào với thẻ này');
return;
}
// Get tag name from first blog
const firstBlog = tagBlogs[0];
const tagName = firstBlog.tags.find(tag => {
const tagSlugNormalized = generateSlug(tag);
return tagSlugNormalized === tagSlug;
});
// Display blogs
displayTagBlogs(tagName, tagBlogs);
} catch (error) {
console.error('Error loading tag blogs:', error);
showError('Lỗi: ' + error.message);
}
}
function displayTagBlogs(tagName, blogs) {
document.getElementById('loading').style.display = 'none';
document.getElementById('content').style.display = 'block';
document.getElementById('tag-title').textContent = 'Bài viết với thẻ: ' + tagName;
document.title = 'Thẻ: ' + tagName + ' - Blog';
const blogList = document.getElementById('blog-list');
const urlName = getUrlName();
let siteUrl = window.location.origin;
if (window.appifio && window.appifio.global && window.appifio.global.apps && window.appifio.global.apps.site_url) {
siteUrl = window.appifio.global.apps.site_url.replace(/\/$/, '');
}
blogs.sort((a, b) => new Date(b.created_at) - new Date(a.created_at));
let html = '';
blogs.forEach(blog => {
html += `
<div class="blog-item">
<h3><a href="${siteUrl}/${urlName}/${blog.slug}">${escapeHtml(blog.title)}</a></h3>
<div class="blog-meta">
Tác giả: ${escapeHtml(blog.author)} •
${formatDate(blog.created_at)}
</div>
<div>${escapeHtml(blog.excerpt || '')}</div>
</div>
`;
});
blogList.innerHTML = html;
}
function formatDate(dateString) {
if (appifio_client && appifio_client.appifio_formatDateTime) {
return appifio_client.appifio_formatDateTime(dateString, 'date');
}
const date = new Date(dateString);
return date.toLocaleDateString('vi-VN', {
day: '2-digit',
month: '2-digit',
year: 'numeric'
});
}
function showError(message) {
document.getElementById('loading').style.display = 'none';
const errorDiv = document.getElementById('error');
errorDiv.textContent = message;
errorDiv.style.display = 'block';
}
</script>
</body>
</html>
```
### Example 5: Category Listing Page (blog/category.html)
Similar to tag.html, but filters by category instead of tags:
```javascript
// In blog/category.html, extract category slug from URL:
// URL format: /urlname/category/category-slug
const pathParts = window.location.pathname.split('/').filter(p => p);
let categorySlug = '';
const categoryIndex = pathParts.indexOf('category');
if (categoryIndex !== -1 && pathParts.length > categoryIndex + 1) {
categorySlug = pathParts[categoryIndex + 1];
}
// Filter blogs by category:
const categoryBlogs = Object.values(blogIndex.blogs).filter(blog => {
if (!blog.category) return false;
const blogCategorySlug = generateSlug(blog.category);
return blogCategorySlug === categorySlug;
});
```
---
## 📋 CRITICAL RULES
### ✅ ALWAYS DO:
1. **Initialize with default structure** before reading files
2. **Handle file not found gracefully** - it's normal for first-time
3. **Single Index File:** Store all blogs in ONE `blog.json` file
4. **Use ID as Key:** Structure as `{ blogs: { "id": {...} } }`
5. **Full Content:** Store complete blog content in `content` field
6. **Generate Slug:** Use `appifio_generateSlug()` for URL-friendly slugs
7. **Update Metadata:** Always update `metadata.total` and `metadata.last_updated`
8. **MANDATORY Routes:** Create route entry for EVERY blog, tag, and category
9. **Nested Routes:** Use `tag/slug` and `category/slug` format for nested routes
10. **Create Handler Files:** Blog detail/tag/category HTML must exist in filesystem
11. **Absolute URLs:** Always use absolute URLs for navigation (base tag issue)
12. **Remove Routes:** Always remove routes when deleting content
13. **Error Handling:** Use try-catch for all async operations
14. **Check Client:** Always check `appifio_client && appifio_client.methodName` before calling
### ❌ NEVER DO:
1. ❌ Assume file exists without checking
2. ❌ Create separate files per blog (`blog-slug.json`)
3. ❌ Store only metadata without full content
4. ❌ Hardcode IDs
5. ❌ Forget to update metadata section
6. ❌ Skip route creation (URLs won't work!)
7. ❌ Forget to create handler HTML files
8. ❌ Use relative URLs for navigation (base tag breaks them)
9. ❌ Forget to remove routes when deleting
10. ❌ Check `typeof appifio_client === 'undefined'` (it's a getter, always exists)
11. ❌ Define `class AppStorageClient`
12. ❌ Rewrite `appifio_*` methods
---
## 🔍 STORAGE SEPARATION
### TempDB (app_storage table)
**Purpose:** Store data files
**Use for:** `blog.json`, `settings.json`, `user-data.json`
**Methods:** `appifio_readFile()`, `appifio_writeFile()`
### Filesystem (sync_data/urlname/)
**Purpose:** Store HTML files and configuration
**Use for:** `routes.json`, `blog/detail.html`, `index.html`, `blog/tag.html`, `blog/category.html`
**Methods:** `appifio_readFsFile()`, `appifio_writeFsFile()`
---
## 🎯 COMPLETE WORKFLOW
### First-Time Setup:
```
1. Create blog/detail.html, blog/tag.html, blog/category.html in filesystem
↓
2. User creates first blog
↓
3. blog.json is created (writeFile)
↓
4. Route is added to routes.json for blog post
↓
5. Routes are added for tags and category
↓
6. System can now serve /urlname/blog-slug, /urlname/tag/tag-slug, /urlname/category/category-slug
```
### Creating a Blog:
```
1. Read blog.json (or use empty structure if not found)
2. Generate ID (timestamp)
3. Generate slug from title
4. Add new entry to blogs object
5. Update metadata
6. Save blog.json to TempDB
7. Add route to routes.json for blog post (MANDATORY)
8. Ensure routes exist for all tags (tag/tag-slug format)
9. Ensure route exists for category (category/category-slug format)
10. User can now visit /urlname/slug, /urlname/tag/tag-slug, /urlname/category/category-slug
```
### Displaying a Blog:
```
User visits: /urlname/my-blog-slug
↓
System reads: routes.json
↓
Finds: "my-blog-slug" → "blog/detail.html"
↓
Serves: blog/detail.html
↓
blog/detail.html reads: blog.json (TempDB)
↓
Finds blog with slug: "my-blog-slug"
↓
Displays: blog content
```
### Displaying Tag/Category:
```
User visits: /urlname/tag/javascript
↓
System reads: routes.json
↓
Finds: "tag/javascript" → "blog/tag.html"
↓
Serves: blog/tag.html
↓
blog/tag.html extracts slug "javascript" from URL
↓
Reads: blog.json (TempDB)
↓
Filters blogs by tag slug
↓
Displays: filtered blog list
```
---
## 💡 DEBUGGING TIPS
### If blog.json not found:
```javascript
// ✅ This is NORMAL for first time
console.log('blog.json not found - will create on first save')
```
### If route doesn't work:
```javascript
// Check if route exists
const routes = await appifio_client.appifio_getRoutes()
console.log('All routes:', routes.data.routes)
// Check specific route
if (!routes.data.routes['my-slug']) {
console.error('Route missing! Add it:')
await appifio_client.appifio_addRoute('my-slug', 'blog/detail.html', 'blog')
}
```
### If nested route doesn't work:
```javascript
// Check nested route
const routes = await appifio_client.appifio_getRoutes()
if (!routes.data.routes['tag/javascript']) {
console.error('Nested route missing! Add it:')
await appifio_client.appifio_addRoute('tag/javascript', 'blog/tag.html', 'tag')
}
```
### If handler file doesn't exist:
```javascript
// Check if file exists
const result = await appifio_client.appifio_readFsFile('blog/detail.html')
if (!result.success) {
console.error('Handler file missing! Create it:')
await appifio_client.appifio_writeFsFile('blog/detail.html', htmlContent)
}
```
### If navigation links broken:
```javascript
// Always use absolute URLs
const urlName = getUrlName();
let siteUrl = window.location.origin;
if (window.appifio && window.appifio.global && window.appifio.global.apps && window.appifio.global.apps.site_url) {
siteUrl = window.appifio.global.apps.site_url.replace(/\/$/, '');
}
const absoluteUrl = siteUrl + '/' + urlName + '/path';
```
---
## 🎓 FINAL REMINDER
You are building an APPLICATION that USES a pre-built API.
The API library is already written and injected.
Your job: Write business logic using the API.
Focus: User interface, data flow, user experience.
Don't waste time: Reimplementing what already exists.
### Key Points:
- File not found is NORMAL for first-time usage
- Routes are MANDATORY for all non-index URLs
- Nested routes work: `tag/slug`, `category/slug`
- Handler HTML files MUST exist in filesystem
- Always initialize with default structure
- Always add routes when creating content
- Always remove routes when deleting content
- Always use absolute URLs for navigation
- Always check `appifio_client && appifio_client.methodName` before calling
Build great applications with the tools provided!