Weaver Xtreme Theme API Documentation -- Version 1.0

 

Table of Contents

 

This document is a reference to all the internal details of the Weaver Xtreme Theme rendering engine.

This includes:

  1. Rough <div> layout overview
  2. Classes used
  3. Filters
  4. Actions
  5. Pluggable functions
  6. Option values

One key to learning how to build child themes or custom option interfaces for Weaver Xtreme is to understand how the various parts of the site are organized. Not surprisingly, Weaver Xtreme relies heavily on the basics of HTML <div>s and the "Cascading" part of CSS. Most of the theme options are based on this cascading layout, and organized accordingly. The following diagram illustrates the cascading nesting of the Weaver Xtreme design.

 

body
#wrapper - wraps entire site - no content
#header - header image, header widget area, HTML insertion

.menu-primary - primary menu
#container - wraps infobar, content and main sidebars
#infobar - breadcrumbs, other info
#content - the main content - posts and pages
#primary-widget-area
widgets

6 different layouts
#secondary-widget-area
widgets
#colophon - footer widget area, HTML insertion, copyright line

The main options for the #wrapper and #container areas are found on the Weaver Xtreme Main Options : Wrapping Areas tab. The options for the #header are on the Header tab, and the options for the #colophon are on the Footer tab. Options for the Menus are on the Menus tab. There are two tabs to cover Page and Post Content: Content Areas and Post Specifics. Normally, Posts will inherit the settings from the Page options, but various Post specific options are available on the separate tab. The general layout and behavior of the content area and the sidebar areas is controlled by the Sidebars & Layout tab. If you remember the main layout nesting above, and the options found on these specific tabs, you will be well on your way to effectively designing with Weaver Xtreme.

Weaver Xtreme includes its own translation files for over 20 languages. There are about 100 visitor side messages, and it is fairly simple to create a Weaver Xtreme translation file for new languages. If you create your own new translation file, we would be happy to include it in the official Weaver Xtreme distribution.

It is easy to design your own site look. You can start with one of many pre-defined subthemes, and change the settings to meet your needs. It is easy to get started: you just have to pick colors and click on check marks.

For more advanced developers, there a many options for fine tuning. These include custom CSS, options to add HTML to various areas of the screen, and several ways to display posts in places other than the standard blog page.

Directory Macro Replacement for CSS images

Sometimes you might want to add a background image to a style ( e.g., using a url( ) value ). Those images need to be stored someplace available to visitors to your site. One typical place is to use the WordPress media gallery, and use the full URL to those images.

Because you might be building a child theme, or an Add-on Subtheme, Weaver Xtreme Plus provides a handy macro replacement capability for Custom CSS Rules and CSS+ rules. For example, if you want to supply some background images for a child theme, and you would like to save those images in a directory called /images in the child theme directory, you can use the macro %stylesheet_directory% in a style url( ) value.

For example, say you've built a child weaver theme, and have a file called content-bg.jpg stored in the child theme's /images directory. You can specify the location of that file in a site independent manner by using:

#content {background-image: url( %stylesheet_directory%images/content-bg.jpg );}

The %stylesheet_directory% will be replaced in the generated CSS code as

url( /wp-content/themes/your-child-theme/images/content-bg.jpg )

The file directory macros supported by Weaver Xtreme will produce a root-relative path, and include the trailing /. Using a root-relative path eliminates issues with http and https protocols, and will be site independent. The following macro values are supported:

%template_directory% - the main theme directory. If the theme is a child theme, this will be the directory of the parent theme ( so /weaver-xreme/ ).

%stylesheet_directory% - the directory of the theme's stylesheet - thus if it is a child theme, then this will be the child theme's directory.

%dendrologicals% - the directory where Weaver Xtreme loads Add-on Subthemes. Add-on Subthemes are available for download from WeaverTheme.com, and are loaded in the /uploads/weaver x-subthemes/add on-subthemes/ directory. This value is useful for providing images with Add-on Subthemes.

 

 

Actions and Filters

This block lets you add arbitrary PHP code to your site. This main purpose of this feature is to allow you to add WordPress Actions and Filters for plugins and many standard WordPress actions and filters. This is a very advanced option, and some understanding of PHP code and how WordPress actions and filters work is expected.

Technically, any PHP code you add here will be executed at the very beginning of the theme's header.php template file. This file does not get loaded and executed until the core WordPress engine has loaded the main theme files ( e.g., functions.php ), so it will be too late to add actions or filters for many WordPress options. But any actions or filters used to generate content of a page can be added at this point of execution. However, the code can not be used to override pluggable functions in the theme's functions.php file.

