Your comments

My name is Michael Becker, and I've been chopping Blox apart since 2010. These customization tips are presented without warranty. Break off the core files at your own risk.


Macros

In general, Blox's design team invested heavily into its macros when it designed Flex. That's because under the Zen system, there were a half dozen ways of doing any one thing, such as showing a headline or calling up the last updated time for an asset. This had lead to loads of different means for displaying very simple things in HTML — for example, there was not a consistent set of class names for headlines. (Good luck trying to target custom CSS to that.) It forced the designers to have to bloat their CSS to try to cover all the possible classes and IDs that might have been on elements, further slowing down load times.


Flex, on the other hand, relies on macros, so each component of the templates is adjustable individually. Want to change how the headlines or bylines are displayed? Just change the appropriate macro and you've changed them all, sitewide.


The heavy lifting for the templates is now done by the core components (especially the holy "config" component). That's where all your core macros are going to be stored. The template search field is going to be your saving grace if you're trying to figure out what a certain macro does or which component file it's located in. Use it often.


If you want to override TN templates, just find the macro you want to change, copy it from beginning to end, and past it into a file inside your own site's component. As long as your macro has the exact same name as the core component TN wrote, it will override it.


Here at the Bozeman Daily Chronicle, we have created a slew of files within our site component, to keep custom and overridden macros organized. We have files such as:


  • advertising.utl
  • asset-display.utl
  • template.utl
  • load.utl
  • overrides.utl

We find that the most important thing you can do when overriding core macros is to document them well. Include the date you forked it off the core component, and the location and version number of the core macro.


Also, include the last time you checked your work against the core macro — this part's important. TN updates their stuff often. You don't want part of your site to stop working or to start displaying funny because your version of a core macro is too out of date to work correctly.


Another important thing: Note with inline comments where you make changes inside your versions of the core macros. We mark the beginning and ends of the segments we change or delete. That also makes "core checks" easier, as it will make re-adding your customizations to the latest version of the core files easier.


Templates

Sometimes, you may want to do more customizing than simply changing macros will allow for. Say you're dealing with a YouTube asset and you want to move the description from above the video to below it, or vice versa. This is a time when you might consider changing a template file.


In Blox, the template files are the ones that actually generate the pages that are displayed on your site. They are located under either the "Site Templates" or "Flex" folders on in your template editor (depending on which you are using) and under "Skins."


Underneath the various apps (Editorial, Business, Calendar, etc.) you'll find a skin called "Flex" that contains folders called includes, resources and templates.


  • The resources folder mostly contains CSS and javascript.
  • The templates folder contains the template files, such as inline.pdf.html.utl (which controls how inline pdfs display on the HTML version of pages) or front.html.utl (which controls your homepage's HTML view) or index.html.utl (which controls your section front pages' HTML view). They are all named more or less clearly. Often, these are full of macros and calls to "include" files.
  • The includes folder contains includes, which are basically smaller chunks of the template files. Think of them as a sort of "macro" on a larger scale. They contain whole chunks of pages that can be called in and inserted into templates as needed.

Presently, you can override template files by recreating them in your Global folder, which also contains includes, feeds and templates folders. Just create a new UTL file inside the appropriate folder in your Global folder and name it exactly as the core file is named. If your file is located in a directory within the core folder structure, just recreate that folder structure in your Global folder.


It is good practice to immediately copy the core version of the file you're changing into your newly created file. That way, if you accidentally hit the "publish all packages" or "publish" buttons before you're ready, you won't break your site for the next 30 minutes until you can undo your changes.


What would you want to clone templates for? Well, we have done this in the past to alter the way RSS feeds are displayed or even to create new versions of RSS feeds for certain applications. I have in the past altered the way table assets are displayed to make it possible to use DataTables JS on them with a simple asset custom property setting. Frankly, though, I dipped into customizations at this level MUCH more often under Zen than I have under Flex.


Block Templates

Block templates are the items placed into regions on the page. They actually query the Blox database and show your assets to the readers.


Create new blocks in the Template Editor by Opening up the "Blocks" subfolder of either your "Flex" or "Site Templates" folder (depending on which your site is using). Give your new block a filename and you're good to go with a blank screen awaiting your UTL.


You can also right click on any core block template and choose to duplicate it. This is often a better approach, as it also duplicates the basic custom properties common to TN-created blocks. Plus, it's easier to duplicate and tweak than to write a block entirely from scratch.


Unlike the macros and template files, you never "override" TN block templates. Instead, you create new templates that you can choose to use in the Block Editor instead. So don't worry about breaking anything in the core blocks, as you aren't going to be able to save the changes you make to them anyhow. About the worst that can happen is that you have problems in your block's code that prevent the Block Editor screen from being able to display a preview of the page with your asset on it, forcing you to head back to the Template Editor and do some work to fix it.


I would recommend setting up a test URL on your site with an unorthodox name people in the public won't guess. You can use this to test your creations before making them "public."


General Tips

  • Study the core templates to see how things are done. There's a lot to learn in there.
  • Use the heck out of the template search to track down where macros come from and understand what they do.
  • Don't hit the "publish all packages" button until you're sure you're ready.
  • Preview everything before hitting publish.
  • Make lots of new block templates. Make your own macros.
  • DOCUMENT EVERYTHING with inline comments. EVERYTHING. Dates. What you changed. Why you did it. If you do this well, when you have to ask TN support for help in a bind, they might be able to see some of your twisted logic.

Hit me up if you have questions. I'm always willing to help fellow Bloxers out. becker@dailychronicle.com.

The ability to zoom out on that image editor screen would be golden too. Since we import photos from TCMS, the images are often far larger than the window, making cropping a pain since there is no way to zoom out and see the whole image.

Ditto. The editor should be smart enough to parse the special characters without having to resort to the character codes.

TownNews actually rolled out a comment count for Facebook, so I rolled back my customizations. Your comment dashboard would be at https://developers.facebook.com/tools/comments/YOUR_APP_ID_HERE

Yeah, I switched to using your guys' code after I saw that feature launched.

You know I'm always interested in experimenting with new Blox stuff, Christine.

There aren't setting you can change, per se, but you could customize certain macros to tell Blox to display the date however you'd like.

Push notifications on which platform? Through the browser, you mean?

It tracks engagement rather than just a hollow pageview. The fact that the user has to actually opt to read the rest of the article tells the media outlet that it was engaging beyond the headline and lede and it tells advertisers something about how worthwhile it is to advertise on that site.