1. Start
  2. (Pre-) Installation
  3. Quickstart
    1. Columns
    2. Count
    3. IDs
    4. Orderby
    5. Type
    6. Authors
    7. Categories
    8. Tags
  4. Advanced Boxing
    1. Creating A Block Mask
    2. Altering a Block Mask
    3. Creating A New Template
    4. Using Our New Template
    5. Adding Custom CSS Classes
  5. Sources and Credits
  6. Appendix A
    1. Below are all defined template tags you can use in your templates

WP Boxer Pro v2.2.1
(shared on wplocker.com)

Create beautiful content blocks using shortcodes

Thank you for purchasing my plugin. If you have any questions that are beyond the scope of this help file, please feel free to email me via my user page contact form here at CodeCanyon or visit the support forum. Thanks so much!

(Pre-) Installation

1. Create a Backup

ALWAYS, ALWAYS, ALWAYS create a backup of your existing content first! Really, this can save you lots of headaches and agony and takes only a few minutes (if that). 


2. Installation

Installation of WP Boxer Pro is as simple as installing any other WordPress plugin

  1. Go to Plugins | Add New | Upload
  2. Select the zipfile you downloaded from CodeCanyon and click Install Now
  3. Click Activate Plugin
     

3. Migrating from WP Boxer Free version?

If you have been using the free version of Boxer and are now migrating to WP Boxer Pro, you can convert your existing boxes. To do this, go to Settings | WP Boxer Pro and click the Upgrade button.


4. Demo Content

If you have watched the examples page at http://wpboxer.codingourweb.com/examples/ and want to play around with the content, you can. You can find the XML file inside /assets/samples/. Just import it using the WordPress Importer plugin and you're good to go.

Quickstart

Table Of Contents

A Quick Word
First Some Terminology
Creating You First Block Group
Displaying The Block Group
Other Shortcode Parameters
        Columns
        Count
        Ids
 Orderby
        Type
The Shortcode Button
So How About Other Post Types?
        Authors
        Categories
        Tags
Content Block Styling
Importing/Exporting styles
Other Shortcodes
Closing Words

A Quick Word

Once you've activated WP Boxer Pro, you are ready to start creating content blocks. This quickstart guide is meant for you if :

First Some Terminology

A content block is a structure in a webpage that consists of one or more separate sections like a header, an image and/or content. These sections all contain properties e.g. font-family, text color and CSS classes, which determine how the box will look when rendered in a browser.

Depending on the selected template none or all of these sections are implemented. You can think of a template as being the blueprint for a content block.

You can add content blocks to one or more block groups for grouping purposes.
 

Creating Your First Block Group

With all the terminology out of the way, let's get started. As you may have noticed when browsing for themes on ThemeForest.com a lot of those themes, if not all, implement some form of reference landing page. Usually they consist of three or more "content block-like" structures containing an image, a header and a short pitch.

image taken from http://www.redfactory.nl/themes/novum/

These kind of landing pages are an excellent application for WP Boxer Pro as you will learn next.

Adding a content block is just like adding a regular blog post. Follow these steps:

By default, the Box General tab will be shown. This is fine, because that is the focus of our next actions.

Tip
You can hover your mouse pointer over the question mark to find out more infromation about the prioperty

Next, head over to the Box Heading tab

 

Finally, select the Box Content tab

Repeat these steps for the second and the third content block. Make sure all properties are the same as the first box,with the following exceptions:

Nerd Alert!
Make sure the block width of the last content block in a row is always set to {width}_last. That way you're making sure the floats are cleared and your content isn't misplaced.

Examples:
one_third | one_third | one_third_last
one_fourth | one_fourth | one_half_last
one_fifth | two_fifth | one_fifth | one_fifth_last


Displaying The Block Group

Okay, great! We're almost done now. The only thing that is left for us to do, is display our newly created block group. Remember, a block group is nothing but a group of content blocks. In our case the block group named landing-page contains three content blocks. So how do we display this block group? Actually, we first have to determine where we want to display it. Block groups are displayed by typing a simple shortcode and as you might know, shortcodes can be implemented almost anywhere within your WordPress theme: headers, footers, sidebars, widget areas, you name it.

