SizeMatters Snippet Tutorial

I could tell you how many hours it takes to develop a MODX extra Transport Package complete with a build script, properties, multiple MODX elements, internationalized strings, error checks, and then fully test it, but you wouldn't believe me. If you use this extra and like it, please consider donating. The suggested donation for this extra is $10.00, but any amount you want to give is fine (really). For a one-time donation of $50.00 you can use all of my non-commercial extras with a clear conscience.


SizeMatters records and displays a record of the viewport width (in both Ems and CSS Pixels) of the visitors to your site. It also shows the font size used.

(Jump to Properties Table.)


Installing SizeMatters

Go to Extras | Installer on the main menu in the MODX Manager and click on the "Download Extras" button. That will take you to the Revolution Repository (AKA Web Transport Facility). Put SizeMatters in the search box and press Enter. Click on the "Download" button, and once the package is downloaded, click on the "Back to Package Manager" button. That should bring you back to your Package Management grid. Click on the "Install" button next to SizeMatters in the grid. The SizeMatters package should now be installed.



To start recording, put this tag anywhere in the body section of a Template or at the end of the Resource Content field of a resource.

To see the results, view the SizeMattersShowGraphs resource. You will get an "Insufficient Data" message until about 100 hits have occurred.



Almost all responsive design gurus recommend against designing for specific devices for lots of good reasons. Out of curiosity, though, if you want to examine which devices are visiting your site, there's a nice list of common devices and their widths Here. You want to look at the right-most two columns: Device Width and Device Height. These are expressed in CSS pixels. Keep in mind that SizeMatters will record the larger of the two values if the device is in landscape mode.


SizeMatters appends a short line of text to the raw data file (core/components/sizematters/logs/log.txt) each time a page with the SizeMatters snippet tag is visited. If you put the tag in a Template used by a lot of pages there is a slight chance of data loss as many processes try to write to the file at the same time. The recommended place for the tag is at the end of the Resource Content field for your home page. If your site doesn't get a lot of visitors, you may choose to put it on more pages, especially at first.

If your site is extremely busy, you may choose to put the tag in the Resource Content field of a page that's not visited very often.


The snippet just injects a small amount of JavaScript code that calls a processor asynchronously, so it shouldn't have much effect on page-load times.

To show the results, just view the SizeMatters Show Graphs resource. You can control which graphs are shown and whether or not they are up-to-date with the properties of the SizeMattersShowGraphs snippet on that page. Change the 1 to a 0 to omit a graph. Leaving out some of the graphs (especially the pixels graph) can make the rendering much faster.



Using the Information

It's generally a bad practice to code for specific devices, but it's nice to know the viewport sizes used by your site's visitors. Keep in mind the fact that if no one is visiting your site with mobile devices, it may be because your site looks terrible on a phone. As you alter your site's design, you can delete the log file, rename the images to save them, and see if the new design is attracting more mobile or tablet users.

Once you have enough data, SizeMatters may help you fine-tune the breakpoints you use in your media queries. Any responsive design strategy involves compromises, and seeing the distribution of viewport widths for your site visitor may help with those decisions.


The Pie Chart

The Pie Chart shows the percentages of users visiting with phone, tablet, laptop, and desktop devices (or whatever you specify). It can be configured by changing the values in the SizeMattersPieConfig chunk, or by creating a new config chunk and specifying it in the &pieConfigChunk property.

The SizeMattersPieConfig chunk looks like this (this example uses Ems as the unit):

Lg. Desktops:100:9999
The unit (em or px) must go on the first line. Each line below must be in the form:

Each line except the first must have exactly two colons, and min and max must be specified in the unit specified in the first line (they can have decimal points).

You can use as many or as few lines as you like (within reason). You might, for example, choose to have just three classes (e.g., phones, tablets, other). If you already have media queries in your CSS, you might want to use those breakpoints.

