Solspace Documentation

Diggie :: Getting Started

Welcome to the Getting Started area for Diggie!

A typical usage for Diggie is allowing your users to vote your weblog entries up or down. From there, you're obviously going to want to be able to show the current vote counts for your entries, as well as display lists of entries in order by the highest votes. This tutorial will show you how to do all that, as well as get yourself set up in the CP area. Be sure to check out the full Documentation for Diggie to see what else you can do.

Installation

To install Diggie, follow these simple steps:

  1. Download Diggie and unzip the files
  2. Open up the "modules" folder and upload all files in the "diggie" folder to your "system/modules" directory
  3. Open up the "language/english" folder and upload the "lang.diggie.php" into the appropriate sub-folder of your "system/language" directory
  4. Go to your "Modules" tab inside your EE control panel. Find the Diggie module in the list and click "Install"
  5. That's it! If you encounter any issue, please visit our Support Forums

Configuration & Setting up Flags

Other than setting up Flags, there isn't too much to configure with Diggie.

Configuration

To adjust any settings for Diggie, click on the Preferences tab in the module CP area. Currently there is only 1 option called "Votes Per User Per Item". This setting controls how many times a user can vote for an entry. The default setting is "2". If you'd like to allow more or less votes per entry per user, adjust this number accordingly. Also to clarify, each time a user makes an additional vote on the same entry, it is NOT cumulative - it only changes their vote.

Setting up Flags

By default, Diggie is already set up with 3 flags: "Up" (+1), "Neutral" (0), and "Down" (-1). To add, modify or remove and Flags, click on the Flags tab in the module CP area. To edit any of the existing flags, just click on the name. To create a new flag, click the "Create a New Flag" button at the top right corner of the page. Let's create a new Flag:

  1. In the "Flag Name" field, type in "boring". This will be the short name used to call this flag later on. Remember, lowercase, no special characters and no spaces
  2. In the "Flag Label" field, type in "Boring". This is the full name of the flag that will be displayed on your site later on
  3. In the "Flag Message" field, type in "Thanks for voting! You voted this item "Boring" (-3)". This is the message that will be displayed to your users when they vote this flag for any entry
  4. In the "Flag Value" field, type in "-3". This is the value of the flag that will be applied to the overall score of your entries when voted
  5. Click the "Update" button and the flag will be saved

Allowing your users to Vote

This is obviously the key part of Diggie. How do you allow your users to vote on your weblog entries? Well, there's 2 very similar methods, but we'll show you one way.

Message & Error Handling

Let's first create a new EE template group called "diggie". Then, create a new template called "vote". In your "vote" template, place in the following code:

<ul>
{exp:diggie:vote item_id="{segment_3}" flag_id="{segment_4}"}
{diggie:errors}
<li>{diggie:error}</li>
{/diggie:errors}
{if diggie:message}
<li>{diggie:message}</li>
{/if}
{/exp:diggie:vote}
</ul> 

This template will serve as the Message and Error handling when a user votes for an entry. It also assumes that the Entry ID and the Flag ID will be passed through the 3rd and 4th segments in the URI.

Voting Links

Next, you'll need to then create a new template in your "diggie" template group called "entry". This will replicate your typical Single Entry page that you would display a full weblog entry on. You can of course apply this code to any existing template, but we'll use this one for example purposes. In this template, insert the following code:

{exp:weblog:entries}
<h2>{title}</h2>
<p>{body}</p>
 
{exp:diggie:stats item_id="{entry_id}"}
<h4>Vote for this Entry</h4>
<ul>
{diggie:item_flags}
<li><a href="{path="diggie/vote"}{entry_id}/{diggie:flag_id}/">{diggie:flag_label}</a></li>
{/diggie:item_flags}
</ul>
{/exp:diggie:stats}
{/exp:weblog:entries} 

As you can see, all of Diggie's variables and variable pairs are prepended with "diggie:". This allows us to use Diggie code within the Weblog:Entries loop without worrying about variable collisions (when both loops use the same variables, usually the Weblog:Entries loop will override the parsing). It's also easier to set apart Diggie code from other code.

The result of this code will output a list of all available Flags in the Diggie module. When a link is clicked by the voter, it takes them directly to the "vote" template where their vote will be recorded and a message will be displayed to them.

Displaying Stats

What good would Diggie be if you couldn't display stats for your weblog entries. Using the same "entry" template as noted above, we're going to add just a little more code to it:

<h4>Stats for this Entry</h4>
<ul>
<li>Total Votes for this entry: {diggie:total_votes}</li>
<li>Total Cumulative Score for this entry: {diggie:vote_value}</li>
<li>Total Vote Average for this entry: {diggie:vote_average}</li>
</ul> 

So, if we insert that code into the template code noted earlier, it would look like this:

{exp:weblog:entries}
<h2>{title}</h2>
<p>{body}</p>
 
{exp:diggie:stats item_id="{entry_id}"}
<h4>Stats for this Entry</h4>
<ul>
<li>Total Votes for this entry: {diggie:total_votes}</li>
<li>Total Cumulative Score for this entry: {diggie:vote_value}</li>
<li>Total Vote Average for this entry: {diggie:vote_average}</li>
</ul>
 
<h4>Vote for this Entry</h4>
<ul>
{diggie:item_flags}
<li><a href="{path="diggie/vote"}{entry_id}/{diggie:flag_id}/">{diggie:flag_label}</a></li>
{/diggie:item_flags}
</ul>
{/exp:diggie:stats}
{/exp:weblog:entries} 

You now have a functioning Diggified single entry view template ready for use!

Ordering your Entries by Top Votes

There's just one thing left to do! You'll more than likely want to display and order your weblog entries by most popular votes. You can rank your entries by "vote_value", "vote_count" or "vote_average". The most common method is total cumulative "vote_value", so that's what we'll use in this example.

First, create a new template in your "diggie" template group called "rank". Then, insert the following code:

<h2>Highest Ranking Entries</h2>
 
<ul>
{exp:diggie:rank orderby="vote_value" limit="25"}
<li>[{diggie:vote_value}] <a href="{url_title_path="diggie/entry"}">{title}</a></li>
{/exp:diggie:rank}
</ul> 

And remember, there's a lot more you can do with Diggie. Whether you want to tweak some of the above examples, or add a feature not mentioned here, make sure you check out the full Documentation for Diggie.