In this particular case I chose to display the block group on a new page. So once again fire up your WP admin panel.

Now, for the exciting part. In the content section of your new page, type the following:

[wpbp_blocks set="landing-page"]

It should look much like this:

How about that? With almost no effort and coding at all, we recreated the targeted landing page.


Other Shortcode Parameters

In the example above we used the wpbp_blocks shortcode with only a single parameter, set. As you might have guessed, there are a lot more parameters you can use. They are all used to fine-tune what is displayed. We will cover some frequently used ones next.

Columns

The one you are likely to use the most is columns. With columns you specify exactly how many columns you want your content block set to span. Remember, previously we declared the block widths to be one_third, one_third and one_third_last to create a block group which spans 3 columns. The columns parameter allows you to do that automagically. If any block widths are set, the columns parameter will overrule them. Let's try this out on the page we just created. Change the shortcode like this:

[wpbp_blocks set="landing-page" columns=2]

Next, update your page by clicking the Update button and view the result by clicking the View Page button. See what happened there? Although the block widths will indicate a column span of three, in reality the shortcode displays a span of two columns. Courtesy of the columns parameter.

Count

Another parameter you may find useful is the count parameter. With count you can specify exactly how many content blocks from a given set you would like to be displayed. Going back to our previous example, update your shortcode like so:

[wpbp_blocks set="landing-page" columns=2 count=2]

Although the block group landing-page contains three content blocks, only two of them are displayed. Important thing to remember is that they are sorted by block index, so the two content blocks with the lowest box index are displayed. If this is inconvenient, or you would like to display two other content blocks, you might consider using the ids or orderby parameter.

IDs

The ids parameter allows you to specify exactly which content blocks from a block group you would like to be displayed by using their IDs. But how do you find out these content block id's? Easy, in your WP admin panel go to Content Blocks | Content Blocks.

Let's assume for a minute we only want to show content blocks with ID 1404 and 1410. To do this, update your shortcode like so:

[wpbp_blocks set="landing-page" columns=2 ids=1404,1410]

Now that's convenience for you!

So, are you starting to get the hang of it now? If so, can you try to predict what happens when we remove the columns parameter from our shortcode?

[wpbp_blocks set="landing-page" ids=1404,1410]

Orderby

Orderby is the new kid on the block. You can order your content blocks by a number of predefined values, like ID, Author, Title, Date Created, Random, Comment Count, Meta Value etc. When you have specified Meta Value, you will need to also specify a Meta Key. When sorting it is best to use the shortcode wizard for convenience.

Type

The final parameter I would like to address for now is the type parameter. When the number of content blocks you use starts to grow and the templates you apply to them vary a lot, it can be a lot of work to undo this. When the need arises to make all content blocks in a group use the same Block Content Template, you should specify the type parameter.

[wpbp_blocks post_type="post" type="general-2" columns=2]


The Shortcode Buttons

As of version 1.04 WP Boxer Pro adds a few buttons to the visual editor/Wysiwyg in Wordpress.

Clicking these buttons opens up a dialog box with all available shortcode parameters, in some cases even with their possible values.

Needless to say this speeds up the process a lot!


So How About Other Post Types?

Nerd Alert!

WordPress can hold and display many different types of content. Internally, these are all stored in the same place, in the wp_posts table. These are differentiated by a column called post_type.

WordPress 3.0 gives you the capability to add your own custom post types and to use them in different ways.

So far we have only used the box custom post type. But what if we wanted to target regular blog posts? Or let's say you are using another plugin of mine, mymedia for wordpress, and you would like to display movie content in boxes? WP Boxer Pro allows you to do this by using yet another shortcode parameter, named post_type.

In the page you created earlier, add the following shortcode:

[wpbp_blocks post_type="post"]

Update the page and view the result.

See, nothing to it. You can use the same shortcode parameters you used earlier to place the content exactly the way you like. Let's try this:

[wpbp_blocks post_type="post" columns=2]

Update your page and presto!

