สำหรับนักพัฒนา

ปลั๊กอิน

ตัวอย่างปลั๊กอิน — สมุดเยี่ยม

สร้างปลั๊กอิน JavaScript ครบทั้งตัวทีละขั้น — ตารางข้อมูล หน้าสาธารณะในหัว/ท้ายของเว็บ ฟอร์มส่งข้อความ อีเมลแจ้งเตือน หน้าจัดการในหลังบ้าน และการตั้งค่า

อ่าน 10 นาทีอัปเดตล่าสุด

ดูเป็น Markdown

ในหน้านี้

ตัวอย่างนี้สร้างปลั๊กอิน สมุดเยี่ยม (guestbook): ผู้เยี่ยมชมเขียนข้อความที่ /guestbook ผู้ดูแลได้อีเมลแจ้งเตือนและลบข้อความได้จากหลังบ้าน ใช้ API สาธารณะเท่านั้น — อ่านพื้นฐานก่อนที่ สร้างปลั๊กอิน JavaScript

1. โครงสร้าง#

guestbook/
├── manifest.json
├── README.md
├── code/main.ts
└── migrations/001_create_entries.ts

2. manifest.json#

{
  "id": "guestbook",
  "name": "Guestbook / สมุดเยี่ยม",
  "version": "1.0.0",
  "description": "สมุดเยี่ยมให้ผู้เยี่ยมชมเขียนข้อความ / A simple guestbook",
  "author": "Your name",
  "icon": "📖",
  "category": "content",
  "license": "MIT",
  "minCore": "2.0.4",
  "runtime": "js",
  "permissions": ["code", "settings"],
  "settings": [
    { "key": "title", "type": "text", "default": "สมุดเยี่ยม", "maxLength": 100,
      "label": { "th": "หัวข้อหน้า", "en": "Page title" } },
    { "key": "notify", "type": "boolean", "default": true,
      "label": { "th": "ส่งอีเมลแจ้งเมื่อมีข้อความใหม่", "en": "Email me on new entries" } }
  ],
  "code": {
    "entry": "code/main.ts",
    "scopes": ["db", "routes", "mail", "admin-pages"],
    "routes": ["/guestbook"]
  }
}

สิทธิ์ที่ขอ: db (ตารางของตัวเอง), routes (หน้า /guestbook), mail (แจ้งเตือน + อ่านอีเมลผู้ดูแล), admin-pages (หน้าจัดการ)

3. Migration#

// migrations/001_create_entries.ts  → ตารางจริง p_guestbook_entries
export default migration({
  up(schema) {
    schema.create('entries', (t) => {
      t.id();
      t.string('name', 80);
      t.text('message');
      t.timestamps();
    });
  },
  down(schema) { schema.drop('entries'); },
});

4. โค้ด (code/main.ts)#