You can add arbitrary PHP code here, but normally this code will just be add_action and add_filter calls, plus supporting function definitions. You can probably add enqueue_style and enqueue_script functions as well, as those functions are typically used later in the header.php file.

The code you define is executed using the PHP eval( ) function. Any PHP errors will cause failure of the site to load properly. Specifically, you should NOT wrap the code with <?php at the beginning and ?> at the end. You can use them within the code as needed.

 

Weaver Xtreme Helper Classes

Weaver Xtreme provides quite a few helper classes that can be used to help style your content. You can used these in the any of the PlusHere's a short summary.

Styling Hints

The following section has various styling hints, including specification of classes that can be used for custom styling.

Styling Titles

The Weaver Xtreme title options have been designed for a uniform appearance. There are really two kinds of titles used on pages - the title of the page, and the title of posts displayed on various pages. The default Blog page does not have a page title, and the title of a post displayed on the Single Page View is displayed just like a regular page. The informative title included on archive-like pages will normally be styled like Page titles, but there are options on the Content Areas tab to customize those.

You can also customize any title on any kind of page with these classes:

Title for Page-like pages: ( Standard Page, Attachment, 404 ):

 All the same ( the default ):
    .page-title {}

Just Pages:
    .page .page-title {}

Standard Page titles:

    .page .page-title {}

Attachment:
    .attachment .page-title{}

404:
   .error404 .page-title {}

The Post Single View Page (Default is same styling as standard Pages )

    .title-single {}
      -or-
    .single-post .page-title {}

Non-blog Archive-like pages

Tag archives:
    .title-tag {} /* title of tag archive page */
      -or-
    .tag .page-title {}

    .tag .post-title {} /* post titles on the .tag page */

   .archive .post-title{} /* post titles on ANY archive-like page */

Category archives:
    .title-category {}  /* title of category archive */
      -or-
    .category .page-title {}

    .category .post-title {} /* post titles on category archive */

Date archives:
    .title-archive {}
     -or-
    .date .page-title {}

    .date .post-title{} /* post titles on date archives */

Search:
    .title-search {}
     -or-
    .search-results .page-title {}

    .search-results .post-title {}

Author:
    .title-author {}
     -or-
    .author .page-title {}

    .author .post-title {}

Page With Posts:

.weaverx-page-pwp .page-title {}

.weaverx-page-pwp .post-title {}

 

 

Weaver Page Templates

 

Custom User Interface Messages

A request we often get is the ability to customize user interface messages such as "Reply", "Previous/Next Post", and others. Weaver Xtreme now provides the ability to do this using standard WordPress filters. This section will list all the available filters to modify User Interface messages.

Note that some values, such as the "Continue Reading" message already have a built-in option due to popular demand. These messages can be changed either with a filter, or using the option.

These filters can't be added directly by Weaver Xtreme, but are easily added using the new Weaver Xtreme <HEAD> Section Actions and Filters option provided by the Weaver Xtreme Plus plugin.

For example, to replace the built in Older/Newer Blog Navigation messages, add these filters to the Actions and Filters box:

/* Add filters to change the Older Blog Navigation messages */
add_filter( 'weaverx_older_posts','wx_older_posts' );
function wx_older_posts( $older ) {
    return 'Back!';
}

The original message, including wrapping HTML for many strings, will be passed in to the filter using the single parameter. You can return whatever string you want, including your own HTML wrapping and styling. You have total flexibility in what message comes out. You would define similar filters for any of the following defined Weaver Xtreme filters.

Filters labeled with ( %s ) mean that the subject of the title ( mostly archive page titles ) will be used in place of the %s. If you want the extra title info, then you need to include the %s in your filter replacement. Technically, the title uses sprintf to add the specific information to the main title. For example, the tag archive default title is "Tag Archives: %s". The tag name will be filled in to the %s position - "Tag Archives: Post Formats".

If you don't know PHP programming, join the crowd! But it isn't that hard to simply use the above example to create your own custom message text for the various elements described in the list below. For example, suppose you want to change the text on the "Post Comment" button for comments. It is a pretty easy 4 step process - you can repeat for any of the filters listed below changing to appropriate names.

  1. Copy the above example into the Actions and Filters box.
  2. Change the 'weaverx_older_posts' to 'weaverx_post_comment_form'.
  3. Change the 'wx_older_posts' to 'wx_post_comment_form'.
  4. Finally, change the 'Back!' to whatever you want.