But that's not all yet. Setting the post_type parameter to post. brings three new shortcode parameters to the table, which will be discussed next.


Authors

A new parameter you could apply is author. Let’s for a minute assume you want to show only those blog posts that were created by Herman Schnapowitz. First, you would need to determine his or her author ID. To do this, just go to Users | All users and hover over the Edit link. You should see the user_id query parameter in the status bar of your browser. This number is what we are going to use. So after you figured out the author id or id’s you would like to display, you type this:

[wpbp_blocks post_type="post" author=2]

In my particular case this renders a pretty nasty error message, because the author with an ID of 2 has not done much of anything yet!

In case you want to display multiple authors just separate the ID's with a comma.

[wpbp_blocks post_type="post" author=1,2]


Categories

Targeting a specific category or categories isn’t much different than targeting specific authors. In stead of author you should use the cat parameter and you must separate multiple category ID’s by a comma. To find out the ID of a category, go to Posts | Categories and hover over the Edit link of a category. The number you are looking for is specified in the browsers' statusbar as tag_ID.

 [wpbp_blocks post_type="post" cat=8,11,45 count=4 columns=2]

Can you tell what this shortcode does, without first watching the result?


Tags

Targeting a specific tag or tags is a bit different from targeting specific authors or categories. You must use the tag parameter but in stead of specifying an ID you must specify the tag’s slug. Multiple tags should be separated by a comma. So in short, when you want to target four posts with a tag of api or sql, use this shortcode:

[wpbp_blocks post_type="post" tag=api,sql count=4]

Nerd Alert!
Wordpress defines a slug as follows:

A word or two describing an entry, for use in permalinks (replaces the %posttitle% field therein), especially useful if titles tend to be long or they change frequently.

You can find the slug of a yag by going to Posts | Tags. The slug is mentioned in the tag table.


Content Block Styling

So far we have been really withholding when it comes to styling our content blocks. The main reason for this is that this is just a quickstart guide and a chapter about styling would take up to much space. Basically the best way to learn how to style your content blocks, is experimenting. And when I say expermimenting, I mean experimenting a lot! Start by adding or removing classes, changing colors, fonts or sizes and then view the result. As you grow more comfortable with WP Boxer Pro you can even start experimenting with your own custom styles. So for now, we'll just leave it at this.

Importing/Exporting Styles

A much requested feature was the ability to export and import styles to and from content blocks. In version 2 this feature was added to the Box General tab. 

After saving each content block will place its style in the export textarea, allowing it to be copied to any location: a file, another content blocks' import area or an e-mail message to share it with a friend.

To import this style into a content block, just copy it into the import textarea and click the import button.

The Other Shortcodes

As of version 2 a number of other shortcodes have been introduced. They use the same content blocks you have been using the entire time, they just display them slightly different. We will not review them one by one. Just use the shortcode wizard and you'll be fine.

Closing Words

If you've come this far, congratulations! You are officially no longer a boxer newby. If you feel comfortable enough you can try taking your first steps in the Advanced section, but that is totally up to you.

Advanced Boxing

Table of Contents

Word Up Front

Block Masks

Creating A Block Mask

Altering A Block Mask

Our Final Project

     Creating A New Template

     Using Our New Template

     Adding Custom CSS Classes

 

A Word Up Front

As the title of this section implies, it contains advanced material. Therefore you are advised to walk through the quickstart first and experiment with WP Boxer Pro as much as possible. Also, a thorough understanding of HTML and CSS is required. If you do not know what these terms mean, you might as well stop reading. But if you're good on all these requirements, have fun!

Block Masks

Okay, so you have been using WP Boxer Pro a lot. Then youmay have noticed it can be a tremendous amount of work to keep styles of content blocks belonging the a specific block group in sync. Take the WP Boxer Pro landing page for instance. What if I – for some reason – wanted to make the background gradient of all boxes darker. This means that I would have to modify nine content blocks to make it consistent. Sure, I could just change the responsible CSS class and make it darker, but this would affect all content blocks using this specific class, not just the ones on my landing page!

