Welcome

Hello and welcome to the CSS Hero Developers Knowledge Base, by following those docs you’ll be guided in building your first hero-ready theme or plugin.

Configuring your product to be hero-ready is quite easy and can seriously increase the quality level as your users will experience the freedom of customizing it without having to write a single line of code with an easy and intuitive tool. Your users will be happy and your support requests on aspect customization will drop down. Of course you have full control of what your users will be able to edit and even how they can interact with it.

Moreover, if you’re willing to earn some extra cash we’d be happy to share revenues with you, check our affiliation program for further infos on this topic or drop us a mail, we’d be happy to discuss this together.

The Hero-Ready concept

A theme or plugin in order to be defined ‘hero-ready’ needs some simple configuration in order to let CSS Hero understand which CSS selectors to target.

A hero configuration is a set of rules that CSS Hero will follow to let your users safely edit your product without the risk of messing around.
Basically you have to declare your own set of editable items on which CSS Hero will be able to work.

Getting Started

To get started create a blank csshero.js file inside your currently activated theme root folder and add the main wrapper function, here’s how your csshero.js file should look at this stage:

Example dummy csshero.js file:

function csshero_theme_declarations(){
     // CONFIGURATION WILL BE HERE
     // call here the csshero api functions like
     // csshero_declare_item  (selector,description)
     // or the more advanced ones;
     // so read on this documentation to learn
     // what to put in here and get started!
}

Now let’s move on and discover the CSS Hero API

CSS Hero API

Hero needs to know which elements should be editable by your users. To achieve this you have to declare the editable elements of your theme\plugin and there’s a very basic API function to do it in a breeze:

csshero_declare_item(selector,description);
  • selector the CSS selector identifying that element
  • description (optional) A textual description of that element

That’s it. As simple as that. With this function you can tell CSS Hero which element (selector) has to be editable and add an optional description of it (description).

Example csshero.js file:

function csshero_theme_declarations(){
	csshero_declare_item('#header','Site Header');
}

This will make the #header element of your theme editable, please note that the selector you provide as selector has to be at least specific as the one actually controlling it’s aspect in your stylesheet. So if in your stylesheet the header look is defined by #wrap #header the previous example will not work, or more precisely will work only on the css rules not applied via stylesheet. So if your stylesheet declares the aspect of your header element with #wrap #header you may need to declare it as it follows:

Example csshero.js file:

function csshero_theme_declarations(){
	csshero_declare_item('#wrap #header','Site Header');
        //add more declarations at your will for intercepting more elements...
}

Understanding this very simple logic is the first step to get into CSS Hero configurations.

However, declaring all of your theme\plugin elements just with this function may result extremely verbose and annoying, our API comes to rescue with a set of pre-built helper functions that wrap standard blocks of item declarations based on WordPress standards.

CSS Hero API: Helper Functions

Those helper functions are mainly built for theme configurations purposes and could incredibly speed up your configuration tasks.

csshero_config_sidebar(selector,widget_selector,prefix);
csshero_config_post(selector,content_selector,prefix);
csshero_config_menu(selector,ul_selector,prefix);
csshero_config_comments(selector,….,prefix);
csshero_config_respond(selector,inner_selector);

As you may know WordPress outputs some standard blocks

  • sidebars (widgets)
  • posts (header, meta, content, footer)
  • menu (list of items and sub-lists)
  • comments (lists of items)
  • respond (a comment form)

Most of the times those blocks make up to 90% of your theme and probably you don’t want to go mad declaring each item in them. Using our helper functions will definitively help.

csshero_config_sidebar()

csshero_config_sidebar(selector,widget_selector,prefix);

Parameters:

  • selector the CSS selector of the sidebar container element
  • widget_selector the CSS selector of the widget element, most of the time will be something like .widget or aside
  • prefix the prefix text to show up in the editor
dd01

In this example the description selector is set to ‘Primary Sidebar’

Example: if this would be the HTML markup produced by your custom theme…


You can just add this to your declarations instead of multiple csshero_declare_item calls:

csshero_config_sidebar('#sidebar','.widget','Sidebar');

One line does it all. All the typical WP elements of the sidebar will be live-editable. Of course you can define multiple sidebars and Hero will make editable each of them and each element in them.

csshero_config_sidebar('#sidebar','.widget','Widget Area');
csshero_config_sidebar('#footer','.widget','Footer Widget Area');

csshero_config_post()

csshero_config_post(selector,content_selector,prefix);

