Image Linking

and adjustment

Image upload and linking is an area which has had an extensive overhaul in version 3 of Mara. There are now two image-related buttons, Image (Linking)  and Quick Image Upload. The Image button functions in a broadly similar way to the original, whereas Quick Image Upload is an entirely new  concept. Use whichever you prefer, although Quick Image Upload is more suited to the straightforward placement of a single image on a page, whilst Image is more suited to adjusting the display of an existing linked image, or batch uploading of several images.

This page covers the conventional Image Linking tool. For the Quick Upload tool, see its separate page.

The image dialog, showing the positioning controls.To insert an image hyperlink into a page, click the 'picture' toolbar button. If the image is has already been uploaded and you know its location, you can type this directly into the 'URL' dialog. If not, press the Browse Server button.This takes you to the filesystem browser - a separate window with three sections.The lefthand bar contains list of the site directory-structure.

Click a location to expand its contents.
Click a filename to see a preview in the righthand pane.
Double-click a filename, or press 'Use this image'  to select it.

If the image is on your own computer and needs uploading to the webserver, see the Filesystem Browser instructions. Or, use Quick Image Upload instead.


Once you have selected your image, you will probably want to adjust how it displays in the page. In the new style of dialog, the horiziontal positioning of the image is handled in one step, and covers left, center or rigthhand alignment, along with the choice of the image being in its own space, or allowing the surrounding text to 'flow' around it.

This feature works by adding css classes to the image link tag, rather than using inline styles, since this keeps the amount of markup in the image tag small and concise. The classes themselves are found in system.css and are fairly complex, but for the most part you don't need to understand them, as the feature is designed to 'just work.' All you see in the dialog is a series of classes added to the third tab of the image dialog. (Which you can add manually, by the way, if you prefer.)

The vertical position is determined by the insertion point, and there are no controls in the dialog for this. Instead, you adjust this by dragging and dropping the image in the main editor. Note that when you are using text flow-around it is generally better to place the insertion point at the start of a paragraph, and this should always be on the left of page (for left-to-right languages) even if the image is floated to the right.

A major advantage of this new dialog is that images can be centered directly, without the need of any workarounds like enclosing them in paragraphs. If you have documents with images enclosed in centered paragraphs you will probably want to remove the paras and use the new method, as it works far better.

The new positioning logic may not work as intended if the image still carries 'baggage' from a previous attempt at centering or alignment by some other means. This will mostly arise with imported pages from other systems, or where Mara has been upgraded from an earlier version. In such cases you are best to delete the image link (which does not delete the file itself) and recreate it. Or, if you are confident with such operations, find the image tag in the  page sourcecode and manually remove the html or css junk which is causing the problem.


The supplied stylesheet provides a small space between the image and surrounding text. For most purposes this will be suitable. If you need to adjust the spacing of a particular image, use the hspace and vspace properties. In general it is better not to do this, though, as it leads to images having non-uniform spacing. If you need a different image spacing for the whole site, adjust the stylesheet instead. HSpace has no effect in some image positions.

Note: it is advised that the main toolbar's text alignment buttons should no longer be used on images. No great harm will be done by doing so, but the new dialog is the preferred method and will give better results.


The new dialog provides a simple means of placing an explanatory caption below an image. This caption is effectively attached to the image, and will follow it if you drag and drop the image. To use this, type your caption into the Alternative Text box. Now select the caption position from the options below the preview. The caption is not displayed in page editing mode. To see your caption you must either preview your work, or else exit from editing mode. It's done like this to ensure that the captions are kept separate from the normal page text. You can alter the appearance of captions to use a different text size or font by editing your theme.css file.

Image Dimensions

The Width and Height options in the dialog do not alter the dimensions of the actual image file. They simply zoom (shrink or magnify) the image, as displayed in the webpage. It is probably more convenient to adjust these values using the resize handles on the editor page rather than by typing-in values.

Some points ought to be made here about appropriate and inappropriate use of the width/height controls. Firstly, magnifying (the display of) an image beyond its real size will usually result in a rather poor quality result, so is best avoided. If you have a larger copy, then re-upload instead. Shrinking an image is acceptable up to a point, but shrinking a very oversize image so that it fits the page will result in slow page loading, since the browser then has to download many times the amount of data which is actually required to display the picture, for no good purpose. With fast broadband connections, needlessly large image file sizes are not quite so problematic as they once were, but commonsense still needs to be applied. 

One exception is images containing text or numbers, which should preferably be displayed at their native size.  If such an image needs resizing it should be recreated and re-uploaded. 

Click to Zoom

The onClick item allows you to set a Click-to-Zoom function. This is a mainly useful if you wish to display a detailed image at a reduced size so as to not take up too much document space, but at the same time allow the user to see the full detail when needed. (Ideal for vehicle part images, service manual schematics, etc.) If the user clicks the image, a fullsize version is shown in a popup. (actually it's a layer  rather than a popup to avoid problems with popup-blockers, but the result is much the same) Clicking the popup unzooms the image. Note that zoom should not be used on images which have a hyperlink attached on the Link tab, as the two would then be competing for the click action.

Files and Locations

It is suggested that all images and media content are stored in an img/ folder/directory under the location of the document itself. Doing things this way makes it easier to move files around in the website structure without breaking the links. Thus, if you create a multilevel site, there should be an 'img' directory for each level.

As with local html files, images on the same website should never be linked using a 'http://' prefix. They should preferably be linked relative to the webpage itself. Links to images on other websites must start with an http:// prefix. Note that you should seek permission before making links to the material on other sites, it is considered bad manners to do so without the webmaster's OK.