kreftjs 0.0.19-beta → 0.0.20-beta
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -0
- package/bin/build.js +13 -2
- package/bin/kreftjs.js +1 -0
- package/book/ar/01-getting-started.md +169 -0
- package/book/ar/02-language.md +330 -0
- package/book/ar/03-components-and-state.md +258 -0
- package/book/ar/04-router-data-forms.md +333 -0
- package/book/ar/05-arabic-rtl.md +175 -0
- package/book/ar/06-backend.md +247 -0
- package/book/ar/07-auth-and-security.md +157 -0
- package/book/ar/08-background-work.md +250 -0
- package/book/ar/09-testing-and-deploy.md +234 -0
- package/book/ar/10-electron-desktop.md +258 -0
- package/book/ar/11-advanced-blog.md +370 -0
- package/book/ar/12-advanced-shop.md +426 -0
- package/book/ar/13-advanced-ui.md +440 -0
- package/book/ar/14-advanced-ops.md +167 -0
- package/book/ar/15-appendix.md +81 -0
- package/book/ar/README.md +62 -0
- package/book/kreft-book-ar.docx +0 -0
- package/docs/README.md +2 -2
- package/kreftjs.d.ts +1 -1
- package/kreftjs.js +436 -74
- package/package.json +4 -3
- package/templates/app/frontend/errors/ErrorMonitor.kreft +2 -2
- package/templates/app/frontend/kreftjs.d.ts +1 -1
- package/templates/app/frontend/kreftjs.js +436 -74
- package/templates/app/frontend/pages/Dashboard.kreft +1 -1
- package/templates/errors/ErrorMonitor.kreft +1 -1
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
# الفصل العاشر: تطبيقات سطح المكتب مع Electron
|
|
2
|
+
|
|
3
|
+
يمكن لـ Kreft أن يحزم تطبيقك كبرنامج سطح مكتب لـ Windows وmacOS وLinux. الصفحات هي ملفات `.kreft` نفسها؛ وElectron يقدّم النافذة فقط.
|
|
4
|
+
|
|
5
|
+
## البداية السريعة
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
kreft new my-app --electron # تطبيق جديد بدعم سطح المكتب
|
|
9
|
+
# أو في تطبيق موجود:
|
|
10
|
+
kreft electron:init # اسم بديل: kreft make:electron
|
|
11
|
+
npm install # يثبّت electron و electron-builder
|
|
12
|
+
kreft electron # يفتح التطبيق في نافذته: بلا متصفح وبلا عنوان
|
|
13
|
+
kreft electron:build # مثبّت في dist-electron/
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
للمساعدة في الطرفية في أي وقت:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
kreft electron:help
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## الأوامر
|
|
23
|
+
|
|
24
|
+
| الأمر | ماذا يفعل |
|
|
25
|
+
|---|---|
|
|
26
|
+
| `kreft electron:init` | يكتب `electron/main.js` و`electron/preload.js` وأيقونة التطبيق `build/icon.png`، ويضيف السكربتات واعتماديات `electron` و`electron-builder` وكتلة `build` إلى `package.json`. الملفات الموجودة لا تُستبدل أبدًا. ويزيل أيضًا روابط Google Fonts من `index.html` ليبدأ التطبيق بلا شبكة. |
|
|
27
|
+
| `kreft electron` | يفتح التطبيق في نافذة سطح مكتب فقط: لا متصفح ولا عنوان يُطبع. خادم التطوير يعمل مخفيًا على منفذ خاص بحاسوبك لا تستعمله إلا النافذة (إعادة التحميل الفورية تعمل). إغلاق النافذة يوقف الخادم. |
|
|
28
|
+
| `kreft electron:build` | يشغّل `kreft build --base ./` ثم `electron-builder`. |
|
|
29
|
+
| `npm run electron:build:mac` | `.dmg` و`.zip`. |
|
|
30
|
+
| `npm run electron:build:win` | مثبّت NSIS و`.exe` محمول. |
|
|
31
|
+
| `npm run electron:build:linux` | AppImage و`.deb` و`.rpm`. |
|
|
32
|
+
| `npm run electron:build:all` | الثلاثة. |
|
|
33
|
+
| `kreft electron:help` | دليل مختصر في الطرفية. |
|
|
34
|
+
|
|
35
|
+
## مرجع سريع
|
|
36
|
+
|
|
37
|
+
| أريد أن… | افعل هذا |
|
|
38
|
+
|---|---|
|
|
39
|
+
| أضيف دعم سطح المكتب | `kreft new my-app --electron`، أو `kreft electron:init` ثم `npm install` |
|
|
40
|
+
| أفتح التطبيق في نافذته | `kreft electron` |
|
|
41
|
+
| أفتح DevTools | `kreft electron --devtools=bottom` أو `ELECTRON_DEVTOOLS=right` أو F12 |
|
|
42
|
+
| أظهر القائمة أو أخفيها | `ELECTRON_MENU=show` أو `auto` أو `hide`؛ و`kreftDesktop.setMenu('hide')` |
|
|
43
|
+
| أغيّر الأيقونة | استبدل `build/icon.png` (PNG مربعة 512×512 أو أكبر) |
|
|
44
|
+
| أغيّر اسم التطبيق | `build.productName` و`build.appId` في `package.json` |
|
|
45
|
+
| أصنع مثبّتًا | `npm run electron:build:mac` أو `:win` أو `:linux` أو `:all` |
|
|
46
|
+
|
|
47
|
+
## بنية المشروع
|
|
48
|
+
|
|
49
|
+
```text
|
|
50
|
+
my-app/
|
|
51
|
+
├── electron/
|
|
52
|
+
│ ├── main.js النافذة والقائمة وجسر النظام
|
|
53
|
+
│ └── preload.js ما تراه صفحاتك من النظام (window.kreftDesktop)
|
|
54
|
+
├── build/icon.png أيقونة التطبيق
|
|
55
|
+
├── dist/ البناء الثابت (kreft build --base ./)
|
|
56
|
+
├── dist-electron/ المثبّتات التي يكتبها electron-builder
|
|
57
|
+
└── package.json "main": "electron/main.js" وكتلة "build"
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## كيف يعمل
|
|
61
|
+
|
|
62
|
+
- أثناء التطوير: خادم Kreft المخفي يخدّم الصفحات، والنافذة تفتحه. لا متصفح يُفتح ولا عنوان يُطبع.
|
|
63
|
+
- في التطبيق المحزوم: النافذة تحمّل `dist/index.html` مباشرة من الملفات، بلا خادم.
|
|
64
|
+
|
|
65
|
+
## اكتشاف تطبيق سطح المكتب
|
|
66
|
+
|
|
67
|
+
```js
|
|
68
|
+
if (Kreftjs.isElectron) {
|
|
69
|
+
const info = await kreftDesktop.getInfo() // { name, version, platform, arch, isPackaged }
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
```html
|
|
74
|
+
<!-- components/Titlebar.kreft -->
|
|
75
|
+
state info = null
|
|
76
|
+
on start { if (Kreftjs.isElectron) info = await kreftDesktop.getInfo() }
|
|
77
|
+
|
|
78
|
+
<view>
|
|
79
|
+
<footer k-if="info">{info.name} v{info.version} · {info.platform}</footer>
|
|
80
|
+
</view>
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## جسر سطح المكتب
|
|
84
|
+
|
|
85
|
+
`window.kreftDesktop` (وكذلك `Kreftjs.desktop`) هو الطريقة الوحيدة التي تصل بها صفحاتك إلى النظام. لا شيء آخر من Node.js أو Electron مكشوف.
|
|
86
|
+
|
|
87
|
+
| الدالة | ماذا تفعل |
|
|
88
|
+
|---|---|
|
|
89
|
+
| `getInfo()` | اسم التطبيق والإصدار والنظام. |
|
|
90
|
+
| `minimize()` و`maximize()` و`close()` | التحكم بالنافذة. |
|
|
91
|
+
| `getMenu()` و`setMenu('show' \| 'auto' \| 'hide')` | قائمة النافذة. |
|
|
92
|
+
| `openDevTools(mode)` و`closeDevTools()` و`toggleDevTools()` | أدوات المطوّر. |
|
|
93
|
+
| `showMessageBox(options)` | مربع رسالة أصلي. |
|
|
94
|
+
| `showOpenDialog(options)` و`showSaveDialog(options)` | نوافذ اختيار الملفات. |
|
|
95
|
+
|
|
96
|
+
```html
|
|
97
|
+
action confirmDelete() {
|
|
98
|
+
const r = await kreftDesktop.showMessageBox({
|
|
99
|
+
type: 'warning',
|
|
100
|
+
buttons: ['حذف', 'إلغاء'],
|
|
101
|
+
defaultId: 1,
|
|
102
|
+
cancelId: 1,
|
|
103
|
+
title: 'تأكيد',
|
|
104
|
+
message: 'هل تريد حذف هذا العنصر؟',
|
|
105
|
+
})
|
|
106
|
+
if (r.response === 0) await remove()
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## إضافة دالة سطح مكتب خاصة بك
|
|
111
|
+
|
|
112
|
+
1. في `electron/main.js` أضف معالجًا: `ipcMain.handle('app:ping', () => 'pong')`.
|
|
113
|
+
2. في `electron/preload.js` أضفه إلى كائن `desktop`: `ping: () => ipcRenderer.invoke('app:ping')`.
|
|
114
|
+
3. استعمله من الصفحة: `await kreftDesktop.ping()`.
|
|
115
|
+
|
|
116
|
+
> **تنبيه أمني:** مرّر الحد الأدنى من البيانات، وتحقق منها في `main.js`. هذا جسر بين صفحة (قد تُحقن فيها شيفرة) ونظام التشغيل.
|
|
117
|
+
|
|
118
|
+
## أدوات المطوّر
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
kreft electron --devtools # على اليمين
|
|
122
|
+
kreft electron --devtools=bottom # أسفل أو left أو detach
|
|
123
|
+
kreft electron --no-devtools
|
|
124
|
+
ELECTRON_DEVTOOLS=bottom kreft electron
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
والمفتاح F12 (أو Ctrl+Shift+I) يبدّل اللوحة.
|
|
128
|
+
|
|
129
|
+
## قائمة النافذة
|
|
130
|
+
|
|
131
|
+
اضبط شريط القائمة عند بدء التطبيق:
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
ELECTRON_MENU=show kreft electron # الافتراضي: الشريط ظاهر
|
|
135
|
+
ELECTRON_MENU=auto kreft electron # مخفي، اضغط Alt لإظهاره (Windows وLinux)
|
|
136
|
+
ELECTRON_MENU=hide kreft electron # بلا قائمة
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
أو غيّرها والتطبيق يعمل من صفحة:
|
|
140
|
+
|
|
141
|
+
```js
|
|
142
|
+
window.kreftDesktop.setMenu('hide') // 'show' | 'auto' | 'hide'
|
|
143
|
+
window.kreftDesktop.getMenu() // الوضع الحالي
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
على macOS تعيش القائمة في الشريط العلوي للشاشة، فـ `show` و`auto` متشابهان، و`hide` يُبقي قائمة اسم التطبيق (فيها Quit) لأن macOS يحتاج واحدة. ولقائمتك الخاصة (File, Edit…) استعمل `Menu.buildFromTemplate([...])` و`Menu.setApplicationMenu(...)` في `electron/main.js`.
|
|
147
|
+
|
|
148
|
+
> **للتطبيقات التي أُنشئت قبل 0.0.18:** ملف `electron/main.js` القديم بلا هذه الميزة. انسخ تعديلاتك احتياطيًا، واحذف الملف، وشغّل `kreft electron:init`.
|
|
149
|
+
|
|
150
|
+
## أيقونة التطبيق
|
|
151
|
+
|
|
152
|
+
يضع `kreft electron:init` شعار Kreft في `build/icon.png`. استبدله بأيقونتك: PNG مربعة 512×512 أو أكبر. تستعملها النافذة، ويصنع electron-builder منها `.icns` (macOS) و`.ico` (Windows). واسم التطبيق في `build.productName` و`build.appId` داخل `package.json`.
|
|
153
|
+
|
|
154
|
+
يحتاج electron-builder أيضًا إلى `description` و`homepage` و`author` (مع بريد) و`build.linux.maintainer` (لـ `.deb` و`.rpm`). الأمران `kreft electron:init` و`kreft electron:build` يملآن الناقص منها من اسمك وبريدك في git؛ راجعها قبل الإصدار.
|
|
155
|
+
|
|
156
|
+
## المثبّتات
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
npm run electron:build:mac # .dmg و .zip
|
|
160
|
+
npm run electron:build:win # مثبّت NSIS و .exe محمول
|
|
161
|
+
npm run electron:build:linux # AppImage و .deb و .rpm
|
|
162
|
+
npm run electron:build:all # الثلاثة
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
تُكتب في `dist-electron/`. والوسائط تذهب إلى electron-builder، مثل `kreft electron:build --mac --arm64`. الإعدادات الافتراضية في كتلة `build` من `package.json`:
|
|
166
|
+
|
|
167
|
+
| النظام | الأهداف |
|
|
168
|
+
|---|---|
|
|
169
|
+
| Windows | مثبّت `nsis` (تختار المجلد) و`portable` |
|
|
170
|
+
| macOS | `dmg` و`zip` |
|
|
171
|
+
| Linux | `AppImage` و`deb` و`rpm` |
|
|
172
|
+
|
|
173
|
+
- ابنِ كل نظام على نظامه. على Mac تُبنى AppImage ومثبّتات Windows، لكن `.deb` و`.rpm` تفشل: ابنهما على Linux، أو احذفهما من `build.linux.target`.
|
|
174
|
+
- توقيع الشيفرة (code signing) يُضبط عبر electron-builder (electron.build/code-signing) ولازم قبل تسليم التطبيق للناس؛ تطبيقات macOS غير الموقّعة تعرض تحذير Gatekeeper.
|
|
175
|
+
- **التطبيق المحزوم لا يشغّل واجهة خلفية.** يحمّل `dist/index.html` فقط. تطبيق الواجهة وحدها يعمل كما هو؛ أما التطبيق المتكامل (تسجيل دخول وقاعدة بيانات) فلا يعمل بعد التثبيت ما لم تشغّل خادمًا في مكان ما وتوجّه `api.setup({ base })` إليه.
|
|
176
|
+
|
|
177
|
+
## `npm run build` أم `electron:build`؟
|
|
178
|
+
|
|
179
|
+
إضافة Electron لا تغيّر `npm run build`. الأمران يصنعان شيئين مختلفين:
|
|
180
|
+
|
|
181
|
+
| الأمر | ماذا يصنع | استعمله لـ |
|
|
182
|
+
|---|---|---|
|
|
183
|
+
| `npm run build` | الموقع في `dist/`، بمسارات تبدأ بـ `/` (ومجلد `docs/` مضمَّن). | نشر التطبيق على خادم ويب. |
|
|
184
|
+
| `npm run electron:build` | الموقع نفسه مبنيًا بـ `--base ./` ليُفتح من ملف، ثم مثبّت في `dist-electron/`. | تسليم التطبيق كبرنامج سطح مكتب. |
|
|
185
|
+
|
|
186
|
+
`dist/` الناتج عن `npm run build` يعرض نافذة بيضاء إن فتحته في Electron لأن مساراته تبدأ بـ `/`. شغّل `electron:build` (أو `kreft build --base ./`) أولًا. ولا مانع من الاثنين: `electron:build` يعيد كتابة `dist/`، فشغّل `npm run build` من جديد قبل نشر الموقع.
|
|
187
|
+
|
|
188
|
+
## الأمان
|
|
189
|
+
|
|
190
|
+
النافذة تتبع إرشادات Electron الأمنية:
|
|
191
|
+
|
|
192
|
+
- `contextIsolation: true` و`nodeIntegration: false` و`sandbox: true`: صفحتك لا ترى Node.js.
|
|
193
|
+
- الروابط الخارجية تُفتح في المتصفح الافتراضي للنظام، لا داخل النافذة.
|
|
194
|
+
- التنقل بعيدًا عن أصل التطبيق ممنوع.
|
|
195
|
+
- الجسر يمرر حقولًا مسموحة فقط إلى نوافذ الحوار.
|
|
196
|
+
|
|
197
|
+
## استكشاف الأخطاء
|
|
198
|
+
|
|
199
|
+
| الرسالة أو العَرَض | الحل |
|
|
200
|
+
|---|---|
|
|
201
|
+
| `Electron is not installed locally` | `kreft add -D electron` |
|
|
202
|
+
| `electron-builder is not installed` | `kreft add -D electron-builder` |
|
|
203
|
+
| نافذة بيضاء في التطبيق المحزوم | أعد تشغيل `electron:build` (يلزمه `--base ./`) وتأكد من وجود `dist/index.html` |
|
|
204
|
+
| `.deb` أو `.rpm` تفشل على Mac | ابنهما على Linux أو احذفهما من `build.linux.target` |
|
|
205
|
+
| خطأ author/maintainer/homepage عند بناء Linux | أضف `author` ببريد و`homepage` و`build.linux.maintainer` في `package.json` |
|
|
206
|
+
| لا أستطيع إخفاء القائمة | استعمل `ELECTRON_MENU=hide`؛ وللتطبيقات القديمة أعد توليد `electron/main.js` |
|
|
207
|
+
|
|
208
|
+
## مثال: تطبيق ملاحظات لسطح المكتب (واجهة فقط)
|
|
209
|
+
|
|
210
|
+
تطبيق لا يحتاج خادمًا: الملاحظات تُحفظ بـ `saved` في الجهاز، وأوامر النظام عبر الجسر.
|
|
211
|
+
|
|
212
|
+
```html
|
|
213
|
+
<!-- pages/Notes.kreft -->
|
|
214
|
+
saved notes = [] // تبقى بعد إغلاق التطبيق
|
|
215
|
+
state text = ''
|
|
216
|
+
state info = null
|
|
217
|
+
|
|
218
|
+
on start { if (Kreftjs.isElectron) info = await kreftDesktop.getInfo() }
|
|
219
|
+
|
|
220
|
+
action add() {
|
|
221
|
+
if (!text.trim()) return
|
|
222
|
+
notes.unshift({ id: Date.now(), text: text.trim() })
|
|
223
|
+
text = ''
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
action removeNote(n) {
|
|
227
|
+
if (Kreftjs.isElectron) {
|
|
228
|
+
const r = await kreftDesktop.showMessageBox({
|
|
229
|
+
type: 'question', buttons: ['حذف', 'إلغاء'], defaultId: 1, cancelId: 1,
|
|
230
|
+
message: 'حذف هذه الملاحظة؟',
|
|
231
|
+
})
|
|
232
|
+
if (r.response !== 0) return
|
|
233
|
+
}
|
|
234
|
+
notes = notes.filter((x) => x.id !== n.id)
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
action hideMenu() { kreftDesktop.setMenu('hide') }
|
|
238
|
+
|
|
239
|
+
<view>
|
|
240
|
+
<h1>ملاحظاتي</h1>
|
|
241
|
+
<form novalidate @submit.prevent={add}>
|
|
242
|
+
<input k-model="text" placeholder="اكتب ملاحظة…">
|
|
243
|
+
</form>
|
|
244
|
+
|
|
245
|
+
<ul>
|
|
246
|
+
<li k-each="n in notes" k-key="n.id">{n.text} <button @click="removeNote(n)">✕</button></li>
|
|
247
|
+
</ul>
|
|
248
|
+
|
|
249
|
+
<p k-if="info">{info.name} {info.version} · {info.platform}</p>
|
|
250
|
+
<button k-if="Kreftjs.isElectron" @click="hideMenu">أخفِ القائمة</button>
|
|
251
|
+
</view>
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
## تمارين
|
|
255
|
+
|
|
256
|
+
1. أنشئ تطبيق سطح مكتب بـ `kreft new notes --electron`، وغيّر الأيقونة، وابنِ `.dmg` أو `.exe`.
|
|
257
|
+
2. أضف دالة `ping` خاصة بك عبر `ipcMain` و`preload.js`.
|
|
258
|
+
3. ابنِ للنظامين وقارن حجم المثبّتين.
|
|
@@ -0,0 +1,370 @@
|
|
|
1
|
+
# الفصل الحادي عشر (متقدم): مدونة كاملة
|
|
2
|
+
|
|
3
|
+
نبني مدونة بمقالات وتعليقات ووسوم، بحث وترقيم صفحات، تحقق متقدم، ووصلات عربية، وSEO للزواحف. **كل شيفرة هنا جُرِّبت فعلًا**: شُغّل الخادم وأُرسلت طلبات حقيقية، وفُتحت الصفحات في المتصفح.
|
|
4
|
+
|
|
5
|
+
ما ستتعلمه: علاقات متعددة لمتعدد (many-to-many)، وscopes، وخطّافات النماذج، وFormRequest، وResource، وقواعد تحقق خاصة، وبحث بتأخير (debounce)، وSEO من قاعدة البيانات.
|
|
6
|
+
|
|
7
|
+
## الخطوة 1: الجداول
|
|
8
|
+
|
|
9
|
+
أربعة جداول: المقالات والتعليقات والوسوم وجدول الربط `post_tag`.
|
|
10
|
+
|
|
11
|
+
```js
|
|
12
|
+
module.exports = {
|
|
13
|
+
up(schema) {
|
|
14
|
+
schema.create('posts', (table) => {
|
|
15
|
+
table.id()
|
|
16
|
+
table.string('title', 200).unique()
|
|
17
|
+
table.string('slug', 220).unique()
|
|
18
|
+
table.text('body').nullable()
|
|
19
|
+
table.boolean('published').default(false)
|
|
20
|
+
table.integer('views').default(0)
|
|
21
|
+
table.json('meta').nullable()
|
|
22
|
+
table.timestamps()
|
|
23
|
+
})
|
|
24
|
+
|
|
25
|
+
schema.create('comments', (table) => {
|
|
26
|
+
table.id()
|
|
27
|
+
table.foreignId('post_id').constrained().cascadeOnDelete()
|
|
28
|
+
table.string('author', 80)
|
|
29
|
+
table.text('body')
|
|
30
|
+
table.boolean('approved').default(false)
|
|
31
|
+
table.timestamps()
|
|
32
|
+
})
|
|
33
|
+
|
|
34
|
+
schema.create('tags', (table) => {
|
|
35
|
+
table.id()
|
|
36
|
+
table.string('name', 60).unique()
|
|
37
|
+
table.timestamps()
|
|
38
|
+
})
|
|
39
|
+
|
|
40
|
+
schema.create('post_tag', (table) => {
|
|
41
|
+
table.id()
|
|
42
|
+
table.foreignId('post_id').constrained().cascadeOnDelete()
|
|
43
|
+
table.foreignId('tag_id').constrained().cascadeOnDelete()
|
|
44
|
+
})
|
|
45
|
+
},
|
|
46
|
+
|
|
47
|
+
down(schema) {
|
|
48
|
+
schema.dropIfExists('post_tag')
|
|
49
|
+
schema.dropIfExists('tags')
|
|
50
|
+
schema.dropIfExists('comments')
|
|
51
|
+
schema.dropIfExists('posts')
|
|
52
|
+
},
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
بعد إضافة ترحيل جديد شغّل `kreft migrate` (خادم التطوير يرحّل عند بدئه فقط). وإن نسيت ستجد الخطأ المفيد: `no such table: posts. Hint: Run kreft migrate`.
|
|
57
|
+
|
|
58
|
+
## الخطوة 2: النماذج
|
|
59
|
+
|
|
60
|
+
```js
|
|
61
|
+
const { Model } = require('kreftjs/server')
|
|
62
|
+
|
|
63
|
+
// Str.slug مناسب للاتينية. للعربية نبني الوصلة بأنفسنا ونُبقي الحروف العربية
|
|
64
|
+
const slugify = (text) => String(text).trim().toLowerCase()
|
|
65
|
+
.replace(/[\u064B-\u065F\u0670\u0640]/g, '') // التشكيل والتطويل
|
|
66
|
+
.replace(/\s+/g, '-')
|
|
67
|
+
.replace(/[^\p{L}\p{N}-]+/gu, '')
|
|
68
|
+
.replace(/-+/g, '-')
|
|
69
|
+
|
|
70
|
+
class Post extends Model {
|
|
71
|
+
static fillable = ['title', 'slug', 'body', 'published', 'meta']
|
|
72
|
+
static casts = { published: 'boolean', meta: 'json' }
|
|
73
|
+
|
|
74
|
+
comments() { return this.hasMany(require('./Comment')) }
|
|
75
|
+
tags() { return this.belongsToMany(require('./Tag'), 'post_tag') }
|
|
76
|
+
|
|
77
|
+
// scopes: تُسلسل كأنها دوال: Post.query().published().search('kreft')
|
|
78
|
+
static scopePublished(q) { q.where('published', true) }
|
|
79
|
+
static scopeSearch(q, text) {
|
|
80
|
+
if (text) q.where((w) => w.where('title', 'like', `%${text}%`).orWhere('body', 'like', `%${text}%`))
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
// خطّاف: يعمل قبل الإنشاء
|
|
84
|
+
static async creating(post) { post.slug ??= slugify(post.title) }
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
module.exports = Post
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
نقاط مهمة:
|
|
91
|
+
|
|
92
|
+
- **`scopePublished` و`scopeSearch`**: دوال استعلام قابلة لإعادة الاستخدام: `Post.query().published().search('كلمة')`.
|
|
93
|
+
- **`creating`**: خطّاف يعمل قبل الإنشاء ويملأ `slug`.
|
|
94
|
+
- **وصلات عربية:** `Str.slug` مصمم للاتينية؛ جرّبته فحوّل "أول" إلى `ا-ول`. لذلك كتبنا `slugify` يُبقي الحروف العربية (`\p{L}`) ويحذف التشكيل. النتيجة: `أول-مقال-في-kreft`.
|
|
95
|
+
- **`casts`**: `published` منطقي و`meta` JSON.
|
|
96
|
+
|
|
97
|
+
```js
|
|
98
|
+
const { Model } = require('kreftjs/server')
|
|
99
|
+
|
|
100
|
+
class Comment extends Model {
|
|
101
|
+
static fillable = ['post_id', 'author', 'body', 'approved']
|
|
102
|
+
static casts = { approved: 'boolean' }
|
|
103
|
+
|
|
104
|
+
post() { return this.belongsTo(require('./Post')) }
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
module.exports = Comment
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
```js
|
|
111
|
+
const { Model } = require('kreftjs/server')
|
|
112
|
+
|
|
113
|
+
class Tag extends Model {
|
|
114
|
+
static fillable = ['name']
|
|
115
|
+
posts() { return this.belongsToMany(require('./Post'), 'post_tag') }
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
module.exports = Tag
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## الخطوة 3: التحقق والاستجابة
|
|
122
|
+
|
|
123
|
+
```js
|
|
124
|
+
const { FormRequest } = require('kreftjs/server')
|
|
125
|
+
|
|
126
|
+
class StorePostRequest extends FormRequest {
|
|
127
|
+
authorize(req) { return true } // في مشروع بمصادقة: return req.user != null
|
|
128
|
+
rules() {
|
|
129
|
+
return {
|
|
130
|
+
title: 'required|min:3|max:200|unique:posts,title',
|
|
131
|
+
body: 'required',
|
|
132
|
+
published: 'boolean',
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
messages() {
|
|
136
|
+
return { 'title.required': 'أعطِ المقال عنوانًا.', 'title.unique': 'هذا العنوان مستعمل من قبل.' }
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
module.exports = StorePostRequest
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
```js
|
|
144
|
+
const { JsonResource } = require('kreftjs/server')
|
|
145
|
+
|
|
146
|
+
class PostResource extends JsonResource {
|
|
147
|
+
toArray(req) {
|
|
148
|
+
return {
|
|
149
|
+
id: this.id,
|
|
150
|
+
title: this.title,
|
|
151
|
+
slug: this.slug,
|
|
152
|
+
excerpt: String(this.body || '').slice(0, 140),
|
|
153
|
+
views: this.views,
|
|
154
|
+
published: this.published,
|
|
155
|
+
created_at: this.created_at,
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
module.exports = PostResource
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
الـ Resource يتحكم بما يخرج من الـ API: هنا نخرج مقتطفًا من النص لا النص كله.
|
|
164
|
+
|
|
165
|
+
### قاعدة تحقق خاصة بالعربية
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
kreft make:rule ArabicName
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
```js
|
|
172
|
+
// قاعدة تحقق خاصة: اسم بالحروف العربية والمسافات فقط
|
|
173
|
+
class ArabicName {
|
|
174
|
+
passes(attribute, value, data) {
|
|
175
|
+
return /^[ء-يٱ-ۓ\s]{2,60}$/.test(String(value || '').trim())
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
message() {
|
|
179
|
+
return 'اكتب :attribute بالحروف العربية فقط.'
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
module.exports = ArabicName
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
وتُستعمل في مصفوفة مع القواعد النصية: `author: ['required', new ArabicName()]` (انظر المتحكم أدناه).
|
|
187
|
+
|
|
188
|
+
## الخطوة 4: المتحكم والمسارات
|
|
189
|
+
|
|
190
|
+
```js
|
|
191
|
+
const { response } = require('kreftjs/server')
|
|
192
|
+
const Post = require('../../Models/Post')
|
|
193
|
+
const Tag = require('../../Models/Tag')
|
|
194
|
+
const PostResource = require('../Resources/PostResource')
|
|
195
|
+
const ArabicName = require('../../Rules/ArabicName')
|
|
196
|
+
const StorePostRequest = require('../Requests/StorePostRequest')
|
|
197
|
+
|
|
198
|
+
class PostController {
|
|
199
|
+
// GET /api/posts?q=كلمة&tag=kreft&page=2
|
|
200
|
+
async index(req) {
|
|
201
|
+
const query = Post.query().published().search(req.string('q')).latest('id')
|
|
202
|
+
if (req.filled('tag')) query.whereHas('tags', (q) => q.where('name', req.string('tag')))
|
|
203
|
+
return PostResource.collection(await query.paginate(5, req.integer('page', 1)))
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
// GET /api/posts/{slug}: يزيد المشاهدات ويحمّل العلاقات
|
|
207
|
+
async show(req, slug) {
|
|
208
|
+
const post = await Post.query().published().where('slug', slug).with('tags').firstOrFail()
|
|
209
|
+
await post.increment('views')
|
|
210
|
+
const comments = await post.comments().where('approved', true).get()
|
|
211
|
+
return { ...post.toJSON(), comments }
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
// POST /api/posts
|
|
215
|
+
async store(req) {
|
|
216
|
+
const data = await StorePostRequest.validate(req)
|
|
217
|
+
const post = await Post.create(data)
|
|
218
|
+
const names = req.input('tags', [])
|
|
219
|
+
const tags = []
|
|
220
|
+
for (const name of names) tags.push((await Tag.where('name', name).first()) || (await Tag.create({ name })))
|
|
221
|
+
await post.tags().sync(tags.map((t) => t.id))
|
|
222
|
+
return response(new PostResource(post), 201)
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
// POST /api/posts/{id}/comments: تنتظر الموافقة
|
|
226
|
+
async comment(req, id) {
|
|
227
|
+
const post = await Post.findOrFail(id)
|
|
228
|
+
const data = await req.validate({ author: ['required', new ArabicName()], body: 'required|min:2|max:1000' })
|
|
229
|
+
return response(await post.comments().create({ ...data, approved: false }), 201)
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
module.exports = PostController
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
وفي `routes/api.js`:
|
|
237
|
+
|
|
238
|
+
```js
|
|
239
|
+
const PostController = require('../app/Http/Controllers/PostController')
|
|
240
|
+
Route.get('/posts', [PostController, 'index'])
|
|
241
|
+
Route.post('/posts', [PostController, 'store'])
|
|
242
|
+
Route.get('/posts/{slug}', [PostController, 'show'])
|
|
243
|
+
Route.post('/posts/{id}/comments', [PostController, 'comment']).middleware('throttle:10,1')
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
ملاحظات:
|
|
247
|
+
|
|
248
|
+
- `index` يبحث ويرشّح بالوسم ويرقّم: `paginate(5, page)` تعيد `{ data, meta }`.
|
|
249
|
+
- `show` يزيد المشاهدات بـ `increment` ويجلب الوسوم والتعليقات الموافَق عليها فقط.
|
|
250
|
+
- `store` ينشئ الوسوم الجديدة ويربطها بـ `sync([...ids])`.
|
|
251
|
+
- `comment` محدود بـ `throttle:10,1` (10 في الدقيقة) والتعليق ينتظر الموافقة (`approved: false`).
|
|
252
|
+
|
|
253
|
+
> **تنبيه الصلاحيات:** هذا المشروع التجريبي بلا تسجيل دخول، فمسار `POST /posts` مفتوح. في مشروع حقيقي ضعه تحت `Route.middleware('auth')` واجعل `authorize()` في `StorePostRequest` تُرجع `req.user != null`، وللتعديل والحذف استعمل سياسة (`req.authorize('update', post)`) كما في الفصل السابع.
|
|
254
|
+
|
|
255
|
+
## جرّبه بنفسك
|
|
256
|
+
|
|
257
|
+
```bash
|
|
258
|
+
curl -H 'Content-Type: application/json' -d '{"title":"أول مقال في Kreft","body":"هذا نص المقال الأول","published":true,"tags":["kreft","js"]}' localhost:8000/api/posts
|
|
259
|
+
curl -H 'Content-Type: application/json' -d '{"title":"أول مقال في Kreft","body":"x"}' localhost:8000/api/posts # 422: العنوان مستعمل
|
|
260
|
+
curl -G --data-urlencode 'q=مقال' localhost:8000/api/posts
|
|
261
|
+
curl 'localhost:8000/api/posts?tag=kreft'
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
نتائج حقيقية من تجربتنا:
|
|
265
|
+
|
|
266
|
+
- إنشاء مقال: `201` وشكله `{"data":{"id":…,"slug":"أول-مقال-في-kreft",…}}`.
|
|
267
|
+
- تكرار العنوان: `422` مع `"The title has already been taken."`.
|
|
268
|
+
- البحث والتصفية بالوسم يعيدان المقالات المطابقة فقط مع `meta` (`total`, `per_page`, `current_page`, `last_page`).
|
|
269
|
+
- تعليق باسم لاتيني: `422`، وباسم عربي: `201`.
|
|
270
|
+
|
|
271
|
+
> **رسالة بالاسم الخام:** رسالة القاعدة الخاصة أظهرت "اكتب author…" لأن اسم الحقل لم يُترجم. أضف `"attributes": { "author": "الاسم" }` إلى `lang/ar/validation.json` فتظهر "اكتب الاسم بالحروف العربية فقط".
|
|
272
|
+
|
|
273
|
+
## الخطوة 5: SEO من قاعدة البيانات
|
|
274
|
+
|
|
275
|
+
```js
|
|
276
|
+
const Post = require('../app/Models/Post')
|
|
277
|
+
|
|
278
|
+
module.exports = {
|
|
279
|
+
'/': { title: 'مدونتي', description: 'مقالات عن البرمجة' },
|
|
280
|
+
'/blog/:slug': async ({ slug }) => {
|
|
281
|
+
const post = await Post.query().published().where('slug', slug).first()
|
|
282
|
+
if (!post) return null // 404 حقيقي مع noindex
|
|
283
|
+
return {
|
|
284
|
+
title: post.title,
|
|
285
|
+
description: String(post.body || '').slice(0, 150),
|
|
286
|
+
schema: { '@type': 'Article', headline: post.title },
|
|
287
|
+
}
|
|
288
|
+
},
|
|
289
|
+
urls: async () => (await Post.query().published().get()).map((p) => ({ path: '/blog/' + p.slug, lastmod: p.updated_at })),
|
|
290
|
+
}
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
اختبرناه بطلب يحاكي زاحفًا:
|
|
294
|
+
|
|
295
|
+
```bash
|
|
296
|
+
curl -A Googlebot "localhost:8000/blog/أول-مقال-في-kreft"
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
والنتيجة تحوي `<title>أول مقال في Kreft</title>` ووسم `description` من نص المقال. ومقال غير موجود يعيد 404 حقيقيًا مع `noindex` لأن الدالة أعادت `null`.
|
|
300
|
+
|
|
301
|
+
## الخطوة 6: صفحة القائمة مع بحث بتأخير
|
|
302
|
+
|
|
303
|
+
```html
|
|
304
|
+
<!-- pages/Blog.kreft -->
|
|
305
|
+
state text = '' // ما يكتبه المستخدم
|
|
306
|
+
state query = '' // ما نبحث به فعلًا (بعد التأخير)
|
|
307
|
+
state tag = ''
|
|
308
|
+
state page = 1
|
|
309
|
+
|
|
310
|
+
// تأخير البحث 300 مللي ثانية: لا طلب مع كل حرف
|
|
311
|
+
let timer
|
|
312
|
+
watch text {
|
|
313
|
+
clearTimeout(timer)
|
|
314
|
+
timer = setTimeout(() => { query = value; page = 1 }, 300)
|
|
315
|
+
}
|
|
316
|
+
on destroy { clearTimeout(timer) }
|
|
317
|
+
|
|
318
|
+
load posts = api.get('/api/posts', { query: { q: query || undefined, tag: tag || undefined, page } })
|
|
319
|
+
|
|
320
|
+
derive meta = posts.data ? posts.data.meta : null
|
|
321
|
+
|
|
322
|
+
action pick(name) { tag = tag === name ? '' : name; page = 1 }
|
|
323
|
+
|
|
324
|
+
<view>
|
|
325
|
+
<h1>المدونة</h1>
|
|
326
|
+
|
|
327
|
+
<input type="search" k-model="text" placeholder="ابحث…">
|
|
328
|
+
<p>
|
|
329
|
+
<button k-each="t in ['kreft', 'js']" k-key="t" class={tag === t ? 'primary' : ''} @click="pick(t)">#{t}</button>
|
|
330
|
+
</p>
|
|
331
|
+
|
|
332
|
+
<p k-if="posts.loading && !posts.loaded">جارٍ التحميل…</p>
|
|
333
|
+
<section k-else>
|
|
334
|
+
{for p in posts.data ? posts.data.data : [] key p.id}
|
|
335
|
+
<article>
|
|
336
|
+
<h3><kreft-link to={'/blog/' + p.slug}>{p.title}</kreft-link></h3>
|
|
337
|
+
<p>{p.excerpt} · {p.views} مشاهدة</p>
|
|
338
|
+
</article>
|
|
339
|
+
{empty}
|
|
340
|
+
<p>لا مقالات تطابق بحثك.</p>
|
|
341
|
+
{/for}
|
|
342
|
+
</section>
|
|
343
|
+
|
|
344
|
+
<p k-if="meta">
|
|
345
|
+
<button disabled={page <= 1} @click="page--">السابق</button>
|
|
346
|
+
{page} / {meta.last_page}
|
|
347
|
+
<button disabled={page >= meta.last_page} @click="page++">التالي</button>
|
|
348
|
+
</p>
|
|
349
|
+
</view>
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
ثلاثة أفكار في هذا الملف:
|
|
353
|
+
|
|
354
|
+
1. **`text` و`query`:** نفصل ما يكتبه المستخدم عمّا نطلبه فعلًا. `watch text` يؤجل تحديث `query` 300 مللي ثانية، فتتجمع الضغطات.
|
|
355
|
+
2. **`load posts`** يقرأ `query` و`tag` و`page` فيعيد الجلب تلقائيًا عند تغيّر أي منها.
|
|
356
|
+
3. **`on destroy`** ينظّف المؤقت.
|
|
357
|
+
|
|
358
|
+
وفي اختبارنا بالمتصفح: كتابة أربعة أحرف متتالية بسرعة أنتجت **طلبًا واحدًا** فقط.
|
|
359
|
+
|
|
360
|
+
ضع المسار في `routes/web.kreft`:
|
|
361
|
+
|
|
362
|
+
```js
|
|
363
|
+
Route.view('/blog', 'pages/Blog.kreft').name('blog').title('المدونة')
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
## تمارين
|
|
367
|
+
|
|
368
|
+
1. أضف صفحة `/blog/:slug` تعرض المقال والتعليقات ونموذج تعليق بـ `form()` يطبّق القاعدة العربية على الواجهة أيضًا.
|
|
369
|
+
2. أضف عدّادًا لمشاهدات اليوم بتخزين العدّاد في الذاكرة المؤقتة (`Cache`) وحفظه في قاعدة البيانات دفعة واحدة كل دقيقة بمهمة مجدولة.
|
|
370
|
+
3. أضف لوحة إدارة لموافقة التعليقات `PATCH /comments/{id}` تحت `auth` و`admin`.
|