Upgrading Mara

Mara has a compartmentalized directory structure, so as to allow easy replacement of individual code sections without having to replace the whole. This makes version upgrades a relatively straightforward task. 

Naturally, before any upgrade job, take a full backup of your website.

Mara is supplied as a zip archive. Expand this into a suitable temporary location.

Important: Do NOT expand the archive into the same location as your existing website.

Rename the codebase directory in your existing site, for example to oldcodebase.

Copy or upload the codebase from the new version.If you test at this stage, you will probably find that the site works.

Now, examine the plugin directories of the new and old versions, and copy over any plugins which you are using, and which need upgrading. If you have customized any plugins, you might want to retain the configuration files and any custom code from these.

In sitecfg, it is not necessary to replace anything specific, but you might want to add to the existing siteini.php any new settings in the latest version. Don't worry about this if the new settings are not needed, since the defaults will apply for any absent values.

You might then need to check your theme php and css files for old and incompatible code, and for slight styling differences. But, these effects are usually quite small.

In some cases you may need to copy the original codebase's .htaccess file into the new codebase section.

If all does not go well, then  renaming oldcodebase back to codebase will in most cases fix that. That really is one of the excellent features of a file-based system - If it breaks, you replace the broken bits and it works again. No domino effect of missing database classes or the like to complicate and confuse matters, just files and files alone.

Earlier versions

The policy is that there might be significant differences between major version numbers, eg 4 to 5. We try to avoid making changes that would break an existing site at anything less than a full version-number change, because we know that can be extremely frustrating. When doing a whole-number upgrade there may be a few things you need to adjust  before your site will work correctly, so the best policy there is to test on a copy of your site first. In particular, from Hyperframe v4 to Mara v5 some of the directory structure has been renamed to be more in-line with standard CMS practices. The should not create any major difficulties provided the webmaster is aware of the changes needed, but could cause issues if they are overlooked.

One of the big advantages of being a portable app is that, provided you have adhered to good practices of using relative URLs for all local links, creating a test version of your site is simply a matter of making a copy of it, and optionally creating a subdomain for the test copy. 

Upgrading CKEditor

New versions of Mara will typically include CKEditor upgrades. However, you might wish to upgrade your copy of CK in-between Mara releases, to take advantage of any new features. This is also a fairly straightforward process.

Download the latest CKEditor from ckeditor.com -If you are not sure which to choose, get the version with all plugins.

On your website, rename codebase/ck to codebase/ckold (or whatever you like)

Create a new ck directory, and place the entire contents of the download in here.

In the new ck, navigate to codebase/ck/plugins.

Copy over the mara plugin in its entirety from the old ck installation. (This is essential as Mara will not run correctly without this plugin)

To retain the special image and link manipulation features of Mara, rename or delete the image and link plugins, and copy the image and link plugins in their entirety, from codebase/ckold/plugins.

That should be all you need to get the new CKEditor running. You will not initially have any toolbar buttons for new features, since these need to be added to the Mara toobar definition in the codebase/ck_config.js file. I'll just repeat that: The configuration file to be modified is in Mara's codebase, not in the one in codebase/ck, which is unused and has no effect. It's done like this so that you can replace your CKEditor without having to worry about any internal config files.

Be careful when modifying ck_config.js, since the syntax is not quite like standard javascript, and locating trivial syntax errors such as a missing comma can be extremely hard without specialist tools. Best to back up your changes progressively as you proceed, then you can roll back to the last good version if an intractable problem arises.