Tracking SharePoint Popular Items Accessed through JavaScript

Applies to: SharePoint 2013+

A while back I wrote an AngularJS app running in SharePoint 2013 and using lists as the backing store for some components. Without getting into the reasons this particular architecture was chosen, let’s look at an issue that came up.

The client asked us to show the popular items. There is a standard web part for this, but you can also query the search API directly by sorting by ViewsLifeTime:descending which is what we did so that we could display it in a custom Angular directive. No problem! Right?

It wasn’t until some time later that the client asked about the results we were displaying. The most “popular” items appeared to be the ones they had had trouble with behind the scenes and didn’t match their expectations about what users would be viewing.

Unpopular

When you view a list item (dispform.aspx?id=X) this view is tracked in SharePoint’s Usage Analytics (assuming you’ve configured this correctly). It’s this information that is used by search to determine an item’s popularity.

Unfortunately, it turns out pulling items from the REST API triggers no such view event. This seems obvious in retrospect, but until we really thought about it, usage tracking is just one of those magical behind the scenes things SharePoint does and we just assumed it would work.

This explains the results the client was seeing. The items they were having trouble with are the ones they were viewing directly (outside of the Angular app). While this wasn’t a ton of traffic, it was far more than any other list item was getting since they were only being viewed via the REST API inside a custom application. Ugh.

Fortunately, the fix for this isn’t too complicated, it’s just not very obvious.

Spoofing Item Views in JavaScript

You can log a View event using the SP.Analytics.AnalyticsUsageEntry.logAnalyticsEvent2 method. I had trouble finding any helpful documentation on this method or what the parameters should be. Fortunately, after some experimentation (and patience as the entries are not immediately available), I got it working.

Here’s the basic JS code which you can then adapt and make smarter:

For instance, I adapted the above into an AngularJS service and wrapped the call to get the site Id and user into a promise so that I only had to pull that once in my app, but all of that is up to you.

One nice thing about doing this manually is you can control when it fires. For instance, you might want to only log usage during reads but not during edits or exclude administrative accounts, etc.

That’s it! Now your custom interface can participate in the internal popularity contest!

Setting the Accent Color of Your Modern Site’s Custom Theme

Modern pages in Office 365 let you “Change the Look” by providing a number of themes (sets of colors) that can be applied to your site (available from the gear menu in the top-right of the screen). The interface is pretty slick, it takes immediate effect, and the default options are so much better than those weird sets of themes from the classic days.

You can even do minor customization by clicking the customize link under your chosen theme. You can choose from one of the preselected primary colors and an accent color (designed to match your primary). Generally, these colors are great and have been selected to look good in most scenarios.

CustomizeColorsInUI

But I can’t pick the exact shade of red marketing has decreed that all things must be! Fortunately, you can create your own theme with the exact colors you want. You can even generate these using the UI Fabric Theme Generator. This is pretty easy, and Mikael Svenson wrote up a nice guide on doing this using PnP PowerShell.

If you follow his guide, and the official documentation, you can easily get a nice custom theme. However, one annoying and not obvious part is setting the accent color. If you use the generated theme you might end up with something like this:

SoPrettyDefault

For this theme, I used the Theme Generator. By default, you specify the primary color (the big rectangle on the left in the theme) and then all the other colors are variations of it. However, you can click on any of the generated colors to override them. I did this as you can see above by overriding themeSecondary (2nd box in the theme) and themeTertiary (3rd box in the theme):

SoPrettyFabricPalette

But what about that 4th box, the accent color? This wasn’t part of the generator and I couldn’t find it documented anywhere. You also don’t get the nice Customize link to let you set it. Instead, the accent color is set to the same as the primary color. This results in things like that weird square in the hero part being the exact color as your buttons, etc.:

StupidAccentFailure

Turns out setting this isn’t hard, it’s just not obvious. All you do is add an “accent” value to your generated list of colors like so:

@{
"themePrimary" = "#144e3a";
"themeLighterAlt" = "#d8f5eb";
"themeLighter" = "#b4ecd8";
"themeLight" = "#90e2c6";
"themeTertiary" = "#edd249";
"themeSecondary" = "#6b4130";
"themeDarkAlt" = "#30bb8a";
"themeDark" = "#279770";
"themeDarker" = "#1e7355";
"neutralLighterAlt" = "#f8f8f8";
"neutralLighter" = "#f4f4f4";
"neutralLight" = "#eaeaea";
"neutralQuaternaryAlt" = "#dadada";
"neutralQuaternary" = "#d0d0d0";
"neutralTertiaryAlt" = "#c8c8c8";
"neutralTertiary" = "#a6a6a6";
"neutralSecondary" = "#666666";
"neutralPrimaryAlt" = "#3c3c3c";
"neutralPrimary" = "#333333";
"neutralDark" = "#212121";
"black" = "#1c1c1c";
"white" = "#ffffff";
"primaryBackground" = "#ffffff";
"primaryText" = "#333333";
"bodyBackground" = "#ffffff";
"bodyText" = "#333333";
"disabledBackground" = "#f4f4f4";
"disabledText" = "#c8c8c8";
"accent" = "#B81344";
}

Adding that last line results in this:

SoPrettyWithAccent

WithAccent

Looks like there are a couple of other values you can add (and possibly more) such as “neutralSecondaryAlt”, “blackTranslucent40”, and “error”. Just like most of the entries, however, it’s not totally obvious when they’re used.

Now you no longer have an excuse not to set that sweet accent color to the boring shade dictated by your corporate style guide!

The PnP Super Heroes we “Need”

Back in November, I reworked the PnP Hero as an opensource SVG Vector image making several corrections and ensuring the hero looks good at any size. Then earlier this year, Vesa Juvonen announced he was using this design for some stickers (I’ve since gotten hold of one and they are awesome):

PnPHeroStickers

One of the things that became obvious though was that people would like to see more than just a dude. So… here’s my attempt at a lady:

PnPHero-Female-Original

Don’t like it or think something’s off? Good news! You can totally update it and submit a PR over in the PnPHero-SVG repo on Github!

While I don’t think there’s necessarily anything wrong with the PnP Hero we’ve had (but I wouldn’t would I), I think it’s important to be as inclusive as possible to make it clear that PnP is for everyone. After all, Sharing is Caring.

SharePoint PnP has contributors from all over the world of various gender and ethnicity. So, following the great example of emojis everywhere, in addition to female heroes, the PnP heroes now come in original, light, medium-light, medium, medium-dark, and dark skin tones:

MaleHeros

FemaleHeroes

The repository has a master SVG file with all of the layers, but there are also individual SVG files (as well as png files) for each included. These files can be freely used for anything (PnP related or not) with no attribution required.

This isn’t meant to be political commentary in any way, just an attempt to be more inclusive. Let me know what you think and if there is anything you think should be changed/added.

Use Font Awesome icons in Column Formatting

Applies to: Office 365

I was reading through the issue list on the sp-dev-column-formatting repository and came across a question from Marc Anderson about using icons from external sources – specifically Font Awesome.

The good news is this is totally possible! In fact, I’ve just submitted a sample that addresses Marc’s use case of having a color-coded, custom icon display for a Gender column using Font Awesome icons:

screenshot

The bad news is this isn’t nearly as simple as just specifying the iconName attribute like you do with UI Fabric Icons (but it isn’t that hard either).

The basic idea

One of the awesome things about column formatting is the ability to use an inline SVG element as one of the elmType values. Inside you can add a path element and specify the d attribute.

However, one of the not so awesome things about column formatting is that that is currently about as fancy as you can get with SVGs. The biggest hurdle in this case is the lack of a viewbox attribute. So we’ll have to adjust our icon SVG to not rely on the viewbox for proper scaling and then extract the d attribute for use in our format.

It’s really not as scary as that might have sounded.

Once we have the path instructions for our icon(s) we can use them like any other value with conditional operators and more. In fact, we can even dynamically build those paths if we want to get crazy about it (In fact, this is exactly how the Donut wizard in Column Formatter works).

Get the SVG for an icon

Many icon providers will allow you to download the SVG version of an icon. Both Material icons and Font Awesome allow this and there are many more. You can even mix and match since you aren’t bringing in a dependency on the actual fonts, you’re just using the SVG for individual icons.