So, does this mean there is another way to accomplish this? Yes, fortunately there is another, much cleaner way of achieving the same result, block masks. You can think of Block Masks as layers that can be applied to content blocks without changing any of the content block properties. So once you remove a mask from a content block, the content block renders exactly like it did before. Excited? Great, let’s put this to the test. For this example, I will use the landing page of the WP Boxer Pro website.

Creating A Block Mask

Let's assume for a minute that I want to change the font-family of the block headings and set their color to orange. Without knowledge about the existence of block masks I would have to:

  1. Open up the first content block in the set
  2. Change the font-family
  3. Change the color
  4. Update the content block
  5. View the result
  6. Repeat the previous steps for the other 8 content blocks

As you might guess, this is a lot of work. So we're definately not going to follow this path. In fact, all we're going to do for now is execute the first five steps. Open up the content block "Zero Coding Skills" and change the properties of the block heading like this:

When you execute steps #4 and #5 you'll notice only the first box has changed.

So how do we copy the style of this first content block over to the other eight? Actually there are two ways of accomplishing that, but first let's create a block mask. Go back to the properties of the first content block and open up the Block Masks tab.

After you click the Save button, the block mask is created. Now, quickly update your content block and view the result.

Disappointed? You shouldn't be, because now we're going to apply the block mask to the other 8 content blocks. Actually there are two ways of doing this:

  1. Apply the block mask to all required content blocks separately
  2. Apply the block mask through the shortcode

In this particular situation we are better off using option #2, because we want to apply the mask to all content blocks in the group. If we were to apply the block mask to only a selection of the content blocks in the group, we'd have to go with option #1.

So, go to the Home page and change the shortcode.

[wpbp_blocks set="home" mask="block-mask-1"]

Update the page and view the result.

So, in closing, we considerably reduced the amount of necessary actions.

Altering a Block Mask

If you want to modify an existing mask, follow these steps:

  1. Again open up the first content block in the set
  2. Make the necessary changes
  3. Update the content block
  4. Create a block mask specifyng the same name and click Save

The changes will overwrite the existing block mask and will immediately be applied to all content blocks in the group.

Suppose I just wanted to roll back the changes to my landing page. Actually, that's really easy too.

Because no actual changes were made to content blocks #2 through #9, you only need to alter content block #1. After you remove the block mask from the shortcode, it will appear like nothing happened.

 

Our Final Project

Take a close look at the next picture, because that's what we are going to create next.

The above images are taken from the Impulse WordPress theme on Themeforest.net