User interface message filters supported

  1. 'weaverx_older_posts', 'weaverx_newer_posts' - replace the Older/Newer and Previous/Next Blog Navigation Style for navigating blog posts.
  2. 'weaverx_more_message' - the Continue Reading message ( already has built-in option )
  3. 'weaverx_tag_archives' - page title for tag archives ( %s )
  4. 'weaverx_404_title' - page title for 404 page
  5. 'weaverx_yearly_archives', 'weaverx_monthly_archives', 'weaverx_daily_archives' - archive page title ( %s )
  6. 'weaverx_author_archives' - Author Archive page title ( %s )
  7. 'weaverx_category_archives' - Category Archives page title ( %s )
  8. 'weaverx_search_results' - Search results page title ( %s )
  9. 'weaverx_comments_title' - Title of comments section
  10. 'weaverx_newer_comments', 'weaverx_older_comments' - Older/Newer comments links
  11. 'weaverx_leave_reply_blog' - Leave a reply ( blog page version )
  12. 'weaverx_reply_1' - Original: ''<b>1</b> Reply' ( blog page version )
  13. 'weaverx_reply_many' - Original '<b>%</b> Replies' ( % replaced by number of replies ) ( blog page version )
  14. 'weaverx_leave_reply_form' - Leave a Reply message on comment form
  15. 'weaverx_cancel_reply_form' - Cancel Reply message on comment form
  16. 'weaverx_post_comment_form' - Post Comment button on comment form
  17. 'weaverx_site_title' - The site title
  18. 'weaverx_tagline' - Site tagline

The strings associated with the Post top and bottom Meta information lines are not suitable for this type of filtering due to some technical limitations. The Weaver Xtreme Plus plugin provides the Custom Post Info Lines option to create custom wording and layout for these lines.

Weaver HTML <div> Hierarchy

The Weaver theme generates content that is wrapped in HTML <div>'s with a set of conventional names. A typical site page will have the following hierarchy. Knowing this can help you make additional custom modifications. ( Another useful thing to do is to use the "View Document Source" option of your web browser to see the actual HTML generated by WordPress for your site content. ) This example is a standard page with a Right Sidebar layout. The locations of the sidebar areas will differ for different layouts. Moving the menu by options will change where it is located. ( Important note: the names and order of these <div>'s have changed significantly since Weaver II! )

body
    #inject_prewrapper
    #wrapper                        - wraps whole site

        #header                     - wraps everything in the header
            #inject_header          - right after #header start
            .menu-secondary          - secondary menu ( top ) ( .menu-secondary.wvrx-menu-wrap )
            #header-widget-area     - the header widget area
            #branding               - the header area
            .title-tagline{-over}   - wraps #site-title and #site-tagline
                #site-title span    - site title
                #header-search      - the search button
                #site-tagline       - the site tagline
                #nav-header-mini    - header mini menu
            #header-image           - the header image
            #header-html            - the header HTML area
            .menu-primary            - primary menu ( bottom ) ( .menu-primary.wvrx-menu-wrap )

        #container                  - wraps infobar, content, sidebars
            #infobar                - info bar, if after menu bar
            #primary-widget-area    - the primary widget area ( if stacked layout )
            #content                - wraps page or post content
                #?-top-widget-area  - the various top widget areas
                #nav-above          - Previous/Next for blog pages
                <article>           - page or post content
                #nav-below          - Previous/Next for blog pages
                #?-bottom-widget-area - various bottom widget areas
            #primary-widget-area    - the primary widget area ( if non-stacked layout )
            #secondary-widget-area  - the secondary widget area ( always after content )

        #inject_prefooter
        #colophon                   - the footer area
            #footer-widget-area     - wraps footer widget areas
            #footer-html            - the footer HTML area
            #site-ig-wrap           - wraps footer bottom line
                #site-info          - copyright
                #site-generator     - powered by
    #inject_postfooter              - last thing, outside #wrapper

 

Different kinds of Pages - HTML 

<!-- **** Example Page HTML  **** -->

<body class="page page-id-146 page-template-default singular weaverx-page-page weaverx-sb-right">
    ...
<div id="content" role="main" class="layout-styles">
    <article id="post-146" class="post-146 page type-page content-page">
        <header class="page-header">
            <h1 class="page-title ">Lorem Ipsum</h1>
        </header><!-- .page-header -->
        <div class="entry-content">
            <p>Lorem ipsum dolor sit amet.</p>
        </div><!-- .entry-content -->
    </article><!-- #post-146 -->
</div><!-- /#content -->
    ...
</body>


<!-- **** example default Blog Page ( as Home page ) **** -->

<body class="home blog weaverx-page-blog weaverx-sb-right">
    ...