For this post, we’ll be using Font Awesome. Here’s how to get an SVG for one of their icons:

  1. From the Font Awesome site, find the icon you want to use in your format and click on it
  2. Click the Download SVG button:
    DownloadSVG
  3. If you haven’t paid for a pro license, you’ll be prompted with an attribution notice. Click Agree & Download the SVG and the file will either open in the browser (in which case, right-click and save) or download directly

Unlike traditional images, you won’t actually upload this file anywhere and you won’t be using it in the src tag of an img element. Instead, we’ll be pulling the instructions directly out of the file (which is actually an XML file).

Format & extract path

Unfortunately, Font Awesome icons rely on a viewbox attribute (like they should) and so they won’t scale properly without some manipulation since we can’t specify the viewbox. We’ll use a free, open-source tool to do this called Inkscape:

  1. Open the icon SVG in Inkscape
  2. We’ll adjust the page size to have the path coordinates drawing at a 1:1 scale instead of relying on the viewbox translation. So choose File > Document Properties to open the Document Properties dialog
  3. Under Custom Size, set the Width and Height both to 13px (or whatever size you are wanting, this is just the default size of icons in column formatting). The Viewbox should also have the same width and height:
    SVGDocumentProperties
  4. Close the Document Properties dialog
  5. That tiny square under your icon is the actual document, so let’s scale down our object to fit. Select the icon object.
  6. In the toolbar, click the lock next to the W (width) property to lock the icon’s ratio:
    LockRatio
  7. Set either the W or the H property (whichever is bigger) to 13
  8. Set both X and Y to 0
  9. You’ll probably want to zoom in now
  10. If it is square, skip to step 12. Otherwise, you’ll want to align the icon either horizontally or vertically as needed. You can do this using the Align and Distribute dialog. Choose Object > Align and Distribute
  11. In the Relative To dropdown select Page then click the Center on vertical axis button if your icon is tall (Y>W) or Center on horizontal axis button if your icon is fat (W>Y):
    AlignAndDistribute
  12. Save your SVG
  13. Open the SVG file in a text editor like VS Code
  14. Scroll down to the only path element (near the bottom) and copy everything in the d attribute:
    ExtractPath

Using the path in a format

Instead of a span with an iconName attribute, you’ll use an svg with a path and a d attribute. A quick example should help clear that up.

Here is a simple format that shows an icon along with the current field’s value. A span with an iconName attribute is used (along with some padding and color) for the icon and then another span to show the field’s text (gist here):

IconFormat

Here’s what that looks like using the fly icon from Font Awesome (gist here):

svgIconFormat

Here’s what’s different:

  • The icon span has been replaced with an svg element
  • We have to specify the height and width since SVG’s have a large default size
  • Instead of the color style attribute, we use fill
  • We add a child element of path and set it’s d attribute to a complicated value (pulled from the icon’s SVG file) instead of a simple icon name

So… not as easy, but this opens up tons of options!

Fortunately, conditionally selecting an icon stays relatively simple since column formatting always allows either an operation or a value. So, where you might have used a conditional statement for the iconName attribute, you can just do the same thing for the d attribute.

Here’s what that looks like in the generic-svgicon-format sample:

ConditionalD

The icons shown here and included in the gist code were adapted from Font Awesome which is available under the Creative Commons Attribution 4.0 International license.

What’s new in Column Formatter 1.2?

Applies to: Office 365

Column Formatter 1.2 is now available! Column Formatter is the Easy editor for modern listview Column Formatting. It is a free webpart available from SharePoint PnP that brings the full power of VS Code editing while providing easy to use templates and browsers all within the browser – and now it’s even better!

Quick start

What’s new

Editor properties

Layout options

A height property was added in 1.1, and with 1.2 Column Formatter now supports full-width sections. With these changes you can dramatically increase the size of the editor on your page:

FullCanvasish

Line Numbers

You can optionally enable line numbers in the editor. This is especially helpful when working with longer formats:

PropertyLineNumbers

Indent Guides

The editor has always had indent guides on by default, but now you can disable them if you prefer a “cleaner” code surface:

PropertyIndentGuides

Mini Map

You can optionally enable the Mini Map navigation/preview in the editor. This is especially helpful for quickly scrolling through long formats:

MiniMap

Site column saving/loading

In addition to downloading, copying to the clipboard, saving to a document library, and applying directly to a list field, you can now save your format at the Site Column level. You can even have those changes pushed to all lists that are using your column!

ApplyToSiteColumn

You can, of course, also load site column formats as needed.

Wizards

With v1.2, Column Formatter now has 14 wizards/templates covering every column type:

WizardCoverage

New wizard: Donut

The new Donut wizard for number columns allows you to create dynamic donut or pie charts:

WizardDonut_Display

You can provide a custom range, size, colors, value display, and more.

This wizard is adapted from the number-piechart sample by Aaron Miao.

New wizard: Start Flow

The new Start Flow wizard makes it easy to create an inline button to launch a flow for a selected item:

WizardStartFlow_Options

Just provide the Flow id and then quickly customize the look and feel to make launching flows even easier for users.

This wizard is adapted from the generic-start-flow sample by Yannick Borghmans.

New template: Overdue Task

The new template Overdue Task takes the concept of highlighting a due date when it’s past due and demonstrates how to add an additional condition based on another column. In this case, the due date will only be highlighted if it’s both past due AND the status column isn’t Complete:

WizardOverdueTask

New wizard: Twitter Pic

The new wizard Twitter Pic makes displaying Twitter profile pictures super easy:

WizardTwitterPic_Options

Now it’s even easier to go bug Marc or write a Dear Vesa style tweet!

Localization

Column Formatter is now more accessible than ever!

Thanks to PooLP, Column Formatter is available in French. Magnifique!

French

Also, thanks to Thomas Goelles, we’ve got German as well. Glücksschweine!

German

Everything else

  • Theme options have moved to the property pane to clean up the editor and to ensure preferences are saved as expected.
  • Each wizard has it’s own documentation page.
  • In fact, there’s quite a bit more documentation in general.
  • New wizard controls made for reuse:
    • Standard colors dropdown (UI Fabric colors)
    • Icons dropdown (UI Fabric icons)
    • Spin button with suffix
  • Updated solution to use SPFx 1.4.1 and PnPJS
  • Several minor bugs were murdered
  • The Mini Map wizard was renamed to Tiny Map to avoid confusion with the new editor feature

Conclusion

If you’re interested in contributing, please do! If you find any bugs or have ideas or are lonely or have questions or whatever, please post in the Issues list – it is greatly appreciated!

Let me know what you think, thanks!

Thank you O365 Seattle!

Last week while attending the MVP Summit, I had the honor of presenting at the O365 Seattle meetup as part of their MVP night.

I presented O365 Column Formatting with Column Formatter. It seemed to resonate well and I think more people with take advantage of both O365 Column Formatting and the PnP Column Formatter.

O365SeattlePresentation
Photo by Tom Resing

There were other great presentations by Kevin Crossman and Seb Levert along with a great Q&A with a full panel of MVPs from across the globe.

MVP Panel
Photo by Tom Resing

It was a fantastic event and I was grateful to be a part of it. My only regret is that I was on an early flight out and had to skip SharePint. Thank you to the organizers, MVPs, and all the attendees!

Resources:

Thank you North American Collaboration Summit 2018!

Over the weekend I was able to attend and speak at the North American Collaboration Summit (Sharepointalooza) in Branson, Missouri. It was an extremely well run and attended event. It’s unbelievable to me that attendees were only paying $65 for content and experience that would cost $1500-2000+ elsewhere!

I spoke on Understanding SharePoint Patterns and Practices (PnP). I love this topic because it allows me to show off amazing stuff that always has immediate “Monday” value. People always leave this session with at least one or two things they’ll start using as soon as they get back to work. SharePoint PnP is awesome but it can be difficult to know about everything that is available.

I was able to demo:

  • SharePoint PnP PowerShell
  • Remote Provisioning
  • Site Designs with Remote Provisioning
  • PnPJS
  • Column Formatter

I even demonstrated how to do the simplest (but still very much appreciated) contribution by live fixing documentation!

Thanks to everyone who attended. I got a lot of great questions and once again people were really impressed with what PnP has to offer! Awesome event, awesome sponsors, awesome speakers, and awesome attendees!

Resources