78 lines
4.0 KiB
Markdown
78 lines
4.0 KiB
Markdown
# Module Creation Guide
|
|
|
|
## Style Reference
|
|
|
|
When creating new modules, you MUST match the visual style of the existing project. Follow these steps IN ORDER:
|
|
|
|
### Step 1: Check for `docs/project-styles.md`
|
|
- If the file exists → read it and use it as your style reference. DONE — skip to module creation.
|
|
- If the file does NOT exist → continue to Step 2.
|
|
|
|
### Step 2: Determine if exploration is needed
|
|
- Count modules in `template/estandar/modulos/` that have `builder.json` and do NOT start with `custom-`
|
|
- If 3+ qualifying modules exist → continue to Step 3
|
|
- If fewer than 3 → skip exploration, create the module based on the user's description. The style will be defined as modules are created.
|
|
|
|
### Step 3: Explore and GENERATE the style guide (MANDATORY)
|
|
- Read `index-base.tpl` and `style.css` of 3-4 representative modules (only those with `builder.json`, skip `custom-*`)
|
|
- **You MUST then create the file `docs/project-styles.md`** with:
|
|
- Primary/secondary/accent colors (hex values)
|
|
- Font families and sizes used
|
|
- Spacing scale (padding/margin patterns)
|
|
- Common Tailwind classes and custom CSS patterns
|
|
- Button styles, card styles, section layouts
|
|
- Any recurring design patterns (gradients, shadows, borders, etc.)
|
|
- This file will be used by future module creation tasks to avoid re-exploring every time.
|
|
|
|
**After creating a module:** if `docs/project-styles.md` does not exist yet and there are now 3+ modules, generate it.
|
|
|
|
## Module Structure
|
|
|
|
Each module lives in `template/estandar/modulos/<moduleId>/` with:
|
|
- `index-base.tpl` — Twig template (source — EDIT THIS)
|
|
- `style.css` — Module styles
|
|
- `script.js` — Module JavaScript
|
|
- `builder.json` — Compiled builder vars (auto-generated, do NOT edit)
|
|
- `index.tpl` / `index-twig.tpl` — Compiled (auto-generated, do NOT edit)
|
|
|
|
## Creating a Module — Full Workflow
|
|
|
|
1. **Read style reference** (steps above)
|
|
2. **`create_module`** — Creates the directory with index-base.tpl, style.css, script.js and compiles. Use descriptive `moduleId` and clear `label`.
|
|
3. **`add_module_to_record`** — Adds the module to a page. Response includes `sectionId` — use it directly in the next step.
|
|
4. **`set_module_config_vars`** — Fill variables with content. Response includes `uploadFields` with `{ fieldName, recordNum }` for each upload variable.
|
|
5. **Upload images** — Use `generate_image` then `upload_record_image` with the `recordNum` and `fieldName` from step 4's `uploadFields`. No need to read builder.json or call get_module_config_vars.
|
|
6. **`navigate_browser`** — Navigate to the page so the user can see the result.
|
|
|
|
## HTML Field Types
|
|
|
|
Use these `data-field-type` attributes in `index-base.tpl`:
|
|
|
|
| Attribute | Purpose | Example |
|
|
|-----------|---------|---------|
|
|
| `headfield` | Editable heading | `<h2 data-field-type="headfield">Title</h2>` |
|
|
| `textfield` | Short editable text | `<span data-field-type="textfield">Text</span>` |
|
|
| `wysiwyg` | Rich text editor | `<div data-field-type="wysiwyg">Content</div>` |
|
|
| `upload` | Image upload | `<img data-field-type="upload" src="...">` |
|
|
| `list` | Select dropdown | `<div data-field-type="list" data-options="opt1,opt2">` |
|
|
| `multiv2` | Repeater/records | `<div data-field-type="multiv2">...</div>` |
|
|
| `checkbox` | Toggle | `<div data-field-type="checkbox">` |
|
|
| `colorpicker` | Color picker | `<div data-field-type="colorpicker">` |
|
|
|
|
## MJML Modules
|
|
|
|
Modules with `MJMLModule: true` in their schema are email modules:
|
|
- Only appear when the page table is `mail_marketing`
|
|
- For `mail_marketing` tables, only MJML modules are shown
|
|
- Use MJML markup instead of standard HTML
|
|
|
|
## Key Rules
|
|
|
|
- Always use Tailwind CSS as primary styling
|
|
- Use `section_id` variable for unique anchors/scoping
|
|
- Use `interno` variable to detect CMS editor vs public view
|
|
- Include other modules with: `<module_id :param1="value1"></module_id>`
|
|
- After editing `index-base.tpl`, ALWAYS call `compile_module`
|
|
- Twig uses filters (with `|`), never functions
|
|
- Twig concatenation uses `~`: `'value=' ~ variable`
|