Skip to content

Commit cc9d6ba

Browse files
devClunadevCluna
committed
docs: add README with setup guide, API reference and field documentation
1 parent 5740f8e commit cc9d6ba

1 file changed

Lines changed: 240 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 240 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,240 @@
1-
# strapi-plugin-form-builder-cms
1+
# strapi-plugin-form-builder-cms
2+
3+
A visual drag-and-drop form builder plugin for [Strapi 5](https://strapi.io). Create, publish and embed forms on any website without writing a single line of backend code.
4+
5+
---
6+
7+
## Features
8+
9+
- **Drag-and-drop builder** — reorder fields visually inside the Strapi admin.
10+
- **Rich field types** — text, email, number, phone, URL, password, date, time, textarea, select, radio, checkbox, checkbox-group, heading, paragraph, divider.
11+
- **Field validation** — required, minLength, maxLength, min value, max value, email, URL, regex pattern — all configurable per field with custom error messages.
12+
- **Draft / Publish** — save a draft without going live; publish when ready.
13+
- **Public page** — one toggle generates a hosted page at `/api/strapi-plugin-form-builder-cms/page/:slug`.
14+
- **Embed script** — a single `<script>` tag renders the form on any external site with zero dependencies.
15+
- **Honeypot spam protection** — invisible field silently discards bot submissions.
16+
- **Submission inbox** — view, filter by status (new / read / archived), inspect and delete submissions from the admin.
17+
- **Form preview** — preview the rendered form inside the admin before publishing.
18+
19+
---
20+
21+
## Requirements
22+
23+
| Dependency | Version |
24+
|---|---|
25+
| Strapi | `^5.0.0` |
26+
| Node.js | `>=18.0.0` |
27+
| React | `^18.0.0` |
28+
29+
---
30+
31+
## Installation
32+
33+
```bash
34+
# npm
35+
npm install strapi-plugin-form-builder-cms
36+
37+
# yarn
38+
yarn add strapi-plugin-form-builder-cms
39+
```
40+
41+
### Enable the plugin
42+
43+
Add the plugin to your Strapi configuration:
44+
45+
```js
46+
// config/plugins.js (or config/plugins.ts)
47+
module.exports = {
48+
'strapi-plugin-form-builder-cms': {
49+
enabled: true,
50+
},
51+
};
52+
```
53+
54+
### Rebuild and restart
55+
56+
```bash
57+
npm run build
58+
npm run develop
59+
```
60+
61+
The **Form Builder** entry will appear in the Strapi admin sidebar.
62+
63+
---
64+
65+
## Usage
66+
67+
### 1 — Create a form
68+
69+
1. Open **Form Builder** in the sidebar.
70+
2. Click **New form**, give it a title.
71+
3. Drag field types from the left palette onto the canvas.
72+
4. Click any field to open its settings panel (label, name, placeholder, required, width, validation rules).
73+
5. Click **Save draft** to persist without publishing, or **Publish** to make it live.
74+
75+
### 2 — Embed on your website
76+
77+
Open the form and click the **Embed** button to copy the snippet:
78+
79+
```html
80+
<div id="sfb-form-{id}"></div>
81+
<script
82+
src="https://your-strapi-domain.com/api/strapi-plugin-form-builder-cms/embed.js"
83+
data-form-id="{id}"
84+
async
85+
></script>
86+
```
87+
88+
Paste both tags wherever you want the form to appear. The script is self-contained — no external dependencies, no build step required.
89+
90+
### 3 — Public page (optional)
91+
92+
Toggle **Public page** in the form settings. A shareable URL is generated:
93+
94+
```
95+
https://your-strapi-domain.com/api/strapi-plugin-form-builder-cms/page/{slug}
96+
```
97+
98+
Share or link directly to this page — it renders the form in a clean, responsive layout served by Strapi itself.
99+
100+
### 4 — View submissions
101+
102+
Click **Submissions** on any form card from the list page. Filter by status, open a submission to see all field values, and update its status (new → read → archived) or delete it.
103+
104+
---
105+
106+
## Public API routes
107+
108+
These routes require no authentication and are safe to call from the browser.
109+
110+
| Method | Path | Description |
111+
|---|---|---|
112+
| `GET` | `/api/strapi-plugin-form-builder-cms/embed.js` | Serve the embed script |
113+
| `GET` | `/api/strapi-plugin-form-builder-cms/forms/:id/embed-schema` | Form schema by numeric ID |
114+
| `GET` | `/api/strapi-plugin-form-builder-cms/forms/:slug/schema` | Form schema by slug |
115+
| `GET` | `/api/strapi-plugin-form-builder-cms/page/:slug` | Hosted public page |
116+
| `POST` | `/api/strapi-plugin-form-builder-cms/forms/:slug/submit` | Submit form data |
117+
118+
### Submit payload
119+
120+
```json
121+
{
122+
"data": {
123+
"fieldName": "value",
124+
"checkboxGroupField": ["option1", "option2"]
125+
}
126+
}
127+
```
128+
129+
### Submit response — success
130+
131+
```json
132+
{ "success": true, "successMessage": "Thank you!" }
133+
```
134+
135+
### Submit response — validation error (`400`)
136+
137+
```json
138+
{
139+
"success": false,
140+
"errors": {
141+
"email": ["Enter a valid email address"],
142+
"name": ["Minimum 3 characters"]
143+
}
144+
}
145+
```
146+
147+
---
148+
149+
## Field types
150+
151+
| Type | Description |
152+
|---|---|
153+
| `text` | Single-line text input |
154+
| `email` | Email input (auto-validates format) |
155+
| `number` | Numeric input (auto-validates format) |
156+
| `phone` | Tel input |
157+
| `url` | URL input (auto-validates format) |
158+
| `password` | Password input |
159+
| `date` | Date picker |
160+
| `time` | Time picker |
161+
| `textarea` | Multi-line text |
162+
| `select` | Dropdown — configure options in the settings panel |
163+
| `radio` | Radio group — configure options in the settings panel |
164+
| `checkbox` | Single checkbox (agree / consent) |
165+
| `checkbox-group` | Multiple checkboxes — configure options in the settings panel |
166+
| `heading` | Non-input heading label |
167+
| `paragraph` | Non-input descriptive text |
168+
| `divider` | Horizontal rule to separate sections |
169+
170+
---
171+
172+
## Validation rules
173+
174+
| Rule | Applies to | Description |
175+
|---|---|---|
176+
| `required` | All input fields | Field must not be empty |
177+
| `minLength` | Text fields | Minimum character count |
178+
| `maxLength` | Text fields | Maximum character count |
179+
| `min` | `number` | Minimum numeric value |
180+
| `max` | `number` | Maximum numeric value |
181+
| `email` | Text fields | Must be a valid email address |
182+
| `url` | Text fields | Must be a valid URL |
183+
| `pattern` | Text fields | Must match a regular expression |
184+
185+
Each rule accepts an optional **custom error message**. The same rule type cannot be added twice to the same field.
186+
187+
---
188+
189+
## Form settings
190+
191+
| Setting | Description |
192+
|---|---|
193+
| Submit button text | Label on the submit button |
194+
| Success message | Message shown after a successful submission |
195+
| Honeypot protection | Adds a hidden field to silently discard bot submissions |
196+
| Public page | Generates a hosted page URL for the form |
197+
198+
---
199+
200+
## Development
201+
202+
Clone the repo and link the plugin to a local Strapi project:
203+
204+
```bash
205+
git clone https://github.com/dev-cluna/strapi-plugin-form-builder-cms.git
206+
cd strapi-plugin-form-builder-cms
207+
npm install
208+
209+
# watch mode — rebuilds on save
210+
npm run watch:link
211+
```
212+
213+
In your local Strapi project:
214+
215+
```bash
216+
npm run develop
217+
```
218+
219+
---
220+
221+
## Contributing
222+
223+
Pull requests are welcome. For major changes please open an issue first to discuss what you would like to change.
224+
225+
1. Fork the repository.
226+
2. Create a feature branch: `git checkout -b feat/my-feature`.
227+
3. Commit your changes following [Conventional Commits](https://www.conventionalcommits.org/).
228+
4. Open a pull request.
229+
230+
---
231+
232+
## License
233+
234+
[MIT](LICENSE)
235+
236+
---
237+
238+
## Author
239+
240+
**dev.cluna** — [dev.cluna@gmail.com](mailto:dev.cluna@gmail.com)

0 commit comments

Comments
 (0)