<div id="content" role="main" class="layout-styles">
    <nav id="nav-above">
		<div class="nav-previous"><a href="http://example.com/page/2/" ><span class="meta-nav">&larr;</span>
Older posts</a></div>
		<div class="nav-next"></div>
	</nav><div style="clear:both"></div><!-- #nav-above -->
    <article id="post-1241" class="post-1241 post type-post format-standard category-uncategorized
        tag-template content-default post-area post-odd post-order-1 "><!-- POST: standard -->

        <header class="entry-header">
            <h2 class="post-title "><a href="http://example.com/post-slug/"
                title="Permalink to Post Slug" rel="bookmark">Post Slug</a></h2>
            <div class="entry-meta ">
            <span class="meta-info-wrap">
                <span class="sep posted-on">Posted on </span><a href="http://example.com/post-slug/" title="7:07 am"
rel="bookmark">
                   <time class="entry-date" datetime="2012-01-07T07:07:21+00:00">January 7, 2012</time></a>
                   <span class="by-author"> <span class="sep"> by </span> <span class="author vcard">
                    <a class="url fn n" href="http://example.com/author/themedemos/" title="View all posts by themedemos"
                       rel="author">themedemos</a></span></span>
                </span><!-- .entry-meta-icons -->
            </div><!-- /entry-meta -->
        </header><!-- .entry-header -->

        <div class="entry-summary"> <!-- EXCERPT, uses entry-content for full post content -->
            <p>Lorem ipsum dolor sit amet.
            <a class="more-link" href="http://example.com/post-slug/">
                <span class="more-msg">Continue reading &rarr;</span></a></p>
        </div><!-- .entry-summary -->

        <footer class="entry-utility"><!-- bottom meta -->
            <div class="meta-info-wrap">
            <span class="cat-links"><span class="entry-utility-prep entry-utility-prep-cat-links">Posted in</span>
                <a href="http://example.com/category/uncategorized/" rel="category tag">Uncategorized</a></span>
                <span class="sep"> | </span><span class="tag-links">
                <span class="entry-utility-prep entry-utility-prep-tag-links">Tagged</span>
                <a href="http://example.com/tag/template/" rel="tag">template</a></span>
            </div><!-- .entry-meta-icons -->
		</footer><!-- #entry-utility -->
        </div>
    </article><!-- /#post-1241 -->

    ... more posts ...

    <nav id="nav-below">
		<h3 class="assistive-text">Post navigation</h3>
		<div class="nav-previous"><a href="http://example.com/page/2/" ><span class="meta-nav">&larr;</span>
Older posts</a></div>
		<div class="nav-next"></div>
	</nav><!-- #nav-below -->
</div><!-- /#content -->
    ...
</body>



<!-- **** Example Single Page View **** -->

<body class="single single-post postid-1241 single-format-standard singular weaverx-page-single weaverx-sb-right">
    ...
<div id="content" role="main" class="l-content-rsb m-full s-full ">
    ... .nav-previous, .nav-next links ...
    <article id="post-1241" class="post-1241 post type-post format-standard category-uncategorized
        tag-template content-single post-content post-area ">
    	<header class="page-header">
    	<h1 class="page-title  title-single ">Post Slug</h1>
		<div class="entry-meta ">
            ... see blog example for .entry-meta content
        </div><!-- /entry-meta -->
	</header><!-- .page-header -->
    <div class="entry-content">
    ... see blog post example for .entry-content, .entry-utility

    ...
</body>



<!-- **** Example Single Page View **** -->

<body class="attachment page page-id-1711 page-child parent-pageid-1133 page-template-default
  singular weaverx-page-image weaverx-sb-right">
    ... remaining similar to other pages ...



<!-- **** Example Archive-like Views **** -->

<body class="archive date weaverx-page-archive weaverx-sb-right">   <!-- Date Based Archives -->
    <div id="content" role="main" class="layout-styling">
        <header class="page-header">
            <h1 class="page-title  archive-title title-archive"><span><span class="title-archive-label">
            Monthly Archives: </span><span class="archive-info">September 2014</span></span></h1>
        </header>
        ... posts - same as blog ...
    </div>
</body>

<body class="archive tag tag-content tag-79 weaverx-page-tag weaverx-sb-right"> <!-- Tag archives -->
    ...
    <header class="page-header">
        <h1 class="page-title  archive-title title-tag"><span><span class="title-tag-label">
        Tag Archives: </span><span class="archive-info">content</span></span></h1>
    </header>
    ...