When I brake it down, I come up with the following tasks:

  1. Create a new template
  2. Add a CSS class for background and border
  3. Create a block mask to copy the style over to the second content block (cause we're lazy)


Creating A New Template

Because none of the existing templates can be used for this particular idea, we need to create our own. This is actually pretty easy because we can copy and paste a lot of stuff from another template. But first things first, let's look at what we need to template.

I have color-marked all sections we need to consider when creating our template. We have the darkblue box image, the lightblue box heading and finally the pink box content that make up the templates' inner workings. These are the three main sections you will see in almost all templates. The orange date and green dotted line are specific to this template. The red wrapper will not be a part of the template!  We will have to create a new CSS class to apply the greyish background and border to the box.

After a little puzzling I came up with this template:

  

{% spaceless %}

{% include '_partials/_image.tpl' %}
<div class="box_content">
   <div class="one_half">
      <div style="border-right: 1px dotted #CCC;min-height:111px;">
         <span class="date" style="color:#C1C1C1;font-size:12px;margin-bottom:8px;">{{ date }}</span>
         {% if box.header.show == 1 %}
            {% include '_partials/_header.tpl' %}
         {% endif %} 
      </div>
   </div>
   <div class="one_half last">
      {% include '_partials/_content.tpl' %}
   </div>
   {% if box.footer.show == 1 %}
      {% include '_partials/_footer.tpl' %}
   {% endif %} 
</div>

{% endspaceless %}

Nothing really fancy here, just HTML, inline CSS, Twig variables ( {{ var }} ) and control structures ( {% %} ) to mimic the picture above. Notice how I use the predefined partials like _image, _header, _content and _footer? 

For a detailed view of all template variables you can use, have a look a Appendix A

Save the above template in a file named impulse.tpl and place it in the templates folder inside the plugin.

Next, we have to create an image for our template. This image will show up in the Content Block Options metabox and should resemble the template as much as possible. WP Boxer Pro provides you with a PSD file which you can manipulate to create a custom template image. Download it here if Photoshopping isn't your thing.

And we're all done!

Using Our New Template

Next step in our final project is adding two boxes based upon our newly created template.

In the Box General section of the Content Block Options metabox

In the Box Image section of the Content Block Options metabox

In the Box Heading section of the Content Block Options metabox

In the Box Content section of the  Content Block Options metabox

Finally, save the content block by clicking the Publish button. To copy the style from this content block to the second we will create a block mask. So head over to the Block Masks tab, specify a unique name (e.g. impulse) and click Save.

For the second content block use this data (do not set any markup):

Title: Unique eye makeup ideas Content: Far far away, behind the word mountains, far from the countries Vokalia and Consonantia, there live the blind texts. Image: download Block Group: impulse Block Width: one_half_last Block Index: 2

After having published the second post, we need to specify the shortcode that will render our content. In my case I will add it to the Other Examples page using this shortcode:

[wpbp_blocks set="impulse" mask="impulse"]

and view the result.

The only thing that is missing is the background color and border. But we're going to fix that next.

Adding Custom CSS Classes

Remember when I said earlier that the red wrapper in the breakdown picture would not be a part of the template? Because the red wrapper encompasses the entire box, we need to find a way to hook into the Box General section of the Content Block Options metabox. Any class we specify in that section will be applied to the entire box.

Back to our project, we need to add a CSS class that will create the background and border as displayed in our target image. You will find all CSS classes in a file named /assets/css/style.css. Open it up and look for a section named Frames. At the bottom of that section append this code and save the file:




	
.content_block .impulse-frame {





	    background: #FBFBFB !important;



	    border: 1px solid #F7F7F7;



	}



	Next, we need to tell our plugin about this new class. To do so, open up /wpboxerpro.php, look for the $frames variable and add the name of our new CSS class.


$frames = array(
    "dark", "frame", "large", "wp-frame", "impulse-frame"
);




	After having created this class, the next step is to apply it to the content block.




	When you view the result now, you'll notice nothing changed. So why do you think this is? Exactly, we added the mask parameter to our shortcode. That means changes to individual content blocks will be overruled by the block mask. What we need to do is redefine the block mask.



	Go to the Block Masks tab of the first content block in the set (the one about Kelly), specify the same name you chose earlier and click Save. When you view the result now, you'll notice the background and border have been applied.



	And that wraps up our little project.





	
Sources and Credits



	I've used the following images, icons or other files as listed, so special thanks go out to:






	Once again, thank you so much for purchasing this plugin. As I said at the beginning, I'd be glad to help you if you have any questions relating to this plugin. No guarantees, but I'll do my best to assist. If you have a more general question relating to the plugins on CodeCanyon, you might consider visiting the forums and asking your question in the "Item Discussion" section.



	Mark Boomaars (from CodingOurWeb)





	
Appendix A


Below are all defined template tags you can use in your templates



	box.author.ID



	box.author.user_name



	box.author.display_name



	box.author.homepage



	box.bgcolor



	box._bgcolor



	box.class



	box.content.align



	box.content.bgcolor



	box.content.color



	box.content.columns



	box.content.text



	box.content.class



	box.content.font_size



	box.content.font_family



	box.content.line_height



	box.date



	box.date_format



	box.footer.show



	box.header.align



	box.header.bgcolor



	box.header.color



	box.header.text



	box.header.class



	box.header.font_size



	box.header.font_family



	box.header.line_height



	box.header.height



	box.header.show



	box.height



	box.ID



	box.image.class



	box.image.src



	box.image.height



	box.image.width



	box.link



	box.pagination



	box.template



	box.time



	box.type



	box.width