XF 2.2 Style archive import/export, Style asset locations and Asset uploads

Everyday administrative housekeeping often requires direct interaction with your server's file system.

Installing or upgrading a style, switching out logo graphics and other images on your forum you will invariably require a dust-off for your rusty old FTP client and an exciting adventure into arcane directory structures in order to upload them manually, while desperately not trying to overwrite the server's kernel or otherwise accidentally lunch the normally smooth operation of your forum.


We have already acknowledged that these archaic methods will no longer do. XenForo 2.1 removed many barriers in order to allow one-click upgrades and add-on installs/upgrades from archive to be performed directly from your admin control panel in a much more convenient way.

But, we felt there was still more to do and that's what we're talking about today 👇

Defining asset locations for styles

Okay, stick with us here, as this takes some explaining, but it's worth it for the pay-off...

With XenForo 2.2, we're introducing the concept of Asset locations for styles, which can be used to define locations, usually directories, in which assets for your style are stored.

Assets can be anything from a font, a JavaScript file, an image or even a directory containing multiple files.

This is an example of how you might set up one of your styles:


Here we have defined an asset key called logos and pointed that at the styles/my_style directory.

Now this is defined, you are free to use the logos asset location in various places including in templates with the asset('logos') template function and style properties using the %ASSET:logos% placeholder.


These style properties now directly reference the three logo files in the styles/my_style directory that we defined as an asset location. If we ever change that asset location, it will update these three style properties automatically to point at the correct location.

Style asset locations are extremely powerful for child styles, too. You may want to make a derivative of this style which may involve changing some properties, and changing some of the logos to reflect your changes.

By default, child styles inherit style asset locations from their parents:


Much like style properties, you can customize an existing asset location in a style or you can add entirely new locations. Just type into an empty field to add a new one, or click the pencil icon to edit an existing one:


Because the style properties are also inherited from the parent and they are making use of the logos asset, no changes need to be made to the style properties themselves. The logos will now be served from the newly defined asset path.

Export styles to archive

[XenForo Ltd. would like to clarify to readers that styles such as the one illustrated above as designed by our former employee, Chris, are not to be encouraged - Ed]

The designer's drudge

You've designed a class-A XenForo style and, of course, you want to share it with the world. Previously, you had to export the XML file from within your Admin control panel and manually put together a zip archive containing the XML file and any other files you want to include - you know the drill by now. Zzzzz.

What if there was a better way?

Forget the old way. You will now be able to export your style as an archive by selecting that option from the "More options" menu on the style list.



And you might think there's not much more to say about it than that, but this really is where the Style asset locations concept comes into its own. The archive will automatically include the files found within the style's custom or cutomized asset locations.

If you export the style as "Independent" it will also include any assets defined in the parent style as well.
That's nice and all, but what about importing styles...?

Import styles from archive

We couldn't possibly add support for exporting styles as an archive if we weren't also going to add support for importing from those same archives, so any styles that have been exported to an archive can now also be imported from that archive directly.

Previously, styles had to be installed by manually uploading the files needed for the style, and then separately uploading an XML file from the "Import style" system in the XenForo control panel, but with XenForo 2.2 you have the option to upload a zip archive to import the style and all its assets right from the control panel, without having to mess around with FTP (assuming that the style you are importing is available in the new format).

During the import process, we check the list of "Style asset locations". If those locations match files or directories saved in the archive, then they will be moved automatically to an appropriate location.


Unified directory

You may notice that the final location of the assets is actually not exactly as it was when it was defined before we exported the style.

We're able to handle the copying of files installed from a style archive somewhat differently to how we handle copying files from an add-on archive. For style files our only requirement is that the files should be in a web accessible location and a location that we know is writable by your XF installation.

To avoid issues with file permissions, and to ensure the files (such as images) are accessible, the data directory perfectly fits the bill. But what makes this even better is that you're already able to serve files in the data directory from a CDN or offload it to some sort of remote file storage so this potentially enables you to reduce disk usage, while also serving files from a potentially faster, geographically closer location to your visitors.

Upgrades too

Importing a style from an archive can also be used to upgrade a style too. As ever, you would simply import the style and overwrite the existing one.

Asset uploads

While not directly related to importing or exporting styles, this new feature definitely fits into the category of changes that should reduce your need to manually upload files to your forum.

There are a number of areas within your admin control panel that require you to type in a URL and then manually upload a file to that location.

A few examples:
  • Reaction images/sprites
  • Smilie images/sprites
  • Various style property fields, e.g. logos
In these locations (and more besides) you can now keep an eye out for input fields that look like this:


Clicking the "upload" icon allows you to browse the files on your device and once selected the file will be uploaded and populate the path in the input.

You can see a handy example of how it works in this video:

Adding support for asset upload fields in your own add-ons is as simple as adding code similar to the following in your templates:

<xf:assetuploadrow name="image_url" asset="reactions" label="Image URL" />

The asset attribute acts as a key which determines the directory where the uploaded file will be stored:
So what we have here is a complete suite of tools to allow style designers to much more easily package styles for distribution, coupled with an overhauled system to allow those styles to be imported directly from the control panel without having to mess around with manual uploads outside of the XenForo context.

The asset system also brings with it the possibility to manage other style-like assets from within the control panel, such as reaction icons and smilies.

We've got nothing against FTP clients, but we think you're going to be spending a lot less time using them once you are running XenForo 2.2.
Looks like some nice features for admins. I mostly use cPanel file manager rather than FTP these days, but either way, being able to do more of this within Xenforo is welcome.
That is a great feature to add, as it's really only the style side of things that I have had to fire up the FTP client for :)
We've got nothing against FTP clients, but we think you're going to be spending a lot less time using them once you are running XenForo 2.2.
Wooooohooooo! Literally the only time I use FTP now is updating one of @Russ 's styles!

I've been FTPing and updating my sites since 1998 but I STILL feel nervous about jacking stuff up by pressing the wrong button when in the depths of the server.

Happy dance!
I love it all! Thank you XenForo! Seeing as a lot of the assets can be style related, is it possible in the form of a custom style property? It'd be amazing if we could use custom upload fields which export the custom field plus the asset with the style package.
This is nice. Now we can be lazy with style installs, updates & exports as well. Next stop: one click upgrades for styles & addons please. :)
I would guess the asset locations are backwards-compatible. In other words, would the site be "broken" if we don't create and use the new asset locations?
Top Bottom