• Overview
• Components
• Inputs
• Sections
• Events

Sections are predefined horizontal page "slices" that can be inserted in the page.

To add a section you need to use Vvveb.Sections.add method, the first parameter is the unique section name.

The second parameter is an object with the following keys

• name
• image
• html

Example:

Vvveb.Sections.add("bootstrap5/my-section", {
    name: "My custom section",
    image: "https://assets.startbootstrap.com/img/screenshots/snippets/sign-in-split.jpg", //screenshot
    html: `
<section data-name="sigin-split">    
<div class="container-fluid">
  <div class="row no-gutter">
	<h1>My section</h1>
  </div>  
</div>  
`,
});    

A good practice is to have the section html wrapped in a <section> tag, you can also use <header> or <footer>.

Based on this tag the editor will insert the section either at the end of the page for <section> or at the top for <header> and for <footer> after the existing <footer> if there is one already added in the page.

Section group

For a section to be visible in the left panel it needs to be added to a section group, you can do this by including it in the Vvveb.SectionsGroup array using the group name as a key.

For example Bootstrap section group has the following definition.

Vvveb.SectionsGroup['Bootstrap'] = [
  "bootstrap5/signin-split",  
  "bootstrap5/image-gallery", 
  "bootstrap5/video-header", 
  "bootstrap5/slider-header"
];

Automatic generation from html files

Because sections are mostly html code it's easier to maintain them as html files grouped in folders and generate the sections.js file to be included in VvvebJs when changing or adding new sections.

This approach is used in the bundled Landing theme where sections are grouped in folders https://github.com/givanz/landing/tree/main/src/sections

In the theme folder /demo/landing run the following commands to (re)generate sections.

Generate html files

npm run gulp

Watch for changes for development

npm run gulp watch

Generate sections list for VvvebJs page builder

npm run gulp sections

This will generate demo/landing/sections/sections.js file that is included in VvvebJs

Generate blocks list for VvvebJs editor

npm run gulp blocks

Generate screenshots for sections

npm run gulp screenshots

Editor

propertyChange

Called by a input object when the property changes, the editor will listen to this event to update the element when a property changes.

Inputs trigger this event using

new CustomEvent('propertyChange', { detail: {value, input, origEvent} });

vvveb.iframe.loaded

The editor triggers this event after the page/iframe is loaded and the the editor finished setting up the page.

The detail parameter is set to iframe document object.

new CustomEvent("vvveb.iframe.loaded", {detail: self.frameDoc}));

vvveb.getHtml.before

This event is triggered by the Vvveb.Builder.getHtml method before removing helpers and other processing.

new CustomEvent("vvveb.getHtml.before", {detail: document});

Example use by aos plugin to remove classes before page save

//clean aos classes on save
window.addEventListener("vvveb.getHtml.before", function(event) {
	let doc = event.detail;
	doc.querySelectorAll("[data-aos]").forEach(e => e.classList.remove("aos-animate", "aos-init"));
});

vvveb.getHtml.after

This event is triggered by the Vvveb.Builder.getHtml method finished processing the html.

new CustomEvent("vvveb.getHtml.after", {detail: doc}));

Example use by aos plugin to add back classes after page save

window.addEventListener("vvveb.getHtml.after", function(event) {
	let doc = event.detail;
	doc.querySelectorAll("[data-aos]").forEach(e => e.classList.add("aos-animate", "aos-init"));
});		 

vvveb.getHtml.filter

Similar with vvveb.getHtml.after but passes html code instead of document object, used for processing html code instead of manipulating the document.

new CustomEvent("vvveb.getHtml.filter", {detail: html}));

vvveb.ModalCodeEditor.save

Called by the code editor modal with detail set as the value of the editor content.

new CustomEvent("vvveb.ModalCodeEditor.save", {detail: value}));

vvveb.FileManager.deletePage

Called when a page is deleted from file manager, detail parameter is set to page object

Page object structure {name, title, url, file}

new CustomEvent("vvveb.FileManager.deletePage", {detail: page})

vvveb.FileManager.renamePage

Called when a page is renamed from file manager, detail parameter is set to page object and new file name.

Page object structure {name, title, url, file}

new CustomEvent("vvveb.FileManager.renamePage", {detail: {page, newfile}});

vvveb.FileManager.addPage

Called when a new page is added to file manager.

Detail parameter contains an array with page name and page object.

new CustomEvent("vvveb.FileManager.addPage", {detail: [name, data]})

vvveb.FileManager.loadPage

Called when a page is loaded.

Detail parameter contains the page object.

new CustomEvent("vvveb.FileManager.loadPage", {detail: page})

Undo Manager

vvveb.undo.add

Called when a undo action is registered, this happens on a change made to the page

Mutation object has the following structure

let mutation = {
	type: 'style', //style = css change, attributes = attribute change, characterData = text content change, move = element is moved on the page, childList = new node is added to page
	target: element, 
	attributeName: "color", 
	oldValue: "red", 
	newValue: "blue"
}

const event = new CustomEvent("vvveb.undo.add", {detail: mutation});

Example used by code editor to update the page html inside the code editor when a change is made to the page

Vvveb.Builder.frameBody.addEventListener("vvveb.undo.add", () => Vvveb.CodeEditor.setValue());

vvveb.undo.restore

Called when a undo action is restored/reverted

const event = new CustomEvent("vvveb.undo.restore", {detail: mutation});

Example used by code editor to update the page html inside the code editor when a change is made to the page

Vvveb.Builder.frameBody.addEventListener("vvveb.undo.restore", () => Vvveb.CodeEditor.setValue());

To activate pagination, wrap your pagination markup in an element containing:

data-pagination

This container will automatically receive pagination data from the parent component.

Connecting Pagination to a Component

Pagination must know which component it belongs to. This is done using the following attributes:

Example

<div data-pagination
     data-v-parent-component="products"
     data-v-parent-index="0"
     data-v-query-string="true"
     data-v-parameters='{"type":"post","myparam":"value"}'>

This ensures the pagination controls update the correct component and preserve or extend URL parameters.

Pagination Data Attributes

The pagination container receives several dynamic values:

These values can be used to show page indicators, disable buttons, or highlight the active page.

Page Elements

Pagination uses several repeatable or conditional elements to build navigation.

Page List Items

Each page number is wrapped in:

data-page

Inside it, you can use:

• data-page-url — URL for that page
• data-page-no — Page number

Example:

<li data-page>
  <a data-page-url data-page-no href="/shop/2">2</a>
</li>

First Page

Rendered only when the current page is not the first.

<li data-first>
  <a data-page-url>First</a>
</li>

Previous Page

Rendered only when current_page > 1.

<li data-prev>
  <a data-page-url title="Previous page">
    <span class="la la-arrow-left"></span>
  </a>
</li>

Next Page

Rendered only when current_page < pagecount.

<li data-next>
  <a data-page-url title="Next page">
    <span class="la la-arrow-right"></span>
  </a>
</li>

Last Page

Rendered only when the current page is not the last.

<li data-last>
  <a data-page-url>Last</a>
</li>

Full Pagination Example

<div data-pagination
     data-v-parent-component="products"
     data-v-parent-index="0"
     data-v-query-string="true"
     data-v-parameters="{}">

  <nav data-v-if="pagecount > 1">
    <ul>

      <!-- Previous -->
      <li class="page-item pager-prev" data-prev>
        <a data-page-url data-v-if="current_page > 1" title="Previous page">
          <span class="la la-arrow-left la-lg"></span>
        </a>
      </li>

      <!-- Page Numbers -->
      <li class="active" data-page>
        <a data-page-url data-page-no href="/shop">1</a>
      </li>

      <li data-page>
        <a data-page-url data-page-no href="/shop/2">2</a>
      </li>

      <li data-page>
        <a data-page-url data-page-no href="/shop/3">3</a>
      </li>

      <li data-page>
        <a data-page-url data-page-no href="/shop/4">4</a>
      </li>

      <!-- Next -->
      <li data-next>
        <a data-page-url data-v-if="current_page < pagecount" title="Next page">
          <span class="la la-arrow-right la-lg"></span>
        </a>
      </li>

    </ul>
  </nav>

</div>

This example shows a typical pagination block with previous/next arrows and numbered pages.

How Pagination Works Internally

• The parent component (posts, products, comments, etc.) calculates:
  • total items
  • items per page
  • total pages
  • current page
• Pagination receives these values and generates:
  • page links
  • first/prev/next/last controls
  • URLs with preserved or extended query parameters
• When a user clicks a page link, the component reloads with the new page number.

The users component displays a list of useristrator users. It supports pagination, filtering, and searching, making it useful for author listings, team pages, or user management sections within a theme.

Component Options

Add any option as an HTML attribute using the data-v-* syntax.

• start - Starting offset for pagination. Useful when manually controlling the list position.
• limit - Number of user users to display per page.
• status - Filter by account status (1 for enabled, 0 for disabled).
• search - Search by username, first name, or last name.
• user_id - Filter by one or more user IDs. Accepts a single value or a comma‑separated list.

These options allow you to build flexible user listings, from simple team pages to filtered author directories.

Component Properties

Each user user is wrapped in an element marked with data-v-user.
Inside each element, the following properties are available:

• first_name - data-v-user-first_name - User’s first name.
• last_name - data-v-user-last_name - User’s last name.
• avatar_url - data-v-user-avatar_url - Profile avatar image URL.
• cover_url - data-v-user-cover_url - Cover or background image URL.
• url - data-v-user-url - Public profile page URL.
• username - data-v-user-username - Username used for login.
• display_name - data-v-user-display_name - Public display name.
• website - data-v-user-website - Personal or professional website.
• email - data-v-user-email - Internal email for login and notifications.
• public_email - data-v-user-public_email - Publicly visible email address.
• bio - data-v-user-bio - Short biography or description.
• created_at - data-v-user-created_at - Account creation timestamp.
• updated_at - data-v-user-updated_at - Last update timestamp.
• last_ip - data-v-user-last_ip - Last login IP address.
• phone_number - data-v-user-phone_number - Public phone number (if provided).

These properties repeat for each user returned by the component.

HTML Example

<div data-v-component-users data-v-limit="4">

	<div data-v-user>

		<div class="profile-header">
			<div class="cover">
				<img src="" data-v-user-cover_url>
			</div>

			<div class="avatar">
				<img data-v-user-avatar_url class="rounded-circle avatar" alt="Profile Picture">
			</div>
		</div>

		<div class="px-3 m-3 me-5 d-flex justify-content-between">
			<div>
				<h1 class="h3 m-0" data-v-user-display_name>User</h1>
			</div>

			<div class="social-links d-inline-block">
				<!-- Optional social links -->
			</div>
		</div>

		<div class="px-3 m-3 me-5 d-flex">

			<div>
				<div class="text-muted">@<span data-v-user-username>username</span></div>

				<div>
					<a class="d-block" data-v-user-website href="#">
						<span data-v-user-website>example.com</span>
					</a>

					<a class="d-block text-body small" href="#">
						<span data-v-user-public_email>user@vvveb.com</span>
					</a>

					<a class="d-block text-body small" href="#">
						<span data-v-user-phone_number>123456</span>
					</a>
				</div>
			</div>

			<div class="ms-5">
				<div data-v-user-bio>My bio</div>
			</div>

		</div>

	</div>

</div>

This example displays a list of up to four user users, each rendered using the available user properties.

Activate the component by adding:

data-v-component-user-address

The component automatically loads the addresses of the logged‑in user unless a specific user_id is provided.

Component Options

Options are added as HTML attributes using the data-v-* syntax.

These options allow you to paginate, filter, or override which user’s addresses are displayed.

Component Properties

Each address is wrapped in:

data-v-user_address

Inside this element, the following fields are available.

Address Identity

Name & Company

Address Fields

These fields can be combined to display a formatted address block.

Custom Fields

Actions & URLs

These URLs are typically used for buttons or links in the address list.

HTML Example

<div data-v-component-user-address>            
<table>
  <tbody>
	<tr data-v-user_address>
	  <td class="text-start">

		<span data-v-user_address-first_name>John</span>
		<span data-v-user_address-last_name>Doe</span>
		<br>
		<span data-v-user_address-company>Toyota</span>
		<br>
		<span data-v-user_address-address_1>Broadway Avenue</span>
		<span data-v-user_address-address_2>Central Park</span>
		<span data-v-user_address-city>New york</span>
		<span data-v-user_address-post_code>1223</span>

	  </td>
	  <td class="text-end align-middle">
		<a href="/user/address/edit/1" title="Edit" class="btn btn-outline-primary btn-sm border-0" data-v-user_address-url>
		  <i class="la la-pen"></i>
		</a>
		<a href="/user/address/delete/1" title="Delete" class="btn btn-outline-danger btn-sm border-0" data-v-user_address-delete-url>
		  <i class="la la-trash"></i>
		</a>
	  </td>
	</tr>                              
	</tbody>
</table>
</div>

This example displays each saved address with edit and delete actions, making it suitable for a user account dashboard.

| | model | String | Product model identifier.

| | sku | String | Stock Keeping Unit.

| | price | Float | The current price of the product.

| | old_price | Float | The original price (useful for showing discounts).

| | stock_quantity | Int | Number of items currently in stock.

| | image | String | Path to the main product image.

| | weight | Float | Physical weight for shipping calculations.

| | variants | [ProductVariantType] | Available variations (size, color, etc.).

| | contents | [ProductContentType] | Localized names and descriptions.

|

2. Cart (cart)

Represents a user's active shopping session.

| | products | [CartProductType] | List of items currently in the cart.

| | totals | [TotalType] | Breakdown of subtotal, tax, and shipping.

| | total_price | Float | The grand total amount.

| | total_formatted | String | Currency-formatted total string.

| | checkout_url | String | Direct link to the checkout page.

|

📝 Content & Blogging

1. Post (post)

Used for blog articles, news, or generic CMS pages.

| | status | String | The post status (e.g., "published", "draft").

| | comment_count | Int | Total number of approved comments.

| | created_at | String | Timestamp of post creation.

| | contents | [PostContentType] | Multi-language content (title, body, slug).

| | seo | [SeoType] | Metadata for search engine optimization.

|

2. Media (media)

Represents uploaded assets like images and videos.

| | file | String | The file path or URL.

| | type | String | MIME type or category (image, video, etc.).

|

💳 Orders & Customers

Order (order)

A finalized transaction containing snapshot data of the purchase.

Identifiers: Includes order_id, invoice_no, and customer_order_id.

Customer Info: Stores first_name, last_name, email, and phone_number.

Shipping/Billing: Comprehensive address fields including address_1, city, post_code, and country_id.

Financials: Tracks payment_method, shipping_method, total, and currency_id.

Associations: Links to products, shipments, subscriptions, and vouchers.

🛠️ System & Configuration

Localization: Supported via language (codes, locales, RTL support) and currency (symbols, decimal places, exchange values).

Geography: country data including ISO codes and status.

Administration: admin type manages backend users, including role_id, auth_tokens, and failed_logins.

Marketing: coupon management (discount types, usage limits, date ranges) and newsletter_list management.

Customization: field and field_group allow for extensible data models across posts and products.

Pro Tip: Localized Content

Most primary entities (Product, Post, Category) do not store names directly. Instead, they use a contents array (e.g., ProductContentType) which maps content to a specific language_id. Always query the contents field to retrieve the correct translation for your frontend.

Component Options

Add any option as an HTML attribute using the data-v-* syntax.

• admin_id - Loads the admin user with this ID. If set to url, the component will read the admin_id from the URL query string. This is useful for author profile pages where the admin ID is dynamic.
• username - Loads the admin user with this username. If set to url, the component will read the username from the URL query string.

Only one of these options is required. If both are omitted, the component displays the currently authenticated admin user.

Component Properties

The following properties are available inside the component. Each property can be used with its corresponding data-v-admin-* attribute.

• first_name - data-v-admin-first_name - Admin’s first name.
• last_name - data-v-admin-last_name - Admin’s last name.
• avatar_url - data-v-admin-avatar_url - URL of the admin’s profile avatar.
• cover_url - data-v-admin-cover_url - URL of the admin’s cover/background image.
• url - data-v-admin-url - Link to the admin’s public profile page.
• username - data-v-admin-username - Admin’s username.
• display_name - data-v-admin-display_name - Public display name.
• website - data-v-admin-website - Personal or professional website.
• email - data-v-admin-email - Internal email used for login and notifications.
• public_email - data-v-admin-public_email - Publicly visible email address.
• bio - data-v-admin-bio - Short biography or description.
• created_at - data-v-admin-created_at - Account creation timestamp.
• updated_at - data-v-admin-updated_at - Last update timestamp.
• role_id - data-v-admin-role_id - Role ID assigned to the admin.
• role - data-v-admin-role - Role name (e.g., Administrator, Editor).
• last_ip - data-v-admin-last_ip - Last login IP address.
• phone_number - data-v-admin-phone_number - Public phone number (if provided).

HTML Example

<div data-v-component-admin data-v-admin_id="url" class="profile">

	<div data-v-if="admin">

		<div class="profile-header">
			<div class="cover">
				<img src="" data-v-admin-cover_url>
			</div>

			<div class="avatar">
				<img data-v-admin-avatar_url class="rounded-circle avatar" alt="Profile Picture">
			</div>
		</div>

		<div class="px-3 m-3 me-5 d-flex justify-content-between">
			<div>
				<h1 class="h3 m-0" data-v-admin-display_name>User</h1>
			</div>

			<div class="social-links d-inline-block">
				<!-- Optional social links -->
			</div>
		</div>

		<div class="px-3 m-3 me-5 d-flex">

			<div>
				<div class="text-muted">@<span data-v-admin-username>username</span></div>

				<div>
					<a class="d-block" data-v-admin-website href="#">
						<span data-v-admin-website>example.com</span>
					</a>

					<a class="d-block text-body small" href="#">
						<span data-v-admin-public_email>admin@vvveb.com</span>
					</a>

					<a class="d-block text-body small" href="#">
						<span data-v-admin-phone_number>123456</span>
					</a>
				</div>
			</div>

			<div class="ms-5">
				<div data-v-admin-bio>My bio</div>
			</div>

		</div>

	</div>

</div>

This example loads the admin profile based on the admin_id found in the URL. All admin details are displayed using the component’s data attributes.

The admins component displays a list of administrator users. It supports pagination, filtering, and searching, making it useful for author listings, team pages, or admin management sections within a theme.

Component Properties

Each admin user is wrapped in an element marked with data-v-admin.
Inside each element, the following properties are available:

• first_name — data-v-admin-first_name — Admin’s first name.
• last_name — data-v-admin-last_name — Admin’s last name.
• avatar_url — data-v-admin-avatar_url — Profile avatar image URL.
• cover_url — data-v-admin-cover_url — Cover or background image URL.
• url — data-v-admin-url — Public profile page URL.
• username — data-v-admin-username — Username used for login.
• display_name — data-v-admin-display_name — Public display name.
• website — data-v-admin-website — Personal or professional website.
• email — data-v-admin-email — Internal email for login and notifications.
• public_email — data-v-admin-public_email — Publicly visible email address.
• bio — data-v-admin-bio — Short biography or description.
• created_at — data-v-admin-created_at — Account creation timestamp.
• updated_at — data-v-admin-updated_at — Last update timestamp.
• role_id — data-v-admin-role_id — Role ID assigned to the admin.
• role — data-v-admin-role — Role name (e.g., Administrator, Editor).
• last_ip — data-v-admin-last_ip — Last login IP address.
• phone_number — data-v-admin-phone_number — Public phone number (if provided).

These properties repeat for each admin returned by the component.

HTML Example

<div data-v-component-admins data-v-limit="4">

	<div data-v-admin>

		<div class="profile-header">
			<div class="cover">
				<img src="" data-v-admin-cover_url>
			</div>

			<div class="avatar">
				<img data-v-admin-avatar_url class="rounded-circle avatar" alt="Profile Picture">
			</div>
		</div>

		<div class="px-3 m-3 me-5 d-flex justify-content-between">
			<div>
				<h1 class="h3 m-0" data-v-admin-display_name>User</h1>
			</div>

			<div class="social-links d-inline-block">
				<!-- Optional social links -->
			</div>
		</div>

		<div class="px-3 m-3 me-5 d-flex">

			<div>
				<div class="text-muted">@<span data-v-admin-username>username</span></div>

				<div>
					<a class="d-block" data-v-admin-website href="#">
						<span data-v-admin-website>example.com</span>
					</a>

					<a class="d-block text-body small" href="#">
						<span data-v-admin-public_email>admin@vvveb.com</span>
					</a>

					<a class="d-block text-body small" href="#">
						<span data-v-admin-phone_number>123456</span>
					</a>
				</div>
			</div>

			<div class="ms-5">
				<div data-v-admin-bio>My bio</div>
			</div>

		</div>

	</div>

</div>

This example displays a list of up to four admin users, each rendered using the available admin properties.

Component Properties

Inside the component, the following repeatable post properties are available. Each post is wrapped in an element marked with data-v-post.

• name — data-v-post-name — Post title.
• content — data-v-post-content — Post content.
• excerpt — data-v-post-excerpt — Post excerpt.
• status — data-v-post-status — Post status (publish, disabled, scheduled).
• image — data-v-post-image — Main post image.
• slug — data-v-post-url — Post slug.
• url — data-v-post-url — Post detail page URL.
• meta_keywords — data-v-post-meta_keywords — Post meta keywords.
• meta_description — data-v-post-meta_description — Post meta description.
• type — data-v-post-type — Post type, default is post.
• password — data-v-post-password — Post password if is password protected.
• comment_status — data-v-post-comment_status — Post comment status, if comments are allowed or disabled
• comment_count — data-v-post-comment_count — Number of comments on the post
• views — data-v-post-comment_count — Number of views on the post
• sort_order — data-v-post-sort_order — Post sort order.
• template — data-v-post-template — Template used to render the post if a different template is used.

These properties repeat for each post returned by the component.

HTML Example

<div data-v-component-posts 
     data-v-limit="10" 
     data-v-page="2">

    <div data-v-post>
        <a href="#" data-v-post-url>
			<span data-v-post-name>Post name placeholder</span>
		</a>
        
        <span data-v-post-excerpt>Lorem ipsum</span>
        <span data-v-post-content>Lorem ipsum</span>
        
        <img src="" data-v-post-image>
        
        <a href="#" data-v-post-url>View post</a>
    </div>

</div>

This example loads 10 posts from page 2, without including the image gallery. Each post is rendered inside the data-v-post block.

Component Properties

Each breadcrumb item is rendered inside an element marked with data-v-breadcrumb-item. The following properties are available for each item:

• text — data-v-breadcrumb-item-text — The visible label of the breadcrumb item.
• url — data-v-breadcrumb-item-url — The link for the breadcrumb item. If empty, the item is displayed as plain text (typically the current page).

The component repeats these properties for every breadcrumb segment, from the homepage to the current page.

HTML Example

<nav aria-label="breadcrumb" class="text-muted text-small" data-v-component-breadcrumb>
  <ol class="breadcrumb">

    <li class="breadcrumb-item" data-v-breadcrumb-item>
      <a data-v-breadcrumb-item-url data-v-if="breadcrumb.url">
        <span data-v-breadcrumb-item-text>Home</span>
      </a>
      <span data-v-breadcrumb-item-text data-v-if-not="breadcrumb.url">Home</span>
    </li>

    <li class="breadcrumb-item" data-v-breadcrumb-item>
      <a data-v-breadcrumb-item-url data-v-if="breadcrumb.url">
        <span data-v-breadcrumb-item-text>Library</span>
      </a>
      <span data-v-breadcrumb-item-text data-v-if-not="breadcrumb.url">Library</span>
    </li>

    <li class="breadcrumb-item active" aria-current="page" data-v-breadcrumb-item>
      <span data-v-breadcrumb-item-text>Data</span>
    </li>

  </ol>
</nav>

This example shows a typical breadcrumb structure with conditional links: if a breadcrumb item has a URL, it is rendered as a link; otherwise, it appears as plain text (usually the current page).

The users component displays a list of useristrator users. It supports pagination, filtering, and searching, making it useful for author listings, team pages, or user management sections within a theme.

Component Properties

Each user user is wrapped in an element marked with data-v-user.
Inside each element, the following properties are available:

• first_name — data-v-user-first_name — User’s first name.
• last_name — data-v-user-last_name — User’s last name.
• avatar_url — data-v-user-avatar_url — Profile avatar image URL.
• cover_url — data-v-user-cover_url — Cover or background image URL.
• url — data-v-user-url — Public profile page URL.
• username — data-v-user-username — Username used for login.
• display_name — data-v-user-display_name — Public display name.
• website — data-v-user-website — Personal or professional website.
• email — data-v-user-email — Internal email for login and notifications.
• public_email — data-v-user-public_email — Publicly visible email address.
• bio — data-v-user-bio — Short biography or description.
• created_at — data-v-user-created_at — Account creation timestamp.
• updated_at — data-v-user-updated_at — Last update timestamp.
• last_ip — data-v-user-last_ip — Last login IP address.
• phone_number — data-v-user-phone_number — Public phone number (if provided).

These properties repeat for each user returned by the component.

HTML Example

<div data-v-component-users data-v-limit="4">

	<div data-v-user>

		<div class="profile-header">
			<div class="cover">
				<img src="" data-v-user-cover_url>
			</div>

			<div class="avatar">
				<img data-v-user-avatar_url class="rounded-circle avatar" alt="Profile Picture">
			</div>
		</div>

		<div class="px-3 m-3 me-5 d-flex justify-content-between">
			<div>
				<h1 class="h3 m-0" data-v-user-display_name>User</h1>
			</div>

			<div class="social-links d-inline-block">
				<!-- Optional social links -->
			</div>
		</div>

		<div class="px-3 m-3 me-5 d-flex">

			<div>
				<div class="text-muted">@<span data-v-user-username>username</span></div>

				<div>
					<a class="d-block" data-v-user-website href="#">
						<span data-v-user-website>example.com</span>
					</a>

					<a class="d-block text-body small" href="#">
						<span data-v-user-public_email>user@vvveb.com</span>
					</a>

					<a class="d-block text-body small" href="#">
						<span data-v-user-phone_number>123456</span>
					</a>
				</div>
			</div>

			<div class="ms-5">
				<div data-v-user-bio>My bio</div>
			</div>

		</div>

	</div>

</div>

This example displays a list of up to four user users, each rendered using the available user properties.

Component Properties

Inside the component, the following repeatable product properties are available. Each product is wrapped in an element marked with data-v-product.

• name — data-v-product-name — Product name.
• content — data-v-product-content — Product description or content.
• price — data-v-product-price — Product price.
• image — data-v-product-image — Main product image.
• images — data-v-product-images — Product gallery images.
• url — data-v-product-url — Product detail page URL.

These properties repeat for each product returned by the component.

HTML Example

<div data-v-component-products 
     data-v-limit="10" 
     data-v-page="2" 
     data-v-order="price"
     data-v-direction="asc"
     data-v-include_image_gallery="false">

    <div class="product-card" data-v-product>
        <img src="/placeholder.jpg" data-v-product-image alt="Product Image">
        
        <h3 data-v-product-name>Product Name Placeholder</h3>
        <p data-v-product-content>Short description goes here...</p>
        
        <span class="price" data-v-product-price>$0.00</span>
        
        <a href="#" data-v-product-url class="button">View Product</a>
    </div>
    
    <div data-v-if-not="products">
        <p>No products match your criteria.</p>
    </div>
</div>

This example loads 10 products from page 2, without including the image gallery. Each product is rendered inside the data-v-product block.

Component Properties

The following properties are available inside the component. Each property can be used with its corresponding data-v-admin-* attribute.

