# MultiPortal SaaS — Template Integration Skill ## How to integrate a new template and produce a `blocks.json` **Version:** 2.1 **System:** MultiPortal SaaS **Files involved:** `admin.html`, `multiportal.html`, `templates/{id}/template.html`, `templates/{id}/blocks.json`, `data/db.json` --- ## 1. System Overview MultiPortal is a SaaS portal builder where each "portal" (website) is assigned a **template** — a self-contained HTML file that provides the visual shell (navbar, footer, colour scheme, typography). Page content is injected into the shell via `{{TAG}}` placeholders. A **block** is a reusable HTML section (Hero, Features, Team, etc.) that a portal admin drags onto a page using the Block Builder. Blocks are stored per-template in `templates/{id}/blocks.json`. The **Block Editor** (`blockeditor.html`) is a standalone tool for creating and editing `blocks.json` files visually. ### Data Flow ``` User picks template → admin.html fetches templates/{id}/blocks.json → Block Builder shows available blocks → User drags blocks onto a page → Page HTML = concatenated block HTML → multiportal.html fetches template.html + fills {{TAGS}} → renders portal in iframe ``` ### Two Types of Template CSS Understanding this distinction is critical before starting any integration: | Type | CSS lives in | Applied to | |------|-------------|------------| | **Native template** (you built it) | `template.html` ` {{SECTIONS_HTML}} ``` ### 3.2 All Available `{{TAGS}}` | Tag | Type | Description | |-----|------|-------------| | `{{PORTAL_NAME}}` | string | Portal display name, e.g. `"SMK Bukit Jambul"` | | `{{PORTAL_TAGLINE}}` | string | Short description / tagline | | `{{PRIMARY_COLOR}}` | hex | e.g. `#4361ee` — use in CSS variables | | `{{SECONDARY_COLOR}}` | hex | e.g. `#10b981` | | `{{FONT_FAMILY}}` | string | Google Font name, e.g. `Poppins` | | `{{FONT_FAMILY_URL}}` | string | Same name with `+` not spaces, e.g. `DM+Sans` | | `{{PORTAL_LOGO_HTML}}` | HTML | `

` or empty string | | `{{NAV_ITEMS_HTML}}` | HTML | Rendered `

` elements for navigation | | `{{SECTIONS_HTML}}` | HTML | All page sections as `

` | | `{{FOOTER_TEXT}}` | string | Copyright text | | `{{CONTACT_EMAIL}}` | string | Contact email | | `{{CONTACT_PHONE}}` | string | Contact phone | | `{{CONTACT_ADDRESS}}` | string | Physical address | | `{{SOCIAL_LINKS_HTML}}` | HTML | Social media `

` elements | | `{{CURRENT_YEAR}}` | number | 4-digit year | **Tags in block HTML**: Blocks can also use `{{PORTAL_NAME}}`, `{{PORTAL_TAGLINE}}`, `{{PRIMARY_COLOR}}`, `{{SECONDARY_COLOR}}` etc. — they are resolved at render time. In the Block Editor they display as **orange badge pills** rather than being replaced, so authors can see them. ### 3.3 How `{{SECTIONS_HTML}}` renders The renderer wraps each published page's content HTML in: ```html

...content blocks HTML...

``` The first section gets `active`. Style both `.tN-hero` and `.tN-section` in your CSS. ### 3.4 How `{{NAV_ITEMS_HTML}}` renders ```html

Home

``` ### 3.5 CSS Class Naming Convention **CRITICAL for native templates:** Every CSS class must use a unique prefix based on the template ID to prevent style bleed between templates in the admin previewer. | Template ID | Required prefix | |-------------|-----------------| | `t009` | `.t9-` | | `t010` | `.t10-` | | `t011` | `.t11-` | Examples: `.t9-nav`, `.t9-hero`, `.t9-card`, `.t9-footer` **Third-party templates** already have their own class names (e.g. `.hero`, `.about-thumb`, `.projects-image`). Do NOT rename these — they are tied to the CSS. Handle CSS via the styles foundation block (see §4.5). --- ## 4. Block Library (`blocks.json`) ### 4.1 File Location ``` templates/{templateId}/blocks.json ``` Loaded by `admin.html` via `fetch('templates/{id}/blocks.json')`. Must be accessible over HTTP (not `file://`). ### 4.2 Block Object Schema ```json [ { "id": "t9-hero", "name": "Hero Banner", "desc": "Full-width hero with background, heading, tagline and CTA button.", "icon": "🏠", "category": "Hero", "thumbnail": "data:image/jpeg;base64,...", "html": "

...

