Themes are made of plain html files, any static html site is a valid Vvveb theme.

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
Structure text 


├── 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