• first_name — data-v-admin-first_name — Admin’s first name.
• last_name — data-v-admin-last_name — Admin’s last name.
• avatar_url — data-v-admin-avatar_url — URL of the admin’s profile avatar.
• cover_url — data-v-admin-cover_url — URL of the admin’s cover/background image.
• url — data-v-admin-url — Link to the admin’s public profile page.
• username — data-v-admin-username — Admin’s username.
• display_name — data-v-admin-display_name — Public display name.
• website — data-v-admin-website — Personal or professional website.
• email — data-v-admin-email — Internal email used for login and notifications.
• public_email — data-v-admin-public_email — Publicly visible email address.
• bio — data-v-admin-bio — Short biography or description.
• created_at — data-v-admin-created_at — Account creation timestamp.
• updated_at — data-v-admin-updated_at — Last update timestamp.
• role_id — data-v-admin-role_id — Role ID assigned to the admin.
• role — data-v-admin-role — Role name (e.g., Administrator, Editor).
• last_ip — data-v-admin-last_ip — Last login IP address.
• phone_number — data-v-admin-phone_number — Public phone number (if provided).

HTML Example

<div data-v-component-admin data-v-admin_id="url" class="profile">

	<div data-v-if="admin">

		<div class="profile-header">
			<div class="cover">
				<img src="" data-v-admin-cover_url>
			</div>

			<div class="avatar">
				<img data-v-admin-avatar_url class="rounded-circle avatar" alt="Profile Picture">
			</div>
		</div>

		<div class="px-3 m-3 me-5 d-flex justify-content-between">
			<div>
				<h1 class="h3 m-0" data-v-admin-display_name>User</h1>
			</div>

			<div class="social-links d-inline-block">
				<!-- Optional social links -->
			</div>
		</div>

		<div class="px-3 m-3 me-5 d-flex">

			<div>
				<div class="text-muted">@<span data-v-admin-username>username</span></div>

				<div>
					<a class="d-block" data-v-admin-website href="#">
						<span data-v-admin-website>example.com</span>
					</a>

					<a class="d-block text-body small" href="#">
						<span data-v-admin-public_email>admin@vvveb.com</span>
					</a>

					<a class="d-block text-body small" href="#">
						<span data-v-admin-phone_number>123456</span>
					</a>
				</div>
			</div>

			<div class="ms-5">
				<div data-v-admin-bio>My bio</div>
			</div>

		</div>

	</div>

</div>

This example loads the admin profile based on the admin_id found in the URL. All admin details are displayed using the component’s data attributes.

Component Properties

The following properties are available inside the component. Each property can be used with its corresponding data-v-user-* attribute.

• first_name — data-v-user-first_name — Admin’s first name.
• last_name — data-v-user-last_name — Admin’s last name.
• avatar_url — data-v-user-avatar_url — URL of the user’s profile avatar.
• cover_url — data-v-user-cover_url — URL of the user’s cover/background image.
• url — data-v-user-url — Link to the user’s public profile page.
• username — data-v-user-username — Admin’s username.
• display_name — data-v-user-display_name — Public display name.
• website — data-v-user-website — Personal or professional website.
• email — data-v-user-email — Internal email used for login and notifications.
• public_email — data-v-user-public_email — Publicly visible email address.
• bio — data-v-user-bio — Short biography or description.
• created_at — data-v-user-created_at — Account creation timestamp.
• updated_at — data-v-user-updated_at — Last update timestamp.
• role_id — data-v-user-role_id — Role ID assigned to the user.
• role — data-v-user-role — Role name (e.g., Administrator, Editor).
• last_ip — data-v-user-last_ip — Last login IP address.
• phone_number — data-v-user-phone_number — Public phone number (if provided).

HTML Example

<div data-v-component-user data-v-user_id="url" class="profile">

	<div data-v-if="user">

		<div class="profile-header">
			<div class="cover">
				<img src="" data-v-user-cover_url>
			</div>

			<div class="avatar">
				<img data-v-user-avatar_url class="rounded-circle avatar" alt="Profile Picture">
			</div>
		</div>

		<div class="px-3 m-3 me-5 d-flex justify-content-between">
			<div>
				<h1 class="h3 m-0" data-v-user-display_name>User</h1>
			</div>

			<div class="social-links d-inline-block">
				<!-- Optional social links -->
			</div>
		</div>

		<div class="px-3 m-3 me-5 d-flex">

			<div>
				<div class="text-muted">@<span data-v-user-username>username</span></div>

				<div>
					<a class="d-block" data-v-user-website href="#">
						<span data-v-user-website>example.com</span>
					</a>

					<a class="d-block text-body small" href="#">
						<span data-v-user-public_email>user@vvveb.com</span>
					</a>

					<a class="d-block text-body small" href="#">
						<span data-v-user-phone_number>123456</span>
					</a>
				</div>
			</div>

			<div class="ms-5">
				<div data-v-user-bio>My bio</div>
			</div>

		</div>

	</div>

</div>

This example loads the user profile based on the user_id found in the URL. All user details are displayed using the component’s data attributes.

With Vtpl, templates are simply lists of rules that map:

CSS selector  →  PHP variable or PHP code

Because the HTML remains untouched, designers can modify layouts freely while developers maintain logic independently. This approach enables systems like Vvveb CMS, where any HTML file can be replaced or redesigned without breaking dynamic content rendering.

Including HTML from Other Templates

Vtpl supports reusing HTML fragments using the from directive. This is useful for shared elements like headers, footers, or repeated UI blocks.

div#top > div.header = from(homepage.html|div#top > div.header)