<body class="archive category category-markup category-29 weaverx-page-category weaverx-sb-right">
    ...
    <header class="page-header">
		<h1 class="page-title  archive-title title-category"><span><span class="category-title-label">
        Category Archives: </span><span class="archive-info">Markup</span></span></h1>
        <div class="category-archive-meta"><p>Posts in this category test markup tags and styles.</p>
        </div>  <!-- shown if tag/category description provided -->
    </header>
    ...

<body class="search search-results weaverx-page-search weaverx-sb-right"> <!-- Search -->
    ...
    <header class="page-header">
        <h1 class="page-title  archive-title title-search"><span><span class="title-search-label">
        Search Results for: </span><span class="archive-info">"content"</span></span></h1>
    </header>
    ...

<body class="search search-no-results weaverx-page-search weaverx-sb-right"> <!-- failed search -->
    ...

Weaver Xtreme Class Reference

This section contains a comprehensive reference to the different HTML areas used by Weaver Xtreme, and the classes used to style those areas.

body

The classes added to the body tag, both by WordPress and by Weaver Xtreme. The list of classes added by WP is not necessarily comprehensive - WP will add more specific classes in various views.

#wrapper - wraps entire site

The area wraps the entire site, and provides the global width, font, and colors.

#header

Site Title

#site-title
Site Title with link
#site-title a
Site Tagline
#site-tagline
Header Image
#header-image img
Header Title, Tagline, Search, Header, Mini Menu
#branding
Header Search
#header-search
Header Mini-Nav
#nav-header-mini .menu
Header HTML Area
#header-html
 
 
 
 

#container

This area wraps the #content and the primary and secondary sidebars.

#colophon

This wraps footer content.

Other Classes

#comment-title.no-comments-made - .no-comments-made is added to the #comments-title <div> if no comments have been made yet.

Filters Used by Weaver Xtreme Engine

Weaver Xtreme processes some content through filters. Short descriptions of the filters used by Weaver Xtreme follow. It will likely be most instructive to look at the actual source code to better understand some of these filters.

weaverx_404_title

weaverx_options

weaverx_daily_archives

weaverx_monthly_archives

weaverx_yearly_archives

taxonomy_archive_meta

weaverx_author_archives

weaverx_category_archives

category_archive_meta

weaverx_comments_title

weaverx_older_comments

weaverx_newer_comments

weaverx_reply/comment_form

weaverx_site_title

weaverx_tagline

weaverx_attachment_size

weaverx_older_posts, weaverx_newer_posts

weaverx_more_message

edit_post_link

weaverx_leave_reply_blog

weaverx_posted_on, weaverx_posted_in

weaverx_author_bio_avatar_size

weaverx_replace_widget_area

weaverx_menu_name

weaverx_menu_class

filtername

Advanced Filters

The following filters require knowledge of the item format ( usually an array ), and are usually used for Xtreme Plus to add new options. These can be added to a new option interface, but will require an understanding of the underlying code, and usually extra CSS style rules to support. Search the code for these filters to see what they do.

'weaverx_add_font_size', 'weaverx_add_font_family', 'weaverx_add_shadows',

Actions Called by Weave Xtreme Engine

Weaver Xtreme calls some actions. Many of these are used to interface with Weaver Xtreme Plus, but these could also be defined by a child theme. Some are specific to a child theme. Short descriptions of the actions by Weaver Xtreme follow. It will likely be most instructive to look at the actual source code to better understand some of these calls.

weaverx_child_siteoptions

weaverx_child_process_options

weaverx_child_saverestore

weaverx_child_update

weaverx_child_show_extrathemes

weaverx_nav

weaverx_post_header

weaverx_per_page

weaverx_per_post

weaverx_breadcrumbs

weaverx_paginate

do_action

Pluggable functions

A "pluggable" function is one that can easily be overridden in a child theme.

weaverx_setup( )

weaverx_init_opts( $who='' )

weaverx_register_header_images( )

weaverx_admin_header_style( )

weaverx_register_sidebar( $name, $id, $desc, $altclass='' )

weaverx_comment( $comment, $args, $depth )

weaverx_comments_popup_link( )

weaverx_content_nav( $nav_id )

weaverx_continue_reading_link( )

weaverx_edit_link( $echo = 'echo' )

weaverx_entry_header( $format_title='', $do_excerpt = false )

weaverx_post_title( $before='', $after='' )

weaverx_link_pages( )

weaverx_not_found_search( )

function

function

function

function

function

function

function

function

function

function

function

 

 

 

 

Weaver Xtreme and this document are © 2010-2014, Bruce E. Wampler. Web Site - WeaverTheme.com