" } ] ``` | Field | Type | Required | Rules | |-------|------|----------|-------| | `id` | string | ✓ | Unique, kebab-case, prefixed: `t9-hero`, `t9-about` | | `name` | string | ✓ | Human-readable, shown in block library | | `desc` | string | ✓ | One sentence description for block library card | | `icon` | string | ✓ | Single emoji, shown if no thumbnail | | `category` | string | ✓ | See Category List §4.3 | | `thumbnail` | string | recommended | Base64 JPEG data URL of a preview screenshot | | `html` | string | ✓ | The block's raw HTML (see §4.4 and §4.5) | ### 4.3 Category List Use exactly these strings (case-sensitive): ``` Hero Features About Services Content People Social Proof Media Contact Stats Menu Courses Listings News Layout CTA ``` ### 4.4 Block HTML Rules #### Rule 1: Self-contained, Bootstrap 5 compatible Each block must render correctly assuming Bootstrap 5 CSS and JS are already loaded. Do not include ``, ``, ``, or `` tags. Do not embed ` ``` **Why `display:none` works:** A ` ``` **Step 6 — Assemble the foundation block** ```json { "id": "xxx-styles", "name": "⚠ Template Styles (Required)", "desc": "MUST be the first block on every page. Contains all [Template Name] CSS. Add this once before all other blocks.", "icon": "🎨", "category": "Layout", "thumbnail": null, "html": "" } ``` #### What NOT to embed | Do NOT include | Reason | |----------------|--------| | `bootstrap.min.css` | Already loaded by shell — doubles CSS, causes specificity conflicts | | `bootstrap.min.js` | Already loaded by shell | | Bootstrap Icons / Font Awesome CSS | Already loaded by shell | | JavaScript | Use a separate hidden `

` block only if a plugin JS is genuinely needed | #### Critical usage rule The `xxx-styles` block **must be the first block on every page** that uses this template's blocks. Without it, all other blocks render as completely unstyled HTML. Make this unmissable in the block name and description. --- ## 5. Standard Block Set For **native templates**, standard content blocks: | # | Block ID | Category | Key tokens used | |---|----------|----------|-----------------| | 1 | `tN-hero` | Hero | `{{PORTAL_NAME}}`, `{{PORTAL_TAGLINE}}`, `{{PRIMARY_COLOR}}` | | 2 | `tN-about` | About | `{{PORTAL_NAME}}`, `{{PORTAL_TAGLINE}}` | | 3 | `tN-services` | Features | `{{PRIMARY_COLOR}}`, `{{SECONDARY_COLOR}}` | | 4 | `tN-contact` | Contact | `{{CONTACT_EMAIL}}`, `{{CONTACT_PHONE}}`, `{{CONTACT_ADDRESS}}` | | 5 | `tN-cta` | CTA | `{{PORTAL_NAME}}`, `{{PRIMARY_COLOR}}` | | 6 | `tN-stats` | Stats | `{{PRIMARY_COLOR}}` | | 7 | `tN-team` | People | — | | 8 | `tN-testimonials` | Social Proof | — | For **third-party templates**, add a block #0 before all content: | # | Block ID | Category | Key tokens used | Notes | |---|----------|----------|-----------------|-------| | 0 | `xxx-styles` | Layout | `{{PRIMARY_COLOR}}`, `{{SECONDARY_COLOR}}`, `{{FONT_FAMILY}}`, `{{FONT_FAMILY_URL}}` | Required first block on every page | --- ## 6. Complete `blocks.json` Examples ### Native template block ```json { "id": "t9-hero", "name": "Hero — Dark Overlay", "desc": "Full-width hero with dark background image, large heading, tagline and two CTA buttons.", "icon": "🌌", "category": "Hero", "thumbnail": null, "html": "

\n Get Started\n

" } ``` ### Third-party template — styles foundation block ```json { "id": "waso-styles", "name": "⚠ Template Styles (Required)", "desc": "MUST be the first block on every page. Contains all Waso Strategy CSS. Add once before any other Waso blocks.", "icon": "🎨", "category": "Layout", "thumbnail": null, "html": "" } ``` --- ## 7. Step-by-Step Integration Checklist ### Step 1 — Assign a template ID Pick the next available ID. Check `data/db.json` under `templates.seed` for existing IDs. Example: `t009`. ### Step 2 — Create the folder ``` templates/t009/ ├── template.html └── blocks.json ``` ### Step 3 — Adapt `template.html` **If building from scratch (native):** 1. Write HTML shell with `{{TAGS}}`, CSS with `.tN-` prefixes. 2. Add `showPage(slug)` and `.page-section` visibility CSS. **If working from a purchased/third-party template:** 1. Keep original HTML structure and class names. 2. Replace navbar content with `{{PORTAL_NAME}}`, `{{NAV_ITEMS_HTML}}`. 3. Replace main content area with `{{SECTIONS_HTML}}`. 4. Replace footer with tokens. 5. Add `showPage(slug)` function and `.page-section { display:none; }` CSS. 6. Add Bootstrap 5 CDN link if not present. 7. **Also embed the template CSS in a `