Documentation for flex templates

I believe UTL and the basic methodology for underlying Blox system is pretty much the same (someone from TN may correct me if I'm wrong), most of the new stuff in Flex are the skins, components, block templates, etc. that are made in UTL.

I came across this awhile ago and it helps shed light on their methodology, etc for the new UTL stuff in Flex: http://docs.townnews.com/kbpublisher/Flex-Style-guide_9470.html#BLOX_and_Git

The UTL language is simple, and looks the same for flex as for zen -- reminds me a bit of django templating language actually.

How the various levels of templates, components, modules and the like work together is pretty opaque and seems significantly different from the way it works in Zen (at least the Zen site detailed in those videos).

I'm having to go all the way to original 'construct.utl' call and then trace the component and macro calls all the way down, and that's before I can get any actual work done.

For people starting from Zen and moving to Flex based sites, it's probably intuitive, but for me it's amazingly frustrating.

Django? You'd probably like to talk to @A.L. Flanagan

Anywho, you wouldn't gain much dealing with Zen. There didn't seem to be a set methodology in Zen UTL code.

There are a few "apps" which are presumably in the backend that no one can really see on control on our end. Such as:

- Editorial

- Business (business listings, etc.)

- Classifieds

. . . and so on . .

The UTL pieces usually deal with only one of those apps at a time usually, though not always (e.g. a classified listing can be related to a business, etc.)

Components are like models, they do most of the logic on the UTL end. They also have macros that are HTML/UTL

Skins are like themes or templates in other CMSes. "Option macros" are like hooks in WordPress, sort of

Block templates are like atoms or molecules in Atomic Web design. they just really on the components and base system, within the current "skin"

A lot of UTL dev time is just searching through the docs a little but mostly the code, following the references to find the right piece you need to change or hook into.

Hope that helps!

Hi Aidian.

Speaking as someone who moved from Zen to Flex, it's not any more intuitive for me than it is for you. I find it incredibly frustrating a lot of the time when I'm trying to figure out where things are happening in the code and where I can/should make changes.

A few things that I've learned are:

More often than not, you do need to trace things. Given the way that your site's files templates and macros will override the core Flex templates and macros, you generally need to know whether there is a local one or if you are using the core version.

I find it helps to look at the page source and identity a class or element id that I can use to search the templates to get an idea of where to start. For example, we wanted to make some changes to the calendar on our www.lancasterfarming.com site, so I started by searching the templates for "event-list." That let me find the templates/results.html.utl. That led me to the cal_searchForm macro. Once I got there, I saw that we would need to create our own version of the Calendar app in order to do what we wanted. Granted it wasn't as though I went straight from one file to the next to the next, but it gives you an idea of the path.

Anything that you do will override the core files. The code looks first for a local version of any macro or template. If it doesn't find one, then it looks to the core macros and templates.

Injection points are your friend. http://help.bloxcms.com/knowledge-base/applications/design/templates/flex/misc/article_afcb907e-5d81-11e5-a100-eb5014eb1cde.html, especially if you want to insert something into an article page.

This list http://docs.townnews.com/kbpublisher/33/ from the old documentation site is useful, but sometimes you just have to look through the code to see how to reference a property.

If you have any questions or there's anything I can help you with, I'd be glad to try. I may not get you very far, but I'd give it a shot.

Wanted to take a sec to say thanks to all you guys for sharing your tips and tricks. It's made things a bit more understandable, and it's at least nice to know I'm on the right track and not missing something. Much appreciated!

TownNews: you all have built a great CMS with TERRIBLE documentation -- that's not cool in a commercial product, and I hope you're working on fixing that.

We are working on more developer-specific documentation, but it will generally be along the lines of what Maureen posted - documentation of injection points, CSS overrides, etc.

Most of our sites are working hard to stay "on the upgrade path" and do not want to make deep code changes. Using our specific macros in other code may cause unanticipated changes in the future (if we were to change the macro, for example).

However, specific modules from the templates are available in the help button in the template editor, available in the upper right hand corner.

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.

I'm pretty late to this party, but I wanted to say thanks for helping me wrap my head around this CMS.

I'm just now diving into it, and I was wondering if you have found any new resources for understanding Flex. It seems like much of the documentation is still outdated.

Thanks!