Welcome Tour
Site Checklist
Our Story




The upload command is used to upload a file to the server. It involves a number of default parameters and some security considerations. Please follow the instructions below carefully.

Here's a simply upload form:

Select File: [file upload] [submit]
[command upload]

This code creates a simple form with a file upload input field and a submit button. The user selects the file they want, hits upload and BoltWire puts a copy of the file in the files folder of you field.

Config Values

There are two config values that limit how this function is used. These are shown in in site.config, and can be modified--but they cannot be deleted. That is, if no site.config value is found, the command will still use the default values below. This is to prevent accidental deletion of an important security setting.

An individual form can further restrict a default config value but cannot expand it. That is, I could create a special image form that only accepts jpg files, but I cannot create a form that accepts doc files if that is not allowed in site.config. If I need a special form to do that, I must first allow docs in site.config, and then second restrict that file type from all the other forms that do not require it. This is because file uploads can be dangerous. So be careful!

Upload Types
This controls what kind of files can be uploaded. By default, site.config uses "uploadTypes: gif,jpg,jpeg,png,txt,pdf". For a file to be uploaded, it MUST have an extension within this group. To expand the list, edit the site.config value. To limit the list for a specific form, add a parameter like this to the command types='jpg,jpeg' or types=pdf. Upload the wrong file type and the form will abort.

Upload Size
This controls the maximum size of the files a user can upload (in bytes). By default, site.config uses "uploadSize: 100000". This is 100k, which is adequate for most small web graphics--but it is a bit limited. To increase the allowed upload size, edit site.config. To limit the upload size allowed for a specific form, add a parameter like this to the command size='25000'. Upload too large a file and the form will abort.

Suppose you wanted to create a form to upload profile pic's, and you wanted to force users to only upload a jpg of 25k or less. You could create a custom form like this:

Select File: [file upload] [submit]
[command upload types=jpg size=25000]

Optional Parameters

There are a few additional parameters you can use to modify how this form works. These are listed below:

By default, all files names are converted to lower case. This makes it easy to create the correct link to an image or file in your site. Just keep it lower case. Case doesn't matter on windows, but most servers use Linux--and links won't match unless the case matches exactly. You can change the default behavior in site.config by setting changing uploadCase: true. Or you can allow case insensitive uploads in a specific form by setting case=true.

By default, all files keep the same name they are uploaded with, except they are converted to lowercase (normally). You can change that name to something different using the name parameter. The case setting applies to this parameter also, so your new name will be converted to lowercase unless otherewise specified. Also, the type of the new name must match the type of the old name or the form will abort. One exception to this is hardcoded into BoltWire: jpg's can be changed to jpeg's and vice versa.

By default all files are stored in the files folder, and BoltWire always looks here for images and links to files you have uploaded. So normally, you don't have to specify any directories. But suppose you wanted to have a subfolder within files where you kept a specific collection of pdf's. You could set dir=pdf as a parameter in the command to store you file in files/pdf. To link to the file you would have to use a markup like this:

[^somefile.pdf dir=pdf^]

Dir names can only include letters, numbers, hyphens and underscores, and only dirs within the files dir can be created. Also, dirs within dirs are NOT allowed. So you cannot set dir=resources/pdf to put them in files/resources/pdf

An Example

So let's expand our profile pic uploader to give it a name that matches their member id, and stores it in a special member directory in your files folder. We also want to allow them to upload either jpg's or jpeg's, but always save them as a jpg. Here's all you do:

Select File: [file upload] [submit]
[command upload types=jpg,jpeg size=25000 dir=members name={id}.jpg]

This is convenient, because now I can easily refer to a user's profile picture with this code: [^.jpg dir=member^].

If a file doesn't exist, BoltWire will create a link to the upload action for the missing file. But suppose I wanted to display a generic member picture instead. Use this code

[if exists {id}.jpg dir=files/member][^{id}.jpg dir=member^][else]img:user.jpg[if]

This checks to see if the file exists, and if so displays it. (Notice the difference in the two dir parameters). If not, it displays user.jpg from the files folder.

Upload Authorizations

For a file to upload a user must have upload authorizations for the specified page. These settings are controlled by site.auth.upload. The default installation comes with a single entry:

action.upload: @editors,@admins

This means only @editors and @admins can upload files, and only if using page action.upload. Suppose we put our custom profile pic uploader on page action.mypic. We would need to modify site.auth.upload to include the following line:

action.upload: @editors,@admins
action.mypic: @member

Now members can upload small jpgs and jpegs as a profile picture if they are logged in. Editors and admins can upload other, larger kinds of files.