XF 2.2 Where do we store add-on images and javascript, and how we access them in templates?

[cowgod]

I'm trying to write my first addon and having some difficulties getting started. I need to add some JavaScript files and the add-on has a few images that it will require, as well as the ability to save new images.

According to the documentation, you can add JavaScript tags like this:

<xf:js src="myaddon/vendor/scripts/myjs_file.js" />

So does this mean I have to manually place my files there? Or do I put them in my add-on _data directory and they get copied there? It seems like they should go in the _data directory so that the files can be verified against the hashes.json file, but the documentation doesn't explain how you would copy them over if that's the case.

Same question goes for images. Also, there's no <xf:img> tag? Do I just use regular <img> tags in templates for those then? Is there a variable that I use to get the relative path to my add-on? Or am I just supposed to hard code it to /src/addons/MyAddon/?

Is there a tutorial for getting started with add-ons other than the developer docs?

 

[cowgod]

Okay I found build.json in the documentation, but it doesn't explain why we should place our Javascript in /js instead of our addons directory, or where to put images and how to get the src to them.

 

[Jeremy P]

You can put them in the _files directory of your add-on and use some build.json entries to include them in builds (and minify them in the process):

{
    "additional_files": [
        "js/vendor/addon"
    ],
    "minify": "*"
}

You can reference them in your templates like this so that they get resolved properly during development:

<xf:js addon="Vendor/AddOn" src="vendor/addon/file.js" min="1" />

 

[cowgod]

So let's say I have the following files in my add-on:

_files/js/MyAddon/app.js
_files/js/MyAddon/options.js
_files/img/MyAddon/bg.png

Then my build.json would look like this?

{
    "additional_files": [
        "_files/js/MyAddon/app.js",
        "_files/js/MyAddon/options.js",
        "_files/img/MyAddon/bg.png",
    ],
    "exec": [
        "echo '{title} version {version_string} ({version_id}) has been built successfully!' > 'src/addons/MyAddon/_build/built.txt'"
    ]
}

And then XenForo puts them where? Here?

<xenforo root>/js/MyAddon/app.js
<xenforo root>/js/MyAddon/options.js
<xenforo root>/img/MyAddon/bg.png

 

[Jeremy P]

The additional_files entries are always relative to the _files directory, so it should be omitted from the paths. I'd also recommend using the minify option to ensure your JS gets minified at build time.

But ultimately, yes, they are included in builds relative to the root directory.

The <xf:js> tag can automatically serve JS files from your add-on directory during development, but images are a little tricker as there's no built-in handling for them as it stands. You might be able to use symlinks to work around this, but understandably that can be a bit cumbersome.

 

[cowgod]

images are a little tricker as there's no built-in handling for them as it stands

Thank you for helping me. If there's no built in handling of images, are there any best practices on where they should go?

 

[Jeremy P]

I typically put them somewhere under styles, and use style properties to refer to them so they can be customized if needed.