Parameters:

  • selector the CSS selector of the post container (usually something like: article, .post, .hentry, .page)
  • content_selector the CSS selector of the element containing the post content (most of the times something like: .entry-content
  • prefix the prefix text to show up in the editor (using ‘Post will show something like this (link imagine in overlay dell’editor con Post)

Example:

The Post Title

By…
the post content […]
post footer contents

This will do the trick:

csshero_config_post('article.post','.entry-content','Article');

You can add more config post functions depending on how different layout customization options you want to give, you may want your users to have the ability to customize single posts and single pages in a different way:

csshero_config_post('body.post article','.entry-content','Post');
csshero_config_post('body.page article','.entry-content','Page');

Please note that this function configures items based on conventional WordPress classes and structures, you may want to refine them by adding some more items:

csshero_config_post('article.post','.entry-content','Article');
csshero_declare_item('article.post .my-meta-area','My Custom Article Meta Area');

csshero_config_menu()

csshero_config_menu(selector,ul_selector,prefix);

Parameters:

  • selector the CSS selector of the menu container (usually something like: nav, .menu, .nav)
  • ul_selector the id\class of your menu list item
  • prefix the prefix text to show up in the editor (using ‘Nav will show something like this (link imagine in overlay dell’editor con Nav)

Example:


Here you go:

csshero_config_menu('#main-navigation','.menu','Nav');

This helper takes care of all the menu editable items including links, sub-menus, current-page items etc.

csshero_config_comments()

csshero_config_comments(selector);

Parameters:

  • selector: the CSS selector of the outer comments area wrap, most of the times #comments

Please note that comment layouts may often vary and may need extra csshero_declare_items() to grant full customization.

csshero_config_respond()

csshero_config_respond(selector,innerselector)

Parameters:

  • selector: the outer CSS selector of the comments area, usually #comments
  • innerselector: the CSS selector of the respond area, usually #respond

Some theme configuration examples

Here you can find the Tiny WP theme configuration example. You can check CSS Hero in action on that theme here.

Tiny WordPress theme full configuration example csshero.js configuration file

function csshero_theme_declarations(){
  // MAIN CONTAINER
  csshero_declare_item('#content','Site Background');
  
  // TOP AREA
  csshero_declare_item('#top','Top Area');
  csshero_declare_item('#top .container','Top Inner Area')
  csshero_declare_item('#top a.logo','Top Logo');
  csshero_declare_item('#top a.logo span','Top Logo Icon');
  csshero_declare_item('#top a.menu-btn','Top Menu Button');
	
  // HEADERS
  csshero_declare_item('body:not(.single):not(.page) .container > header','Generic Header Area');
  csshero_declare_item('body:not(.single):not(.page) .container > header h2','Generic Header Title');
  csshero_declare_item('.home .container header h1','Header Title');
  csshero_declare_item('.home .container header p','Header Description');
	
  // POSTS
  csshero_config_post('.posts','article','Main Post');
  csshero_declare_item('.posts article h2:first-child a','Post Title');
	
  // SINGLE
  csshero_config_post('body.single .post','article','Single Post');
  csshero_declare_item('.single header.title','Single Post Title Area');
  csshero_declare_item('.single header.title h2','Single Post Title');
  csshero_declare_item('.single header.title p','Single Post Title Area Parapgraph');
  csshero_declare_item('.single header.title span','Single Post Title Area Span');
  csshero_declare_item('.single header.title p a','Single Post Title Area Link');
  csshero_declare_item('.single header.title p a[rel=tag]','Single Post Title Area Tag');
  csshero_declare_item('.single header.title .back-to-blog','Back To Blog Button');
  csshero_declare_item('.single header.title .back-to-blog i','Back To Blog Icon');
  csshero_declare_item('.share','Share Area');
  csshero_declare_item('.share i','Share Area Icon');
	
  // COMMENTS
  new_csshero_config_comments('.comments','.comments-holder','.comment');
  csshero_declare_item('.comment_content h3','Comment Author');
  csshero_declare_item('.comment_content h3 a','Comment Author Link');
  csshero_declare_item('.comment_content span','Comment Date');
  csshero_declare_item('#content .comment .comment_content','Comment Inner Area');
  csshero_declare_item('.comment.depth-2','Comment Depth 2');
  csshero_declare_item('.comment.depth-3','Comment Depth 3');
  csshero_declare_item('.comment.depth-4','Comment Depth 4');
  csshero_declare_item('.comments > h2','Comments Area Title');
  csshero_declare_item('.comments > h2 i','Comments Area Icon');
	
  // RESPOND
  csshero_config_respond('.comments');
	
  // FOOTER AREA
  csshero_declare_item('footer','Footer Area');
  csshero_declare_item('footer .container','Footer Inner Area');
  csshero_declare_item('footer .container a','Footer Links');
  csshero_declare_item('footer .container .sub-footer','Footer Sub-footer');
  csshero_declare_item('footer .container .copyrights','Footer Copyrights');
	
  // MENU 
  csshero_config_menu('#main-menu');
  csshero_declare_item('#main-menu .container .widget > h3','Menu Titles');
	
  // BACK TO TOP
  csshero_declare_item('.back-to-top','Back To Top Button');
  csshero_declare_item('.back-to-top i','Back To Top Icon');
	
  // PAGE
  csshero_config_post('body.page .post','article','Page');
  csshero_declare_item('.page .container header h2','Page Title');
  csshero_declare_item('.page header.title','Page Title Area');
	
  // SOCIAL
  csshero_declare_item('.page .post .social-links','Social Links Area');
  csshero_declare_item('.page .post .social-links a','Social Link Background');
  csshero_declare_item('.page .post .social-links a i','Social Link Icon');
	
  // CONTACT FORM
  csshero_declare_item('.contact-form','Contact Form Area');
  csshero_declare_item('.contact-form label','Contact Form Label');
  csshero_declare_item('.contact-form input','Contact Form Input');
}

Going Dynamic!

Until now we’ve used ‘static’ ways of declaring items however CSS Hero configurations file are .js files so you can easily run some javascript\jQuery magic to dynamically identify editable elements:

Let’s say our theme has a set of rows on a specific template page and we want to allow our users to customize each row on an ID basis:

This is the row01 title

This is the row01 description paragraph

This is the row02 title

This is the row02 description paragraph

This is the row03 title

This is the row03 description paragraph

Our configuration file will look something like this:

frame = window.frames['csshero-iframe-main-page'].document.body; 
jQuery('section.row',frame).each(function(){
	id = jQuery(this).attr('id');
	csshero_declare_item('section.row#'+id,'Row ID#'+id);
	csshero_declare_item('section.row#'+id+' h2','Row ID#'+id+' Title');
	csshero_declare_item('section.row#'+id+' .description','Row ID#'+id+' Description');
});
  • line 1: define the frame where Hero has to look for items
  • line 2: loop through each section.row item
  • line 3: find the id for each section.row
  • line 4: fire the declaration (section.row#row01,section.row#row02,section.row#row03)
  • line 5-6: fire declarations for inner items

Dynamic Example: WP Polls

This example configuration file is the one actually in charge of making WP Polls Plugin editable. You can see it in action here.

In this specific example we’re looping through all plugin instances getting the ID for each one and outputting a dynamic configuration on an instance ID basis.

function csshero_theme_declarations(){
  
  // !IMPORTANT - frame is the layer on which dynamic loops should happen
  var frame = window.frames['csshero-iframe-main-page'].document.body;

  // LOOPING THROUGH EACH .wp-polls INSTANCE
  // !IMPORTANT - notice we're using frame, looping by jQuery('.wp-polls').each()... won't work.
  jQuery('.wp-polls',frame).each(function(){

    // GET THE ID OF this INSTANCE
    var f_name = jQuery(this).attr('id');
    var f_id = '#'+f_name;	
  
    // DEFINE array OF EDITABLE ITEMS FOR EACH INSTANCE
    var arr = [ "p", "a", "p a", "img", "quote", "blockquote", "h1", "h2", "h3", "h4", "h5", ".screen-reader-response","textarea","label","ul","ul li",];
  
    // FIRE csshero_declare_item() FOR EACH EDITABLE ITEM INSIDE THIS .wp-polls INSTANCE
    jQuery.each( arr, function( i , val) {
      csshero_declare_item(f_id+' '+val,f_name+' '+val);
    });
  
    // DECLARE SOME GENERIC STUFF FOR EACH INSTANCE
    csshero_declare_item(f_id,'Form ID: '+f_name);
    csshero_declare_item(f_id+' .wpcf7-list-item',f_name+' List Item');
  
    // DECLARE THIS INSTANCE INPUTS BY TYPE
    jQuery(f_id,frame).find('input').each(function(){
      var t = jQuery(this).attr('type');
      csshero_declare_item(f_id+' input[type='+t+']',f_name+' Input ('+t+')');
    });
  });
}

Let your users use your configurations

Once you’re done with the configuration of your Theme\Plugin and want to go public allowing your users to use CSS Hero on your products get in touch with us and we’ll be happy to spread your configuration to all our users and feature you in our Hero Ready Themes or Hero Ready Plugins directories.

CSS Hero is the definitive plugin to customize your WordPress themes with an easy and intuitive WYSIWYG interface.

Affiliate

Become a CSS Hero affiliate and earn 40% on each sale right now. Spread the CSS Hero word and share the wealth with us!
Start Earning →

Follow the Hero