Composr Tutorial: Releasing a theme

If you've developed your own theme for Composr, and would like to share it with others, we strongly encourage you to do so via the https://composr.app theme gallery. This tutorial explains how to do it.

Why distribute a theme

• The way for users to get a very different look to their website is to either re-theme it themselves, download a theme from the Composr site (or another source), or to buy the services of a professional to do the themeing for them. By releasing a theme, you are helping other Composr users, and giving yourself and your site some publicity for it.
• It's a good way to earn respect in the community – and points.

How to make a theme pack

Making a theme pack using the 'addon' facility

(Click to enlarge)

Details on how to create a theme are outside the scope of this tutorial, and included in the Themeing your site tutorial.

To actually make a theme pack that is ready for release, you just need to export your theme as an addon (as in the screen-shot).

Releasing your theme pack

Once this is done, all you need to do is to upload the addon to our site:

1. Go to our website
2. Go to the Community section (you will be taken to the addons category for the most recent version)
3. Go to the Themes category
4. Use the 'Add a new download' link
5. Fill in the Name/Upload/Author/Description and click the "Add a new download" button
6. You will be invited on what to do next; we like it if users submit images to go with their theme so that's a good next step

Your theme will at first not be validated (i.e. not live for download), but we will go and validate the theme as soon as we can after we receive it. Please be patient.

If your theme has only been tested with certain bundled addons it is a good idea to say which addons in the Description.

Editing your theme pack

If you have improved your theme somehow (e.g. fixed a bug), you'll want to replace the download with a newer version.

You can edit your download via the edit link when viewing it.

How other users get your theme pack

Theme packs are just packaged as normal Composr addons, so are installed from Admin Zone > Structure > Addons.

The user will need to import the addon into their own site, which they can do either by point and click (all https://composr.app's addons are shown for easy import), or via uploading the .tar file after downloading it manually from https://composr.app.

Once a theme is installed, it is available from Admin Zone > Style > Manage themes, and can be set as active.

Automatic upgrades with new versions

Themes are built for a specific version of Composr. Particularly, the CSS files used are based on those from the default theme.

Sometimes a new version of Composr will change the CSS files, perhaps for reasons of styling a new feature, fixing a styling bug, or improving browser compatibility.

In order to allow such CSS changes to (hopefully) come through to the new theme from the altered default theme, upon upgrade, we store the source CSS files of the default theme within your theme as *.editfrom files. These files tell the upgrader what the CSS files were built from so it can compare that against the latest default theme CSS files (i.e. see what has changed in the upgrade), and apply those differences to your CSS files (if there are any in the upgrade).

This upgrade process happens on individual site's that use your theme, and hence why the *.editfrom files are included with what you release.

The process will never be perfect, so some manual fixes may be required. We also may change the process in the future, if/as we find better ways to do this.

In any event, it is good for you to maintain the theme over time if anything has changed. Between Composr patch releases do it by editing your theme pack. Between Composr major releases do it by releasing a new version to the new Composr version's new Themes category.

See also

• Themeing your site
• Theme Lifecycle

Feedback

Have a suggestion? Report an issue on the tracker.