const esc = (s: unknown) => String(s ?? '').replace(/[&<>"']/g, (c) =>
  ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' } as Record<string, string>)[c]);

/** application/x-www-form-urlencoded → { key: value } */
function parseForm(body: string): Record<string, string> {
  const out: Record<string, string> = {};
  for (const pair of (body || '').split('&')) {
    if (!pair) continue;
    const [k, v = ''] = pair.split('=');
    out[decodeURIComponent(k.replace(/\+/g, ' '))] = decodeURIComponent(v.replace(/\+/g, ' '));
  }
  return out;
}

// หน้าสาธารณะ — แสดงในหัว/ท้ายของเว็บ
site.route('GET /guestbook', { access: ['*'] }, () => {
  const title = String(site.settings('title') || 'สมุดเยี่ยม');
  const rows = db.table('entries').orderBy('id', 'desc').limit(50).get();
  const list = rows.map((r) => `<li><strong>${esc(r.name)}</strong><p>${esc(r.message)}</p></li>`).join('');
  return {
    page: {
      title,
      html: `<section class="gb"><h1>${esc(title)}</h1>
        <form method="post" action="/guestbook">
          <input name="name" required maxlength="80" placeholder="ชื่อ">
          <textarea name="message" required maxlength="1000" placeholder="ข้อความ"></textarea>
          <button type="submit">ส่งข้อความ</button>
        </form>
        <ul>${list || '<li>ยังไม่มีข้อความ</li>'}</ul></section>`,
    },
  };
});

// รับฟอร์ม แล้วพากลับไปหน้าเดิม
site.route('POST /guestbook', { access: ['*'], maxBody: 8192 }, ({ request }) => {
  const f = parseForm(request.body);
  const name = (f.name || '').trim().slice(0, 80);
  const message = (f.message || '').trim().slice(0, 1000);
  if (name && message) {
    db.table('entries').insert({ name, message });
    const to = site.info().adminEmail;
    if (site.settings('notify') && to) {
      try {
        mail.send({ to, subject: 'ข้อความใหม่ในสมุดเยี่ยม', html: `<p><b>${esc(name)}</b>: ${esc(message)}</p>` });
      } catch (e) {
        log.warn('ส่งอีเมลไม่ได้', String(e));   // ยังไม่ได้ตั้ง SMTP
      }
    }
  }
  return { status: 303, headers: { Location: '/guestbook' } };
});

// action ที่หน้าจัดการเรียก
site.action('delete', {
  input: { id: 'number' },
  access: ['administrator', 'editor'],
  run: ({ input }) => {
    db.table('entries').where('id', input.id).delete();
    return { message: 'ลบแล้ว' };
  },
});

// หน้าจัดการในหลังบ้าน
site.adminPage('entries', {
  label: { th: 'สมุดเยี่ยม', en: 'Guestbook' }, icon: '📖', access: ['administrator', 'editor'],
  render: () => {
    const rows = db.table('entries').orderBy('id', 'desc').limit(200).get();
    const tr = rows.map((r) => `<tr><td>${esc(r.name)}</td><td>${esc(r.message)}</td>
      <td><button class="ak-btn" onclick="del(${Number(r.id)})">ลบ</button></td></tr>`).join('');
    return {
      title: 'Guestbook',
      html: `<header class="ak-page-head"><h1>สมุดเยี่ยม</h1></header>
        <div class="ak-table-wrap"><table class="ak-table"><thead><tr><th>ชื่อ</th><th>ข้อความ</th><th></th></tr></thead>
        <tbody>${tr}</tbody></table></div>
        <script>
          async function del(id) {
            if (!(await AK.confirm('ลบข้อความนี้?', { danger: true }))) return;
            anasaki.call('guestbook:delete', { id }).then(() => location.reload(), (e) => AK.toast(e.message, 'error'));
          }
        </script>`,
    };
  },
});

ในหน้าจัดการของปลั๊กอิน ชื่อ action ต้องมี namespace ของปลั๊กอิน (guestbook:delete) และ anasaki.call คืน Promise ที่ reject เมื่อ action ล้ม ส่วนชุดคลาส ak-* และ AK.confirm / AK.toast มาจาก admin UI kit ที่ระบบใส่ให้ทุกหน้า

5. ติดตั้งและทดสอบ#

  1. zip โฟลเดอร์: cd guestbook && zip -r ../guestbook-1.0.0.zip .
  2. ปลั๊กอิน → อัปโหลด .zip → ตรวจสิทธิ์ 4 รายการ → อนุมัติและติดตั้ง → เปิดใช้งาน (migration รันตอนนี้)
  3. เปิด https://เว็บของคุณ/guestbook แล้วลองส่งข้อความ
  4. เมนู สมุดเยี่ยม ปรากฏในหลังบ้าน — ลองลบข้อความ
  5. ปลั๊กอิน → Guestbook → ตั้งค่า เปลี่ยนหัวข้อหน้า แล้วรีเฟรช /guestbook
  6. มีปัญหา? ดู โค้ดของเว็บไซต์ → บันทึกการทำงาน (log ของปลั๊กอินขึ้นต้นด้วย guestbook:)

6. ต่อยอด#

  • ให้ผู้ออกแบบวางรายการข้อความในหน้าใดก็ได้ด้วย site.collection('entries', { … access: ['*'] }) แล้วเลือกแหล่งข้อมูลในชิ้น รายการข้อมูล (ผูกข้อมูลกับหน้าออกแบบ)
  • กันสแปมด้วยช่องหลอก (honeypot) และนับการส่งต่อ IP ด้วย request.ip
  • ให้ปลั๊กอินอื่นรับรู้ข้อความใหม่: ประกาศ "hooks": { "events": ["guestbook.created"] } แล้ว site.emit('guestbook.created', { id })
  • พร้อมแจกจ่าย: เขียน README ไทย/อังกฤษ เพิ่มรูปใน screenshots/ แล้ว เผยแพร่บน Plugin Store

ตัวอย่างเพิ่มเติมใน repository: examples/js-plugins/ (thai, promptpay, files, admin-crud, members, money + shop) และซอร์สของปลั๊กอินทางการใน plugins-official/