If no selector is provided, Vtpl assumes the same selector (eg div#top > div.header):

div#top > div.header = from(homepage.html)

This ensures consistent markup across templates without duplicating HTML.

Modifiers

Modifiers change how Vtpl inserts content into the selected elements.

innerHTML (default)

Replaces the inside of the element.

div#id > span.title = "Lorem ipsum"
div#id > span.title|innerHTML = "Lorem ipsum"

outerHTML

To replace the entire elements with the specified code use outerHTML modifier

div#id > span.title|outerHTML = "Lorem ipsum"

innerText

To replace only the first text inside element but leave other elements intact

div#id > span.title|innerText = "Lorem ipsum"

before

Inserts content before the element.

div#id > span.class a|before = "lorem ipsum"

prepend

Inserts content at the beginning of the element.

div#id > span.class a|prepend = "lorem ipsum"

after

Inserts content after the element.

div#id > span.class a|after = "lorem ipsum"

append

Inserts content at the end of the element.

div#id > span.class a|append = "lorem ipsum"

deleteAllButFirst

Keeps only the first matched element, useful when designers include multiple mock elements but we only need one to iterate.

div.items a|deleteAllButFirst

Example:

<!-- Original -->
<div class="items">
  <a href="#">1</a>
  <a href="#">2</a>
  <a href="#">3</a>
</div>

<!-- After deleteAllButFirst -->
<div class="items">
  <a href="#">1</a>
</div<

hide (conditional rendering)

Removes elements if a variable is empty or false.

div.articles|if_exists = $articles

delete

Removes the selected elements entirely.

div.ad-banner|delete

Attribute insert

To modify an attribute, specify it as a modifier:

a.button|href = $url
a.button|title = "Go to page"

Additional Commands

import

Includes another Vtpl file. Useful for splitting large templates into smaller, maintainable parts.

import(profile/activity_tab.tpl)

Comments

Vtpl supports both single‑line and multi‑line comments:

// Single line comment

/* 
Multi-line
comment
*/

Debugging

Enable debugging inside a Vtpl file:

debug = true

Disable it:

debug = false

When debugging is enabled, Vtpl outputs a list of all template inserts, helping you understand exactly how the HTML was transformed.

Vtpl’s CSS‑selector‑based approach keeps HTML clean, separates logic from presentation, and makes large CMS systems easier to theme and maintain.

The Rest API allows external applications, such as mobile apps, static site generators, or headless frontends, to read and modify content stored in Vvveb CMS.

It is disabled by default for security, and must be explicitly enabled before use.

Once active, the API exposes posts, products, users, taxonomies, and other resources through clean, predictable endpoints.

Enabling the Rest API

The API is turned off by default. To enable it, edit env.php and set the REST constant to true:

defined('REST') || define('REST', true);

If you do not have direct access to server files, you can enable it using the File manager plugin, available in the plugin marketplace.

Authentication

All API requests require authentication. Vvveb supports two methods:

• Bearer tokens
• HTTP Basic Authentication (username and password)

Any admin user with the appropriate REST permissions can authenticate.

Bearer token example

curl -H 'Authorization: Bearer mytoken' 'https://demo.vvveb.com/rest/posts/hello-world-1'

Basic auth example

curl --user demo:demo 'https://demo.vvveb.com/rest/posts/hello-world-1'

Authentication is required for both reading and writing data unless a plugin or custom configuration explicitly exposes public endpoints.

Permissions and Access Control

Access to API resources is controlled through admin roles. Permissions can be granted or restricted per:

• Resource (posts, products, users, etc.)
• Action (read, write, update, delete)

This ensures that only authorized users or applications can perform sensitive operations.

OpenAPI Documentation

Interactive API documentation is available through the Open Api plugin, which automatically generates:

• Endpoint lists
• Request/response schemas
• Authentication examples
• Live testing interface

This is the recommended way to explore the full API surface.

Next.js Starter Project

A ready‑to‑use example project is available for developers building headless frontends with Next.js. It demonstrates:

• Fetching posts via the REST API
• Rendering content statically or dynamically
• Using Vvveb as a headless CMS

GitHub repository:
https://github.com/givanz/nextjs-headless-rest-vvveb

Live demo:
https://nextjs-headless-rest-vvveb.vercel.app/

The Rest API turns Vvveb into a flexible headless CMS, making it easy to integrate with modern frameworks and external applications.

File Structure

SQL definitions are stored based on the database engine to ensure cross-compatibility: app/sql/{db-engine}/{filename}.sql

• db-engine: mysqli, pgsql, or sqlite.
• Automatic Generation: For every .sql file, Vvveb generates a corresponding PHP class on the fly (e.g., product.sql becomes ProductSQL class).

Procedure Definition

Procedures are defined using a syntax similar to standard SQL CREATE PROCEDURE, but they include special IN and OUT parameters to handle PHP data mapping.

PROCEDURE getAll(
		IN product_id INT,
		IN slug CHAR,
		IN language_id INT,
		OUT fetch_row, 
		OUT fetch_all, 
		OUT fetch_one,
		OUT insert_id,
		OUT affected_rows
	)
	BEGIN
	END

Parameter Types

Output Types (OUT)

• fetch_all: Returns an array of all matching rows.
• fetch_row: Returns a single associative array (for LIMIT 1).
• fetch_one: Returns a single scalar value (e.g., a count or a specific column).
• insert_id: Returns the ID generated by the last INSERT statement.
• affected_rows: Returns the number of rows modified by UPDATE or DELETE.

SQL Example (product.sql)

-- Products

	-- get one product

	CREATE PROCEDURE get(
		IN product_id INT,
		IN slug CHAR,
		OUT fetch_row 
	)
	BEGIN
		-- product
		SELECT *
			FROM product as _ -- (underscore) _ means that data will be kept in main array
		WHERE 1 = 1 

		@IF isset(:product_id)
		THEN
			AND product_id = :product_id
		END @IF				
		
		@IF isset(:slug)
		THEN
			AND slug = :slug
		END @IF	

		LIMIT 1;	

	END
	

	-- Edit product

	CREATE PROCEDURE edit(
		IN product ARRAY,
		IN product_id INT,
		OUT affected_rows
	)
	BEGIN

		-- SELECT * FROM product_option WHERE product_id = :product_id;

		-- allow only table fields and set defaults for missing values
		@FILTER(:product, product);
		
		UPDATE product 
			
			SET @LIST(:product) 
			
		WHERE product_id = :product_id
	END	


	-- Add new product

	CREATE PROCEDURE add(
		IN product ARRAY,
		IN site_id INT,
		OUT insert_id,
		OUT insert_id
	)
	BEGIN
		
		-- allow only table fields and set defaults for missing values
		:product  = @FILTER(:product, product);

		INSERT INTO product 
		
			( @KEYS(:product) )
			
		VALUES ( :product );
		
		INSERT INTO product_to_site 
		
			( product_id, site_id )
			
		VALUES ( @result.product, :site_id );
			

	END


	-- get all products 

	CREATE PROCEDURE getAll(

		-- variables
		IN  language_id INT,
		IN  user_group_id INT,
		IN  site_id INT,
		IN  search CHAR,
		
		-- pagination
		IN  start INT,
		IN  limit INT,
			
		-- return array of products for products query
		OUT fetch_all,
		-- return products count for count query
		OUT fetch_one,
	)
	BEGIN

		SELECT * FROM product AS product
		
			LEFT JOIN product_to_site p2s ON (product.product_id = p2s.product_id) 
			WHERE p2s.site_id = :site_id

			@IF isset(:search)
			THEN 
			
				AND name LIKE :search
				
			END @IF			
			
		LIMIT :start, :limit;


		SELECT count(*) FROM (
			
			@SQL_COUNT(product.product_id, product) -- this takes previous query removes limit and replaces select columns with parameter product_id
			
		) as count;


	END


	-- delete product

	CREATE PROCEDURE delete(
		IN  product_id ARRAY,
		OUT affected_rows
	)
	BEGIN

		DELETE FROM product WHERE product_id IN (:product_id)
	 
	END

Will generate a file productsql.mysqli.php with the following structure:

<?php 

/*
Generated from /home/www/vvveb/vvveb/admin/sql/mysqli//product.sql
*/
namespace Vvveb\Sql;

use \Vvveb\System\Db;

class ProductSQL {
	
	function get($params = array()) {
	}		
	
	function edit($params = array()) {
	}		
	
	
	function add($params = array()) {
	}		
	
	function getAll($params = array()) {
	}		
	
	function delete($params = array()) {
	}		

}

PHP Usage

Once the .sql file is saved, use the generated class in your PHP code:

use Vvveb\Sql\ProductSQL;

$db = new ProductSQL();

// Fetch data (returns array/object based on OUT param)
$product = $db->get(['product_id' => 3]);

// Get first 3 products
$data = $product->getAll(['limit' => 3);

// Insert data
$newId = $db->add([
    'product' => ['name' => 'New Camera', 'price' => 599],
    'site_id' => 1
]);

//edit product with product_id = 1
$product->edit(['product' => ['name' => 'Product 2', 'price' => 100], 'product_id' => 1]);

//delete product with product_id = 3
$data = $product->delete(['product_id' => 3);

Macros

SqlP uses custom macros to handle dynamic logic directly within the SQL file.

1. Logic Macros (@IF, @ELSE)

If macro

@IF isset(:product_id)
THEN
	AND product_id = :product_id
END @IF		

With @IF you can conditionally include sql code, the condition is valid native PHP code, you can use any php code with multiple conditions or different functions like

@IF isset(:product_id) AND !empty(:product_id)

If else macro

@IF isset(:product_id)
THEN
	AND product_id = :product_id
@ELSE
	AND product_id = 0
END @IF		

With @IF @ELSE macro

@IF isset(:product_id) AND !empty(:product_id)

2. Helper Macros

• @SQL_COUNT(col, table): Automatically generates a count query based on the preceding SELECT statement, removing limits and optimizing columns.
• @LIST(:array): Expands an array into col1=val1, col2=val2 (ideal for UPDATE).
• @KEYS(:array): Returns a comma-separated list of array keys (ideal for INSERT).
• @SQL_LIMIT(:start, :limit): Handles cross-database syntax differences for pagination.

SQL_COUNT

Use this macro to run sql count for the previous query to avoid duplicating the query code. The macro will automatically replace all the columns (product_id, name) from the query with the first parameter products.product_id, the second parameter is the table name.

	SELECT product_id, name FROM products 
		INNER JOIN product_content pc ON pc.product_id = product.product_id
	WHERE vendor_id = 1; 

	SELECT count(*) FROM (
		
		@SQL_COUNT(products.product_id, product) -- this takes previous query removes limit and replaces select columns with parameter product_id
		
	) as count;

LIST

Will expand the array into a column=value list in the format used by UPDATE queries.

column1=value, column2=value2, column3=value3

UPDATE product 
	SET @LIST(:product_update) 

3. Loop Macro (@EACH)

EACH

Repeats a query for every item in a PHP array, :each is the item in the array

@EACH(:product_digital_asset) 
	INSERT INTO  product_to_digital_asset 

		( digital_asset_id, product_id)
	
	VALUES ( :each, :product_id );

-- example with KEYS macro

@EACH(:product_attribute) 
	INSERT INTO product_attribute 

		( @KEYS(:each), product_id)
	
	VALUES ( :each, :product_id );

KEYS

Keys macro will use the key instead of value for array values similar to php array_keys In the following example

@EACH(:product_attribute) 
	INSERT INTO product_attribute 

		( @KEYS(:each), product_id)
	
	VALUES ( :each, :product_id );

$product_attribute = [1 => ['name' => 'Product 1', 'price' => 30], 2 => 'Product 2', 'price' => 50];

:each will be

'Product 1', '30'

and @KEYS(:each) will be

'name', 'price'

SQL limit

Use this macro to avoid LIMIT syntax differences between pgsql and mysql

@IF isset(:limit)
THEN
	@SQL_LIMIT(:start, :limit)
END @IF;		

array_key and array_value column alias

With array_key and array_value column aliases you can change the format of the returned results to be more compact. Use these aliases to return custom associative arrays instead of standard nested lists.

For example

-- stock status	
SELECT 

	stock_status_id
	name
	
FROM stock_status as stock_status_id;

will return

['stock_status_id' => 
	[	
		0 => ['stock_status_id' => 5, 'name' => 'status 1' ],
		1 => ['stock_status_id' => 8, 'name' => 'status 2' ],
		2 => ['stock_status_id' => 9, 'name' => 'status 3' ]
	]
];		

with the aliases

-- stock status	
SELECT 

	stock_status_id as array_key, -- stock_status_id as key
	name as array_value -- only set name as value and return  
	
FROM stock_status as stock_status_id;

the return data will be

['stock_status_id' => 
	[	
		5 => 'status 1',
		8 => 'status 2',
		9 => 'status 3'
	]
];		

with only array_key alias

-- stock status	
SELECT 

	stock_status_id as array_key, -- stock_status_id as key
	name
	
FROM stock_status as stock_status_id;

the return data will be

['stock_status_id' => 
	[	
		5 => ['stock_status_id' => 5, 'name' => 'status 1' ],
		8 => ['stock_status_id' => 8, 'name' => 'status 2' ],
		9 => ['stock_status_id' => 9, 'name' => 'status 3' ]
	]
];		

Result Formatting & Aliases

_ table alias

By default, SqlP wraps results in an array keyed by the {table name}. Use the _ alias to flatten the result.

• Standard: ['product' => ['name' => 'Phone']]
• With AS _: ['name' => 'Phone']

For example with

-- select example

-- product
SELECT product.*
	FROM product
WHERE product.vendor_id = 1 LIMIT 1;		

The values will be returned in the array using the table name for array key

['product' => [ 
		['name' => 'product 1], 
		['name' => 'product 2], 
	]
]

With the _ alias

-- select example

-- product
SELECT product.*
	FROM product
WHERE product.vendor_id = 1 LIMIT 1;		

The values will be returned without the table name as key and the values will be appended to the array directly

[ 
	['name' => 'product 1], 
	['name' => 'product 2], 
]

@result.table_name

When you need to use a value from a previous query like a last_insert id or a column id you can use @result.table_name

Access data from a previous query within the same procedure.

• @result.table_name: Returns the last insert ID or row from that table.
• @result.column_name: If using the _ alias, access the column value directly.

-- select example

-- product
SELECT product.*
	FROM product
WHERE product.vendor_id = 1 LIMIT 1;		

-- subscription
SELECT product_subscription.*
	FROM product_subscription
WHERE product_subscription.product_id = @result.product;		


-- insert example

-- product

INSERT INTO product 

	( @KEYS(:product_data) )
	
VALUES ( :product_data );

-- subscription
SELECT product_subscription.*
	FROM product_subscription
WHERE product_subscription.product_id = @result.product;		

When you use _ for table name alias because values are in the top level array you can use @result.column_name directly

-- select example

-- product
SELECT product.*
	FROM product AS _
WHERE product.vendor_id = 1 LIMIT 1;		

-- subscription
SELECT product_subscription.*
	FROM product_subscription
WHERE product_subscription.product_id = @result.product_id;		

Themes are located in public/themes/my-theme-name

For pages like post or product to properly load the correct html file, you need to properly name and group your html files in the following structure.

Folder and files structure

• ├── index.html - default template used for homepage
• ├── index.coming-soon.html - homepage when site is set to coming soon
• ├── index.maintenance.html - homepage when site is set to maintenance
• ├── error404.html - page not found error page
• ├── error500.html - internal server error page
• ├── blank.html - page with basic layout with minimal or no content
• └── content
  • └── index.html - blog page
  • └── post.html - singe post page
  • └── page.html - page template
  • └── tag.html - posts list for tag
  • └── category.html - posts lists for category
  • └── archive.html - posts list for a certain date
  • └── user.html - posts list by user (author)
• └── product
  • └── index.html - shop page
  • └── product.html - singe product page
  • └── manufacturer.html - manufacturer page
  • └── vendor.html - vendor page
  • └── category.html - category page
• └── search
  • └── search.html - search page
• └── user
  • └── index.html - user dashboard
  • └── signup.html - user signup form
  • └── login.html - site login form
  • └── reset.html - password reset form
  • └── edit.html - user data edit
  • └── address.html - address list
  • └── comments.html - comments list
  • └── orders.html - orders list
  • └── downloads.html - digital products downloads list
• └── cart
  • └── cart.html - display cart page
• └── checkout
  • └── checkout.html - cart checkout form
  • └── confirm.html - order confirmation page
• └── email
  • └── order
    • └── new.html - template for new order mail
    • └── new.html.txt - text template for new order mail
  • └── user
    • └── reset.html - template for new order mail
    • └── reset.html.txt - text template for new order mail
    • └── signup.html - template for user welcome
    • └── signup.html.txt - text template for user welcome

├── index.html  -- **default template used for homepage**
├── index.coming-soon.html  -- *replaces homepage when site is set to coming soon*
├── index.maintenance.html  -- replaces homepage when site is set to maintenance
├── error404.html  -- page not found error page
├── error500.html  -- internal server error page
├── blank.html  -- page with basic layout with minimal or no content
└── content
│   └── index.html - blog page
│   └── post.html - singe post page
│   └── page.html - page template
│   └── tag.html - posts for tag page
│   └── category.html - posts category page
│   └── archive.html - posts for a certain date
│   └── user.html - user posts
└── product 
│   └── index.html - shop page
│   └── product.html - singe product page
│   └── manufacturer.html - manufacturer page
│   └── vendor.html - vendor page
│   └── category.html - category page
└── search 
│   └── search.html - search page
└── user
│   └── index.html - user dashboard
│   └── signup.html - user signup form
│   └── login.html - site login form
│   └── reset.html - password reset form
│   └── edit.html - user data edit
│   └── address.html - address list
│   └── comments.html - comments list
│   └── orders.html - orders list
│   └── downloads.html - digital products downloads list
└── cart 
│   └── cart.html - display cart page
└── checkout 
│   └── checkout.html - cart checkout form
│   └── confirm.html - order confirmation page
│   └── confirm.html - order confirmation page
└── email
│   └── order
│   │	└── new.html - template for new order mail
│   │	└── user
│   └── reset.html - template for new order mail
   	└── signup.html - template for user welcome

In addition to default templates your theme can provide additional template for users to choose.

For example you can have multiple product or posts templates for different layouts like large hero header or template for events like black friday etc.

Users can choose different templates for a certain post or product or choose a different template for homepage.

You can easily convert your html mockup into a theme in just a few minutes.

Components

Components are page elements that define a certain area in the template either for editing in the page builder or to define dynamic content.

They are defined by adding a data attribute to a html element.

Static components are defined with data-component-name and dynamic components are defined with data-v-component-name.

Examples:

<div data-component-video>This element will be edited as a video element by the page builder</div>
<div data-v-component-products>This element will display products from database</div>

Static components

Static components are used to designate elements that are recognized by the page builder.

You can use existing components in your theme or you can create your own components to edit elements like testimonials, sliders etc.

For a list of existing components and how to add new ones check the Components guide

Dynamic components

Dynamic components are used to display content from the database like posts, products, cart, user info etc.

In addition to component data-v-component-posts attribute, you can also define attributes for component properties like post name data-v-post-name or image data-v-post-image.

For example to display a list of the latest 3 posts in a template you can use the following snippet.

<div class="container" data-v-component-posts data-v-limit="3">      
	<div class="row">
        <div class="col-12 col-lg-4 mb-2" data-v-post>

          <article class="card">
			<div class="card-img-top">
              <img src="/media/posts/6.jpg" data-v-post-image>
             </div>
            
            <div class="card-body">
              <div class="post-title card-title">
                <a href="/hello-world-6" data-v-post-url>
                  <h3 data-v-post-name >Mauris viverra cursus ante laoreet eleifend</h3>
                </a>
              </div>
              
              <p class="card-text text-muted" data-v-post-excerpt>
				Et et saepe suscipit debitis a accusamus nulla in amet molestiae voluptates dolor autem vitae optio ipsa mollitia voluptatem vitae.
			  </p>
			  
              <a href="/hello-world-6" data-v-post-url>
                <span>Read more</span>
              </a>
            </div>
          </article>
	
		</div>
  </div>
</div>

For a complete list of components and specific attributes check the Components list

Theme configuration

Theme configuration is optional and is done by having a theme.php file in the root of the theme folder.

This file is used to define additional theme information like theme autor, theme homepage url, or to override some template names or add better names for new templates added by the theme.

<?php
/*
Name: Landing
Slug: landing
URI: https://vvveb.com
Author: Vvveb
Author URI: https://vvveb.com
Description: Default theme
Version: 2.0
License:  Apache 2.0
License URI: https://vvveb.com/licence/
Tags: blog, ecommerce
Text Domain: landing
*/
use function Vvveb\__;

return
	[
		'pages' => [
			'index' => [
				'name'        => 'index',
				'file'        => 'index.html',
				'url'         => '/themes/landing/index.html',
				'title' =>  __('Home page title defined from theme config'),
				'folder'      => '',
				'description' => __('Website homepage'),
			],
			'contact' => [
				'name'        => 'contact',
				'file'        => 'contact.html',
				'url'         => '/themes/landing/contact.html',
				'title' =>  __('Contact us page'),
				'folder'      => '',
				'description' => __('Contact us page'),
		]			
		'ignoreFolders' => ['theme-demo-data'],//add additional folders to ignore for page builder when loading template list
		'plugins' => [
			'required' =>  ['contact-form']
			'recommended' =>  ['markdown-editor']
		]
	];

Editor support

To add custom components, sections or blocks when the theme is edited in the page builder you need to have a folder for each in your theme root folder.

└── my-theme
│   └── sections
│  	 └── sections.js - javascript code that adds custom components
│   └── blocks
│  	 └── blocks.js - javascript code that adds custom blocks
│   └── inputs
│  	 └── inputs.js - javascript code that adds custom inputs
│   └── js
│  	 └── vvvebjs.js - javascript code that is executed after the editor is loaded, use it to hook to events. 
					  For example the default landing theme uses it to remove navbar sticky classes on page saving.
					  https://github.com/givanz/landing/blob/main/js/vvvebjs.js

Child themes

Child themes are themes that override parts of a parent theme.

They are used to make new themes that have some small differences from parent theme to avoid duplication and repetition of parent html for easier maintenance and development.

The most common use is to replace a certain part of a template from parent or a whole page or just include some additional css or javscript.

Replacing template parts

If you want your child theme to have a different homepage but keep the navigation and footer from parent theme you can define the following html as child-theme/index.html:

<!DOCTYPE html>
<html>
<head>
	<base href="">
	<title>Child theme hompepage</title>
	<!-- include parent styles from parent css folder -->
	<link href="../landing/css/style.bundle.css" rel="stylesheet">
	<!-- add child theme styles from current folder -->
	<link href="css/style.css" rel="stylesheet">
<head>
<body>

<nav data-v-copy-from="../landing/blank.html,body > nav:first">test</nav>
	
	<main>
		<h1>Child theme content</h1>
	</main>

<footer data-v-copy-from="../landing/blank.html,footer"></footer>

<script id="jquery-js" src="../landing/js/jquery.min.js"></script>
<script id="landing-js" src="../landing/js/theme.js"></script>
<script id="child-theme-js" src="js/theme.js"></script>

</body>
</html>

data-v-copy-from attribute is used to replace the tag where the attribute is defined with the content that is specified as value.

The synax is path/to/html-template.html,#css-selector > .element the path is relative to the current html file and can point to child templates or any parent theme by using ../parent-theme/ in the path.

You can override any parent template like content/post.html or product/product.html using the same pattern as in the above example.

Advanced features

If you have some specific needs that are not covered by the default implementation of current components or you need to tweak the way they work then you can override the components code by providing custom template files. You need to include your templates in a template folder that has the following structure.

• └── template
  • └── common.tpl - global template
  • └── components
    • └── posts.tpl - override posts component template
  • └── content
    • └── post.tpl - override singe post page
  • └── product
    • └── product.tpl - override single product page

Templating

Templating in Vvveb is done with Vtpl php template engine you can learn more about .tpl files syntax in the vtpl documentation

Custom dynamic components

To add custom dynamic components to your theme you need to develop a plugin that you can include in your required plugins section in your theme.php configuration file.

Developing plugins is very easy check out the plugin development guide

Vtpl templates are just lists of php code and variable names to insert into html, to specify the elements where to insert the code css selectors are used.

With Vtpl when the frontend template design of your app is changed you don’t have to change anything, the logic for the html file will be automatically applied for these new html files.

Vtpl ensures proper separations of concerns, the frontend logic is separated from presentation.

Vtpl makes it possible to build CMS's like Vvveb where any html page of the CMS can be changed to the last element without affecting the rendering of dynamic content from the database.

Documentation

Vtpl is just a list of key = value pairs.

On the left you need to specify the CSS selector and on the right the code that must be inserted for the selector.

The code to be inserted can be one of the following

Simple strings

div#id > span.class a = "lorem ipsum"

Php variables

div#id > span.class a = $variable

Php code for complex logic

div#id > span.class a = <?php if ($var) echo $var;?>

Note It's a good practice to use a standard for the css selectors, for example use data attributes like [data-product-name] instead of generic id's or css classes.

Include external html sections for better reuse by using from

/*
from, a special command that copies html from other templates,
useful to include up to date html code into all templates from the currently maintained template 
for the specified section a common use is to apply the header from homepage to all other other html templates
*/

div#top > div.header = from(homepage.html|div#top > div.header)

/*
Or you can skip the selector part, in this case the same selector (eg div#top > div.header) is assumed.
*/
div#top > div.header = from(homepage.html)

List of modifiers

innerHTML

/*
by default code is inserted into the specified elements without replacing the current elements (innerHTML) 
to replace the entire elements with the specified code use outerHTML modifier
*/

div#id > span.class a|innerHTML = "lorem ipsum"

Before

/*
Inserts the code before the element(s)
*/
div#id > span.class a|before = "lorem ipsum"

Prepend

/*
Inserts the code at the beginning inside the element(s)
*/
div#id > span.class a|prepend = "lorem ipsum"

After

/*
Inserts the code after the element(s)
*/
div#id > span.class a|after = "lorem ipsum"

Append

/*
Inserts the code at the end in the element(s)
*/
div#id > span.class a|append = "lorem ipsum"

deleteAllButFirst

/* Deletes all elements for the specified selector except for the first elements, usually in mockups front end developers add multiple elements to better show the final page look, the programmer just needs one element to iterate and fill data*/
div#id > span.class a|deleteAllButFirst

/*

<!-- this -->
<div id="id">
<span class="class">
<a>link 1</a>
<a>link 2</a>
<a>link 3</a>
</span>
</div

**wil result into this**

<div id="id">
<span class="class">
<a>link 1</a>
</span>
</div>
*/

hide

/*removes the specified elements if the variable ($articles) is false*/
div.articles|if_exists = $articles

delete

/* removes the specified elements*/
div.articles|delete

attributes

attributes
/*
to inject code into a tag's attribute you must specify the attribute as an modifier
*/
div#id > span.class a|href = "www.thewebsite.com"

div#id > span.class a|title = "The website"

Additional commands

Import

Includes additional files, usefull to separate logic when things get bigger and harder to maintain in one file

import(profile/activity_tab.tpl)

Comments

Vtpl can have comments

 //single line  
 /* Or multiple line  
 comments  
 */  

Debugging

/*
just on some portions with the following directive directly into the Vtpl files
/*
you can turn on debug with
*/
debug = true
/*
or turn it off with
*/
debug = false

When in debug mode, you will have a list of all template injections made on the html to visualize.

Its architecture follows an MVCC pattern (Model–View–Controller–Component), with a distinctive approach to the Model and View layers:

For Models SQL code is used directly rather than abstracted away, and for View HTML templates remain clean and logic‑free without any template markup.

This design preserves the strengths of both languages and leads to clearer separation of concerns, easier maintenance, and faster development.

Application Structure

Vvveb is organized into main applications, app, admin, rest, graphql and install, alongside shared system directories.

• app is the public‑facing frontend that renders pages for site visitors.
• admin is the backend interface (typically accessed at /admin, though this path can be changed for security) used for content and site management.
• rest serve Rest API requests
• graphql serve GraphQL API requests
• install runs automatically when no database configuration exists (config/db.php), guiding new installations through setup.

Shared directories such as system, public, plugins, and config support all applications.

Directory Layout

The directory structure is designed for clarity, modularity, and maintainability:

├── app
│   ├── controller          # Frontend controllers
│   ├── component           # Frontend components (PHP logic)
│   ├── template            # Frontend templates (Vtpl)
│   ├── sql                 # SQL queries for models
│   └── validate            # Validation rules
├── admin
│   ├── controller          # Admin controllers
│   ├── component           # Admin components (PHP logic)
│   ├── template            # Admin templates (Vtpl)
│   ├── sql                 # SQL queries for admin models
│   └── validate            # Validation rules
├── install
│   ├── controller          # Installer controllers
│   ├── template            # Installer templates
│   └── sql                 # Installer SQL scripts
├── plugins
│   ├── contact-form
│   └── insert-scripts
├── system                  # Core framework files
├── config
│   └── db.php              # Database configuration
├── storage
│   ├── digital_assets      # Uploaded files
│   ├── model               # Compiled model files
│   │   ├── app
│   │   ├── admin
│   │   └── install
│   ├── backup              # Backups
│   ├── sqlite              # SQLite database files
│   ├── compiled-templates  # Cached Vtpl templates
│   └── cache               # General cache
├── public
│   ├── themes              # Frontend themes
│   │   ├── landing
│   │   └── blog-default
│   ├── admin               # Admin theme
│   │   └── default
│   ├── media               # Public media files
│   ├── js                  # Public JavaScript
│   ├── page-cache          # Static page cache
│   ├── install             # Installer public assets
│   └── plugins             # Public plugin assets
│       ├── contact-form
│       └── insert-scripts
├── plugins                # Plugins fles
├── graphql                # Graphql API
├── rest                   # Rest API
└── locale                  # Language files

Architectural Principles

SQL as the Model Layer

Instead of hiding SQL behind ORM abstractions, Vvveb encourages writing SQL directly in the sql directory. This keeps data logic explicit, predictable, and easy to optimize.

HTML as the View Layer

Views are pure HTML enhanced with Vtpl, a template engine that uses CSS selectors to inject dynamic content. This ensures:

• HTML remains clean and designer‑friendly
• No PHP logic is mixed into templates
• Themes can be replaced without touching backend code

Components as the Glue

Components provide the dynamic data for templates. Each component has:

• A PHP file (app/component/...) that fetches data
• A Vtpl template (app/template/components/...) that binds data to HTML

This structure keeps logic modular and reusable.

Application Flow

1. Request arrives
   The router determines whether the request belongs to the frontend (app), backend (admin), restis api, graphql api or installer (install).

2. Controller executes
   Component services load components, run SQL queries, and prepare data. Controller is selected for matching route (based on config/app-routes.php0) and run.

3. Template renders
   Vtpl inserts dynamic data into HTML using CSS selectors.

4. Response is delivered
   The final HTML is sent to the browser, optionally cached for performance.

Development Workflow

• Frontend developers work in public/themes/... and app/template/..., modifying HTML and templates without touching PHP.
• Backend developers work in app/controller, app/component, and app/sql, writing logic and queries.
• Plugin developers extend functionality via the plugins directory.
• Administrators manage content through the /admin interface.

This separation allows teams to work independently without stepping on each other’s code.

Vvveb’s structure is designed to stay flexible even as a project grows.-

Admin Models

• admin
• comment
• digital_asset
• length_type
• option_value
• post_content_revision
• product_option
• product_review
• region
• return_status
• site
• subscription
• tax_rate
• user_group
• voucher
• attribute_group
• country
• field_group
• manufacturer
• order_log
• post
• product_option_value
• product
• return_reason
• role
• stat
• subscription_status
• tax_rule
• user
• weight_type
• attribute
• coupon
• field
• menu
• order
• product_attribute
• product_question
• product_subscription
• return_resolution
• setting_content
• stock_status
• taxonomy_item
• tax_type
• user_wishlist
• category
• currency
• language
• option
• order_status
• product_content_revision
• product_review_media
• region_group
• return
• setting
• subscription_plan
• taxonomy
• user_address
• vendor

App Models

• attribute
• comment
• coupon
• language
• menu
• order
• post
• product_option_value
• product_review_media
• product
• region
• review
• setting
• subscription_plan
• tax_rate
• user_address
• user_wishlist
• category
• country
• currency
• manufacturer
• option
• permission
• product_option
• product_question
• product_review
• product_subscription
• return_reason
• role
• site
• subscription
• tax_type
• user
• vendor

Component object is used to define the html blocks that can be added and edited on the page.

To add a component you need to use Vvveb.Components.add method or extend an existing component, like a base component with Vvveb.Components.extend

For example image component extends _base component and is defined as

Vvveb.Components.extend("_base", "html/image", {
    nodes: ["img"],
    name: "Image",
    html: '<img src="../libs/builder/icons/image.svg" height="128" width="128">',
    image: "icons/image.svg",
    properties: [{
        name: "Image",
        key: "src",
        htmlAttr: "src",
        inputtype: FileUploadInput
    }, {
        name: "Width",
        key: "width",
        htmlAttr: "width",
        inputtype: TextInput
    }, {
        name: "Height",
        key: "height",
        htmlAttr: "height",
        inputtype: TextInput
    }, {
        name: "Alt",
        key: "alt",
        htmlAttr: "alt",
        inputtype: TextInput
    }]
});

Base component does not extend any existing component and is using Vvveb.Components.add being defined as

Vvveb.Components.add("_base", {
    name: "Element",
	properties: [{
        name: "Id",
        key: "id",
        htmlAttr: "id",
        inputtype: TextInput
    }, {
        name: "Class",
        key: "class",
        htmlAttr: "class",
        inputtype: TextInput
    }]
});

In this way any component that extends _base component inherits two properties id and class used to edit the corresponding html attributes.

Note: _base component is loaded for any html node that has no specific component assigned, for example when clicking on a regular span node.

Component definition

Component object can have the following keys

• name - Used to display the name on the components list in the left panel.
• image - Image url to display in the components list.
• html - When dropping the component on the page this html is used to insert it in the page.
• nodes - An array with dom node names to allow the editor to detect the Component when clicking on the corresponding node, example nodes: ["h1", "h2","h3", "h4","h5","h6"], or nodes: ["img"],
• classes - An array with class names to allow the editor to detect the Component when clicking on the corresponding node, example classes: ["btn", "btn-link"]
• classesRegex - An array with regexs used for class names to allow the editor to detect the Component when clicking on the corresponding node, example classesRegex: ["col-"], this regex is used by Grid Component to detect bootstrap columns such as col-md-3 or col-sm-6.
• attributes - An array with attributes names to allow the editor to detect the Component when clicking on the corresponding node, example attributes: ["data-component-maps"], this attribute is used by maps component.
• afterDrop - function (node) {} A function that is called after the element is droped, the node of the new element is passed as parameter, for example map component uses this function to change the html of the node fom a image of a map with the actual map iframe for performance reasons when dragging.
• init - function (node) {} A function that is called after the Component properties are loaded and displayed in the right panel , the node of the new element is passed as parameter, for example video component that supports youtube, vimeo and html5 uses this event to hide vimeo and html5 inputs when a youtube video is detected.
• beforeInit - function (node) {} A function that is called before Component properties are displayed , the node of the new element is passed as parameter, this can be useful to dinamically change component properties for example Select Input or Grid component that needs to load a variable number of inputs based on child nodes uses this event to alter component properties and add the necessary properties for each child node.
• onChange - function (node, property, value) This event is called when a component input in the right panel is changed, the first parameter is the dom node that is edited, second parameter property is the name of the property that has changed (the key attribute of the property), value is the new value of the property. Usually each input has it's own onChange event but because the component onChange event is triggered for all inputs can be usefull when using a common function to process all input changes. This event is usefull when changing complex features, for example the map component uses it to compose a new google maps url by adding all component properties such as latitude, longitude and zoom etc.
• properties - A collection of inputs and corespponding configuration for each, to allow the Component to be edited.

A complete Component definition with all possible keys

Vvveb.Components.extend("_base", "html/image", {
	name: "Image",
	image: "icons/image.svg",
	html: '<img src="../libs/builder/icons/image.svg" height="128" width="128">',
	nodes: ["img"],
	classes: ["btn", "btn-link"],
	attributes: ["data-component-maps"],
	afterDrop: function (node) {},
	init: function (node) {},
	beforeInit: function (node) {},
	onChange: function (node, property, value) {},
	properties: [{
		name: "Id",
		key: "id",
		htmlAttr: "id",
		inputtype: TextInput
    }
});   

Component properties

Component properties are used to define the inputs that are used to edit the component.

properties: [{
        name: "Id",
        key: "id",
        htmlAttr: "id",
        inputtype: TextInput
    }, {
        name: "Class",
        key: "class",
        htmlAttr: "class",
        inputtype: TextInput
    }]

A property can have the following keys

• name - Used as label for the input.
• key - Unique identifier for the input, this is pased on component onChange event second parameter property.
• inputtype - The input type used for the property, any Input object such as TextInput, SelectInput, ToggleInput, ColorInput etc from inputs.js can be used.
• htmlAttr - If htmlAttr is specified then the value is used to edit the coresponding html attribute, the input is filled automatically with the initial value of the attribute and updated automatically when the input is changed, no need to use onChange event, for example htmlAttr: "id",
  • style - If htmlAttr is set to style then the property key is used as the css property to be edited, in the example below background-color css property is edited directly using ColorInput that will display a color picker.
  • class - If htmlAttr is set to class and the property has validValues key then all classed that are contained in validValues array are removed before adding the new value, this can be usefull when having a select input to choose a unique class from a set. For example in the example below bootstrap container component uses validValues to allow either container or container-fluid class to be added from a select.

properties: [
{
	name: "Background Color",
	key: "background-color",
	htmlAttr: "style",
	inputtype: ColorInput,
},
{
	name: "Type",
	key: "type",
	htmlAttr: "class",
	inputtype: SelectInput,
	validValues: ["container", "container-fluid"],
	data: {
		options: [{
			value: "container",
			text: "Default"
		}, {
			value: "container-fluid",
			text: "Fluid"
		}]
	}        name: "Class",
	key: "class",
	htmlAttr: "class",
	inputtype: TextInput
}]

• onChange - function(node, value) This event is triggered when the input is changed (this can depend on Input definition, check inputs.js) you can use this when htmlAttr or style is not enough.
• init - function(node) This function is called when the input is initialized, this can be used for example to load the input with a different value than default. For example when editing width css property and using a NumberInput you need to use init to remove the px from "100px" to set the value for NumberInput correctly.

{
	name: "Width",
	key: "width",
	htmlAttr: "style",
	parent:"",
	inputtype: NumberInput,//can also be replaced with RangeInput
	data: {
		value: "320",//default
		min: "50",
		max: "1024",
		step: "10"
	},
	init: function (node)//use init because number input does not ignore "px"
	{
		return parseInt($(node).css("width"));//remove px
	}
}

• data - Some Inputs need aditional data, for example ToggleInput needs values for on and off states, or SelectInput needs data:{options: [{}]} for values For example using toggle to set disabled to true or false for a bootstrap button

//ToggleInput
{
	name: "Disabled",
	key: "disabled",
	htmlAttr: "disabled",
	inputtype: ToggleInput,
	data: {
		on: "disabled-true",
		off: "disabled-false"
	}
}
//SelectInput
{
        name: "Size",
        key: "size",
        htmlAttr: "class",
        inputtype: SelectInput,
        validValues: ["btn-lg", "btn-sm"],
        data: {
            options: [{
                value: "",
                text: "Default"
            }, {
                value: "btn-lg",
                text: "Large"
            }, {
                value: "btn-sm",
                text: "Small"
            }]
        }
    }

• child - Sometimes you need to edit a node that is inside the parent node, for this you can use child property the value must be the css selector for the child element. For example bootstrap progress bar component has two divs, one for background and one for the progress to use a input to change the progress div instead of the background div, child is set as child:".progress-bar".

{
	name: "Animated",
	key: "animated",
	child:".progress-bar",
	htmlAttr: "class",
	validValues: ["", "progress-bar-animated"],
	inputtype: ToggleInput,
	data: {
		on: "progress-bar-animated",
		off: "",
	}
}	

• parent - Same as child but used to edit parent elements, when only parent is set with no selector then the parentNode is used, if a css selector is used then the selector is used to find parent node (this uses jQuery.parents())

Component group

For a component to be visible in the left panel and to be used for drag and drop it needs to be added to a component group, you can do this by including it in the Vvveb.ComponentsGroup array using the group name as a key.

For example Widgets component group has the following definition.

Vvveb.ComponentsGroup['Widgets'] = ["widgets/googlemaps", "widgets/video"];

Inputs objects are used to edit component properties

For example TextInput extends Input object and is defined as

var TextInput = $.extend({}, Input, {

    events: {
        "keyup": ['onChange', 'input'],
	 },

	setValue: function(value) {
		$('input', this.element).val(value);
	},
	
	init: function(data) {
		return this.render("textinput", data);
	},
  }
);

Inputs also require a template that is defined as a