A short guide to using Flag Vista

When a user flags an item with the Flag module, a record --or "information"-- is written somewhere in the database. This record is known as a flagging. To be able to do almost anything, we first need to "pull in" this information.

The way to pull-in information in Views is by using relationships.

Listing flagged items only

Let's start a new view, of type "Node". Click the "+" in the Relationships box. You'll then notice that Flag Vista provides several relationships. Of the most important ones are:

• Node: Flaggings
• User: Flaggings
• Comment: Flaggings

Each relationship is used to pull-in flaggings of the certain type.

Let's add the "Node: Flaggings" relationship. In the next screen we will be asked to choose the flag we're interested in (e.g. "bookmarks", "spam", "been here").

Pay attention to the "Require this relationship" checkbox, which is turned on by default. It will cause only flagged items to be listed in your views. That's because flagging records exist for flagged items only. Sometimes, and quite frequently, this feature is the only functionality we're after.

Once the flagging relationship is added you'll have access to the "Flagging: Flagged time" field. If you're a beginner, or otherwise stuck, it's recommended that you (temporarily) add this field to your view because it will help you "see" the flaggings: they are actually tangible things and not merely some abstract concept.

Displaying a flag/unflag link

To display flag/unflag links you don't need to bring in any relationship. The link field is attached directly to the item it operates on; for example:

• Node: Flag link
• User: Flag link
• Comment: Flag link

Filtering

Flag Vista has one interesting feature: When you pull-in the "Node: Flaggings" relationship you don't have a pick a single flag: you can pick several flags. Later you can add the "Flagging: Flag" filter or argument to your view to limit these flaggings to those belonging to a certain flag. This is especially handy when exposing this filter. (You may need to turn on the Distinct setting to get rid of duplicate records if you're not limiting the choice to a single flag.)

The ability to pick flaggings of several flags also makes it possible to create interesting views that utilize the new Grouping feature of Views 3.x.

Counters

Whenever an item is flagged, or unflagged, a counter field is updated in the database. This field records the number of times this item is currently flagged --by all users. It records the "popularity", if you wish, of this item. To access this field, you must first bring in the flagging statistics relationship. The counter field resides there. The process is identical to the described above, but the name of the statistics relationships have "statistics" appended to them:

• Node: Flagging statistics
• User: Flagging statistics
• Comment: Flagging statistics

Once you add a statistics relationship, you'll be able to show the counter field, filter by it, and sort by it.

Tip: Optionally, untick the "Require this relationship" checkbox to include in your view also items that have not been flagged (allowing you to display "Total flagged: 0").

Trivia: Currently, the counter is the only field the statistics relationship holds. But in the future we may have a "last time flagged" field as well.

Tip: The statistics relationship serves yet another purpose: since it exists for flagged items only, it's the only means to answer a "show me all the flagged items, by any user" query, without causing duplicate rows.

The flagging user

There are two kinds of users in our system:

1. The user who authored the item ("item" being a node or a comment, for example).
2. The user who flagged this item.

Usually, any mention of "User" in Views' User Interface relates to the first kind: the user who authored the item.

But sometimes we want to see, or operate on, the second kind: the user who flagged the item. For example, we may want to filter the items to only those which were flagged by a certain user. Or we may simply want to print the name of this flagging user alongside of the item.

To have access to the user who flagged the item, we must first add the "Flagging: User" relationship to the view.

Once we do this we will notice that many fields/filters/arguments now have a "Relationship:" dropdown. This dropdown tells Views to which of the two users we want to relate.

Other relationships

Flag Vista provides additional relationships not mentioned above. They are listed here briefly. Their purpose usually becomes clear when the need for them arises.

• "User: Flaggings by user"
• "Flagging: Flagged node" (or comment, or user)
• "Flagging: Flag
• "Flagging statistics: Flag
• "Flag: Flaggings"