The default SizeMatterPieConfig chunk uses ems. There is an alternative config chunk called SizeMattersPieConfig2 that uses pixels as the unit. If you want to use it, just include &pieConfigChunk=`SizeMattersPieConfig2 in the SizeMatters snippet tag on the SizeMattersShowGraphs resource.


Because of the way the calculations are made, and browser anomalies, the percentages may differ (sometimes significantly) depending on whether you use ems or pixels as the unit, even if you try to make the breakpoints the same. For example, at extremely small zoom levels (zommed out), a bug in Chrome leads it to report a larger font size (even though the font is actually smaller). This will affect the ems calculation, but not the pixel calculation, making the percentages diverge. The zoom level must be fairly extreme for this to happen, so the odds are that you won't experience it.

Some devices (notably Kindle HDXs) will jack up the font size to compensate for their higher pixel density. SizeMatters tries to correct for this, but the correction is not perfect.


Disabling SizeMatters

You can disable writing to the log.txt file by simply removing the SizeMatters snippet tag anywhere it exists. The JS will not be injected and no SizeMatters code will run when pages load. If you've had enough visitors to create the three data files (about 100 visits), you can still look at the graphs on the SizeMattersShowGraphs page.


Starting Over

If you've just made your site responsive, you may get a lot more mobile visitors. You might want to save the current graphs and start over to get an accurate look at the new visitors. The images are in the assets/components/sizematters/images/ directory and they can be viewed directly by appending that URL to your site URL and adding the filename at the end. If you rename them periodically, you can see how the distribution of visitors changes over time.

After renaming the image files, delete the three data files:,, Then, either edit the log.txt file and save it empty, or delete it and recreate it. Important: Make sure the log.txt file exists when you're finished.

All the data files are in the core/components/sizematters/logs/ directory.


Musings on Responsive Design

How to approach Responsive site design is controversial, but doing a mobile-first design is a common recommendation. I like using Ems and percentages almost exclusively. (Please don't use this site as an example until I get around to making it responsive — I beg you not to look at the current CSS and HTML used at Bob's Guides — it's an embarrassing, shoemaker's-child mess.)

In a mobile-first design, the CSS at the top of your CSS file is for mobile devices. Once you have the site looking good on a phone, you add media queries that modify the site for larger devices. The breakpoints you use will depend on what SizeMatters tells you, and your particular site's requirements. Using Ems and percentages helps with that, as does having a meta viewport tag in the head section of all your Templates. Generally, the only thing I use pixels for is border widths. You can even do drop shadow and border radius values in Ems. The width of divs, imo, is best specified in percentages, and you can set the font-size of the body section as either 1 Em or 100%, so the user's browser defaults will set the font size, and pinching and zooming will work as expected.


Testing Your Responsive Design

If you can't afford a device simulator, and you're doing your development on a localhost install (so you can't use any of the online simulators), a nice substitute is the device simulator in Google Chrome's Dev. Tools. At present, Firefox's simulations just involve shrinking the browser window. Chrome actually responds with the viewport's correct dimensions, and where appropriate, the pixel density. In other words, it responds correctly to media queries in your CSS. Whenever I've used it, and later tested on the actual devices, the simulation has been dead on.

To use Chrome's simulator, go into Dev. Tools (Ctrl-shift-i). At the left side of its menu, you'll see a box with a smaller box inset. Clicking on that will take you to the device simulator. At the top of the screen, there's a report on the current device being simulated and a drop-down menu for switching to another device. At the bottom of the drop-down menu, there's an 'Edit' option that lets you add devices to the list.

At the right side of the device description at the top of the screen, there's an angled icon that will let you switch from portrait to landscape mode. You can control what's displayed in the device description by clicking on the three dots to the far right of the description line. There, you can also capture a screen shot of the device's display.

To exit the simulator, just click again on the simulator icon at the left end of the Dev. Tools menu.


How SizeMatters Works

SizeMatters injects JavaScript into the page that asks the browser about the font size and viewport width (not the device with, because ... who cares). The results may depend on whether you have a meta viewport tag and what's in it. The JS sends a the three data points (px, em, font) to a processor with an asynchronous Ajax call. The JS is vanilla (no Jquery). The processor sanitizes the data and won't process lines containing anything but numbers and commas. The processor then records the data as a single line in a CSV data file: log.txt in the core/components/sizematters/logs/ directory. The log.txt file is human-readable, but should never be edited directly.

The log.txt file would get immense, especially on busy sites. To prevent this, whenever it's over 1000 bytes, (about 100 visitors). The processor locks the file, reads it, updates the three data files (,, — also in the core/components/sizematters/logs/, and empties the log.txt file. Then it unlocks the file.

The contents of the three data files are what the snippet that draws the graphs sends to the graphing software (after a little massaging). This means that updating the log file, updating the data files, and drawing the graphs will never slow down, regardless of how long the program has been running. The three data files are created with PHP's serialize() function, so unlike the log.txt file, they appear as gibberish when viewed. They are read and parsed very quickly. Most of the time it takes for the SizeMattersShowGraphs page to show up is spent inside the graphing software. Looking at the graphs, you can see why.

The graphs are produced with pChart 2.0.


Security Issues

As far as I know, there aren't any. The processor that writes the data will only write very short lines containing only numbers and commas. It converts all input to numbers. The code that processes the data also converts everything to numbers and all it does with the data is send it to the graphing software. There is no database access at any point, and even if someone managed to introduce malicious code, all it would do is confuse the graphing software.

As always, it's strongly recommended that you harden your MODX site so that the core directory is not accessible via URL, either by moving the core above the web root, or adding the appropriate .htaccess file (I prefer the first method).


SizeMatters Properties

Setting Description Default
showEms Show the Ems graph in the results Yes
pieConfigChunk Configuration chunk for Pie Chart SizeMattersPieConfig
showPxs Show the CSS Pixel graph in the results Yes
showFonts Show the Fonts graph in the results Yes
showPie Show the Pie Chart in the results Yes

My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book is available from Amazon.

If you have the book and would like to download the code, you can find it here.

If you have the book and would like to see the updates and corrections page, you can find it here.

MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:

  • Installing MODX
  • How MODX Works
  • Working with MODX resources and Elements
  • Using Git with MODX
  • Using common MODX add-on components like SPForm, Login, getResources, and FormIt
  • MODX security Permissions
  • Customizing the MODX Manager
  • Using Form Customization
  • Creating Transport Packages
  • MODX and xPDO object methods
  • MODX System Events
  • Using PHP with MODX

Go here for more information about the book.

Thank you for visiting

  —  Bob Ray