KDE.org/Neverland

From KDE Community Wiki

Introduction

KDE's Neverland is able to build full themes from a set of template files. The designer needs to only care about the css/js files and the correct nesting of the layout (html). Once satisfied, complete themes for any supported CMS can be outputted and then used accordingly. The project is based on node.js.

Installation

Requirement

  • Git
  • NodeJs >= 5.2
  • Basic understanding of Mustache

Installing Neverland

Clone the repository:

git clone git://anongit.kde.org/websites/neverland.git

Change to the neverland folder:

cd neverland

Switch to gsoc branch:

git checkout gsoc

Install dependencies:

npm install

Install gulp globally:

npm install gulp -g

You can check if everything is ok by running:

node neverland watch --theme neverland

Usage

To create a new theme, you can run: node neverland new your-theme-name

Your new theme will appear under blueprints directory

To start building a theme, you can run:

node neverland watch --theme your-theme-name

or

gulp watch --theme your-theme-name

Currently you should keep your theme structure by default

Now you can code your theme normally.

To convert your html theme to wordpress or mediawiki theme, you need some additional works. Every theme shares some same parts such as Navigation bar, Category links, Sidebar. In order to let Neverland understand where to transform these parts to corresponding cms part you need to some default Mustache tags.

For example:

You have your navbar like this:

<ul class="header__categories">                                                                                                                              
    <li class="header__categories--item">                                                                
            <a href="#" class="header__categories--link">Work</a>                                            
    </li>                                                                                                     
    <li class="header__categories--item">                                                                
            <a href="#" class="header__categories--link">Portfolio</a>                                       
    </li>                                                                                                     
    <li class="header__categories--item">                                                                
            <a href="#" class="header__categories--link">About</a>                                           
    </li>                                                                                                                                                                                      
</ul>

You should insert the tags like this:

<ul class="header__categories">                                                                               
{{#navbar__category}}                                                                                         
{{&navbar__category}}                                                                                         
    <li class="header__categories--item">                                                                
        <a href="{{&navbar__category--link}}" class="header__categories--link">{{&navbar__category--name}}</a>
    </li>                                                                                                     
{{&navbar__category--end}}                                                                                    
{{/navbar__category}}                                                                                         
{{^navbar__category}}                                                                                         
    <li class="header__categories--item">                                                                
        <a href="#" class="header__categories--link">Work</a>                                            
    </li>                                                                                                     
    <li class="header__categories--item">                                                                 
        <a href="#" class="header__categories--link">Portfolio</a>                                        
    </li>                                                                                                     
    <li class="header__categories--item">                                                                
        <a href="#" class="header__categories--link">About</a>                                            
    </li>                                                                                                     
{{/navbar__category}}                                                                                         
</ul>

There are some key points here:

  • Those tags using BEM methodology
  • {{& }} is the same as {{{ }}} because Neverland uses this library
  • You should define both which part should be transform and default part


You can check for full tags in #Supported Tags section

Finally, you can output your theme to wordpress/mediawiki/drupal themes by running:

node neverland build --theme your-theme-name

Your theme will be placed under buildings/your-theme-name directory

Commands

node neverland [commands]

new <theme-name> Create new skeleton theme
delete --theme <theme-name> Delete theme
themes List existing theme
sass --theme <theme-name> Compile sass files
watch --theme <theme-name> Using gulp watch
build --theme <theme-name> --platform,-p <platform> Build theme for specific platform. If platform is ommited, Neverland will build for all supported platforms.

Supported Tags

article__link
article__title
article__thumbnail
article__time
article__author--link
article__author--name
article__content
article__category
article__category--end
article__category--link
article__category--name
navbar__category
navbar__category--link
navbar__category--name
navbar__category--end

Write a builder for other platforms

Requirements

Basically Neverland doesn't restrict the way you write your builder. But there are still some requirement you must have to follow:

  • There must be a build.js file under workers/platform directory
  • You have to add your platform manually by adding it to platforms array on architect/commands/build.js line 25.

How the default builders work

You can refer the default builders. Here is how they work:

  • First, platform templates are prepared under workers/platform/templates. These templates content some tags such as {{{ header }}}, {{{ body }}}, {{{ footer }}} ...
  • Neverland copy all files from workers/platform/templates to buildings/theme-name/platform
  • Neverland renders {{{ body }}},{{{ footer }}} … with the corresponding files body.mustache,footer.mustache in blueprints/theme-name folder
  • After that, it renders the asset parts.
  • Finally, it renders {{{article__author}}}, {{{article__author--link}}} tags with the platform tags


Take a look at the wordpress builder (workers/wordpress/build.js), and you can see those basic steps.