API
2i API allows for an easy integration of 2i - image hosting image hosting functionality into existing web sites, blogs, discussion forums etc. Using the API you may add a virtual button to your form, which makes it easy to invoke file selection dialog and upload the selected image to 2i - image hosting. Upon successful upload the API inserts link with a thumbnail to the form element of choice, thus inserting an image from the user's point of view is a two-click process, as simple as opening a file selection dialog and clicking "OK" as soon as the desired image file is selected.
Deployment example
XHTML example (2i - image hosting api integration code set in bold)
<form method="post" action="">
<input type="text" name="title" value="" />
<textarea name="body" id="target_2i_textarea"></textarea>
<div class="button2i" id="button_2i_div">insert image</div>
<input type="submit" value="submit" />
</form>
<script type="text/javascript" src="http://2i.sk/2i/j/api2i.js"></script>
<script type="text/javascript">
/* <![CDATA[ */
var o2i = new upload2i('button_2i_div', 'target_2i_textarea', 'cs', 'BBCode+thumb');
o2i.cfgBackURLPath = '2i.html';
/* ]]> */
</script>
How to allow the use of 2i - image hosting in your web form
- Add a DIV into your form that will act as the upload "button".
- You can not use the INPUT type=BUTTON tag as it would interfere with your existing form elements.
- Other that that, you may style the "button" div using CSS any way you want.
- Assign an ID to the form element that should receive the returned link+thumbnail code (target_2i_textarea in the above example).
- Add JS code to load API from http://2i.sk/2i/j/api2i.js. You can insert it in the HEAD of your page although this is not recommended in cases where you include the header site-wise (as some browsers fail to cache JS and they will load it again and again, possibly slowing down the pages where you do not use 2i api in your forms). Recommended: load the API at the form, just like the above example shows.
- Add JS code to create an instance of upload2i object, supplying ID of the "button" element,
ID of the target element, desired language for error messages and return code format specifier.
- var o2i = new upload2i('button_2i_div', 'target_2i_textarea', 'en', 'BBCode+thumb')
- This code must follow the HTML FORM code, i.e. cannot be before the form. You may place it at the end of page, e.g.just before </BODY>.
- Create an empty file anywhere at your website (possibly in the document root), e.g. 2i.html, and set cfgBackURLPath to a relative path
of this file.
- o2i.cfgBackURLPath = '2i.html'
- The file is used to relay the ID of newly uploaded image back to your form to play nicely with browsers' cross-domain security policy.
- If you do not set cfgBackURLPath, current URL (i.e. the page containing the web form) will be used. This may affect your application's state (such as page view counts etc.), therefore it is recommended to point this variable to an empty file somewhere at your site.
- In case you point to a non-existing file (i.e. 404 Not Found), the return code will fail to pass correctly into the target form field in Internet Explorer. Therefore make sure you point to an existing file.
- Try and enjoy!
Custom settings
Object reference (upload2i prototype)
object upload2i(string button, string target, string language in (en|cz|cs), string codeType in (id, bbcode, html, xhtml, custom) [, bool crop = false [, bool large = false]])
- button
- ID of DIV element to present the upload button
- target
- ID of TEXTAREA element to receive the link+thumbnail code (appended to the end of this element's value)
- language
- language used for error messages; default charset is UTF-8. As of this version of API, only en, cs and cz values are recognized. If your site uses a different language or charset, you may override default message texts with custom ones, see configuration
- codeType
- return code format
- id - ID only
- BBCode - BBCode style link
- BBCode+thumb - BBCode style link with inline thumbnail image
- HTML - HTML link, opening in a new window
- HTML+thumb - HTML link, opening in a new window, with inline thumbnail
- XHTML - valid XHTML link, opening in a new window via JavaScript (graceful degradation)
- XHTML+thumb - valid XHTML link with thumbnail
- custom -use custom template string cfgCustomCode (see configuration reference below) to format the code
- crop
- crop thumbnail to square
- large
- larger thumbnail (100px vs. 75px)
Configuration
- cfgBackURLPath
- (string) relative path to an empty file (a proxy for returned ID), if not set, current URL will be used. Recommended: set to an empty but existing filename somewhere in your document root.
- cfgCodeType
- (string) target code format, see codeType above
- cfgCrop
- (bool) true = square cropped thumbnail, false = keep original ratio
- cfgCustomCode
- (string) custom template string for the target link and thumbnail; following macros may be used:
- #thumb# - URL of thumbnail image
- #show# - URL of (link to) full image
- #text# - link text (by selected language)
- cfgLarge
- (bool) larger thumbnail, true = 100px, false = 75px
- cfgResetFormAfterUpload
- (bool) reset upload form after each upload; prevents several issues so defaults to true. Set to false only if you plan to fetch return code via JavaScript yourself.
- tBadType
- (string) error message: unknown/unsupported file type uploaded
- tLinkToImage
- (string) text for linking to image if no thumbnail is used, maps to #text# macro in cfgCustomCode
- tUploadError
- (string) error message: image upload failed
Upload in progress indicator, use of CSS
You may style the DIV used as file upload "button" via CSS but you cannot put any form controls inside it (e.g. INPUT type=BUTTON) as these controls would interfere with your main form controls and above all they would prevent the file selection dialog from opening (blocking the click event propagation).
During upload the DIV is assigned a "uploading2i" classname, which is again removed once the upload is over (whether the result is a success or a failure). This serves to indicate "upload in progress" state and allows for custom styling, e.g. as follows.
(X)HTML example (part visible while uploading set in bold)
<div class="button2i" id="button_2i_div">Insert image<span>Uploading...</span></div>
CSS example
.button2i {
border: outset 2px #fff;
font-size: 0.85em;
height: 20px;
text-align: center;
width: 100px;
}
.button2i span {
background: #efe;
display: none;
position: absolute;
bottom: 0;
left: 0;
right: 0;
top: 0;
}
.uploading2i {
background: #f00;
}
.uploading2i span {
display: block;
}