home | manual | premium service | open source download | forum | contact us

wIMG Manual

Table of Contents:

wIMG

wIMG stands for web <IMG>. wIMG is a free system that can show a picture of any webpage in a variety of sizes and styles. Example

Usage:


http [s] ://wimg.ca/ [options /] [URL to display]

Simply append the URL of the webpage that you want to show after http://wimg.ca/ like in this example:

http://wimg.ca/http://abc.com/

This will work with any URL starting with http:// or https:// that does not contain a pound character (#).

If you use this method with an URL that contains a pound character, the part of the URL that is after the pound character will be ignored (this is because what is after the pound in an URL is not sent to the server by the browser). In order to use display an URL that contains a pound character correcty you must provide the URL url-encoded and mention it in the options. like in this example:

http://wimg.ca/urlencoded_yes/http%3A%2F%2Fwimg.ca%2Fmanual%23usage
or
http://wimg.ca/uc_y/http%3A%2F%2Fwimg.ca%2Fmanual%23usage

click here to use the URL encoder/decoder

wIMG images and every service are available both in regular HTTP or HTTPS (SSL secure connection) for free. So you can use all of our services on your HTTPS webpages without breaking your security.

Options:


option name value description
Quick Sizes size 1,2 or 3 sets the size of the picture. (1=128x96, 2=256x192, 3=512x384)
example:
http://wimg.ca/size_2/http://URL
Will show the picture in a format of 256 pixels wide and 192 pixels high.
Custom Sizes w and h w from 128 to 512, h from 96 to 384 sets the size of the picture to custom dimensions.
example:
http://wimg.ca/w_200_h_201/http://URL
Will show the picture in a format of 200 pixels wide and 201 pixels high.
Keep Aspect Ratio ratio on or off (default: on) If you specify custom dimensions that are not proportional to the dimensions of the original picture (1024x768) this option allows you to decide if you want the picture to be stretched (ratio = off) or displayed in the maximal proportional dimensions possible inside the chosen custom dimensions (ratio = on).
example:
http://wimg.ca/w_200_h_200_ratio_off/http://URL
Will stretch the picture.

http://wimg.ca/w_200_h_200_ratio_on/http://URL
or
http://wimg.ca/w_200_h_200/http://URL
Will preserve the aspect ratio.
Background Color bgcolor from 000000 to FFFFFF (Hexadecimal color number) Sets the color of the background when showing the status in queue of the picture before the image is ready.

Also sets the background color that will fill the rest of the picture in a case where custom dimensions that are not proportional to the size of the original image (1024x768) are used and the aspect ration is kept (ratio = on).
example:
http://wimg.ca/w_200_h_200_bgcolor_000000/http://URL
This picture will be 200 pixels wide by 200 pixels high but the proportion of the orginal picture will be preserved so there will be empty space over and under the screenshot and it will be filled with the color black.
Text Color color from 000000 to FFFFFF (Hexadecimal color number) Sets the color of the text when showing the status in queue of the picture before the image is ready.
example:
http://wimg.ca/bgcolor_000000_color_FFFFFF/http://URL
The text in the picture before it is ready will be white.
URL is url-encoded urlencoded or uc yes (or y) or no (or n) (default: no) Tells the system that the provided URL will be url-encoded (needed to allow the use of a URL containing a pound character "#").

URL encoder/decoder
example:
http://wimg.ca/urlencoded_yes/http%3A%2F%2Fwimg.ca%2Fmanual%23options
The screenshot will display http://wimg.ca/manual#options
Mode mode 0, 1, 2, 3 or js, 4 or iframe. (default: 0) 0: the textual information when the image is queued or in case of error is displayed in image format, the webshot, when available is also dislayed in image format.

1: the textual information when the image is queued or in case of error is displayed in text format, the webshot, when available is displayed in image format.

2: the textual information when the image is queued or in case of error is displayed in text format, the webshot, when available shows debugging text instead of the actual image.

3 or js: information is returned in javascript format for cross domain ajax requests. this mode also has an additional option named "rk" (for return key). the script will add values about the current state of the requested url webshot to an array named "wimg_returned_url_state" with the value that you have set on the "rk" option as key. The possible states are "ready", "queued" and "invalid". It also adds extra textual information about the state to the same key in an array named "wimg_returned_url_state_description".

4 or iframe: the textual information when the image is queued or in case of error, as well as the webshot, when available are displayed as an independant HTML page also called the "Auto-Reloading Iframe Mode". This iframe will reload automatically when the image is still queued until the image is ready. Since the picture will be shown in an independant iframe, you will lose control of the link that is on the image, thats why this mode also enables 2 new options named "link" and "target". Which allow you to change the default link and target on the image. Click here to read more about the Auto-Reloading Iframe Mode and it's options.
example:
http://wimg.ca/mode_1/http://lovesnet.com/?test=89031
The information while the picture is queued or in case of error will be shown in plain text format instead of in an image format. But the webshot will show normally as an image when ready.
Background Images badpic url-encoded picture url (client side) when the request is invalid the image will redirect to the specified image.
badpic? url-encoded picture url (client side) when the request is invalid the image will redirect to the specified image.
badbgpic url-encoded picture url (client side) when the request is invalid, the specified image will display behind the error message.
badbgpic? url-encoded picture path (server side) when the request is invalid, the specified image will display behind the error message.
badbgpictype png, gif or jpg (default: png) hen using a badbgpic of format other than png, the format must be specified.
waitpic url-encoded picture url (client side) when the image is queued the specified image will show instead.
waitpic? url-encoded picture path (server side) when the image is queued the specified image will show instead.
waitpictype png, gif or jpg (default: png) when using a waitpic of format other than png, the format must be specified.
waitbgpic url-encoded picture url (client side) when the image is queued, the specified image will display behind the queue information.
waitbgpic? url-encoded picture path (server side) when the image is queued, the specified image will display behind the queue information.
waitbgpictype png, gif or jpg (default: png) when using a waitbgpic of format other than png, the format must be specified.
outlinecolor from 000000 to FFFFFF (Hexadecimal color number) in addition to chosing the text color, you can also chose a color to outline the text, this can help the text to be more easy to read in front of certain background images.
*when using the wimgOS you must always use the option names that end with a question mark (?). *image paths and URLs must not contain any underscores.
example:
http://wimg.ca/waitbgpic_http%3A%2F%2Fwimg.ca%2Fforest.jpg_waitbgpictype_jpg_color_FFFFFF_outlinecolor_000000/http://lovesnet.com/?test=86925
The image located at http://wimg.ca/forest.jpg will be displayed in the background while the image is still queued and the information text will be white with a black outline.

How does it Work?

When a screenshot for a webpage is requested, the system verifies in its memory to see if it already has a picture for this URL and if yes, displays it.

However, if a screenshot for the requested webpage is not found, the system will add the URL of the webpage to the "queue" and instead of the screenshot of the requested webpage (which is not yet available) it will show a picture that contains textual information about the lenght of the queue and the position of the requested screenshot in the queue.

As soon as a new URL is entered in the queue it will stay there until it has finished its process, the user does not need to keep the image opened for the process to complete.

The wait in the queue could last from a few seconds to several minutes depending on the current state of the queue. When the requested screenshot finishes going through the queue and gets shot the picture is placed in the library and becomes available, next time the image at the exact same url is loaded, it will now display the actual requested completed screenshot.

The screenshot of this webpage will then be kept in the server for a certain amount of months on the server and will also be re-shot every once in a while.

Integration Tools

The wIMG Integration Tools allow you to efficiently integrate wIMG in your website without having to code anything, we did all the coding for you.

Auto-Reloading Iframe Mode

When you try to show a webpage screenshot with wIMG, but there is no picture for that webpage yet, wIMG will need to queue the screenshot to be taken first. So at this point the picture will show information explaining that the image is queued and giving the position in the queue instead of showing the actual screenshot which is not ready yet. And when that happens the picture will actually reload itself as long as the image is still queued, but it will stop reloading when the image is ready, it will also not reload in case of an error. So that is pretty convenient but while this works when the image is loaded alone in the browser, it does not appear to work when the image is embeded on a HTML page with an <IMG> tag. It appears that the src of an <IMG> tag is not able to reload itself!! but the src of an <IFRAME> can. And that is why we have created this simple iframe mode, by setting wIMG to be in iframe mode the resulting screenshot will be a small webpage instead of a PNG image and all you have to do is embed it in your site with an <IFRAME> tag instead of an <IMG> tag. The result will look exactly the same but in case a screenshot on the page is not ready it will not only show *next time you reload the page, but it will instead come up on its own as soon as its ready whitout needing for the user to reload the page. It will also keep showing updated information about the queue process until the image is ready. Example

Usage:


http://wimg.ca/mode_iframe [_ wIMG options /] [URL to display] [? Auto-Reloading Iframe Mode options]

To use the Auto-Reloading Iframe Mode, simply add the options "mode" with "4" or "iframe" for value in your wIMG URL.

Since the result will be an iframe and not an image, it needs to be placed in an <iframe> tag on your page instead of an <img> tag.

Also because an <iframe>does not automatically adapt to the dimensions of its content like an <img> does, it is necessary to specify the desired image dimensions both in the attributes of the <iframe> and in the options of the wIMG URL.

And finally for this to actually look as good as an actual picture, you should also specify a few extra style attributes on your <iframe> tag, such as no scrolling and no borders.

example:
<iframe FRAMEBORDER=0 MARGINWIDTH=0 MARGINHEIGHT=0 SCROLLING=NO WIDTH=256 HEIGHT=192 src="http://wimg.ca/mode_iframe_w_256_h_192/http://mysite.com/"></iframe>

Note that you can also still use all the options of the basic wIMG system.

By default, the image in the iframe will be a link to the actual page shown in the image and it will open in a new window. But you can change or remove the link and change it's target by using the options specific to the Auto-Reloading Iframe Mode

Auto-Reloading Iframe Mode Options:

These Options apply to the Auto-Reloading Iframe Mode. The options of the Auto-Reloading Iframe Mode are specified like normal HTTP GET variables (in the URL after the ? like http://test.com/test?test=1&test=2&test=3). For this reason not only the values of these variables must be URL-encoded but the URL of the main wIMG request must be URL-encoded as well and it must be specified in the wIMG options.

URL encoder/decoder

example:
<iframe FRAMEBORDER=0 MARGINWIDTH=0 MARGINHEIGHT=0 SCROLLING=NO WIDTH=256 HEIGHT=192 src="http://wimg.ca/mode_iframe_w_256_h_192_uc_y/http%3A%2F%2Fmysite.com%2F?link=http%3A%2F%2Fyoursite.com%2F"></iframe>

option name value description
Link URL link none or an URL (default: the URL of the shown picture) (URL must be URL-encoded) The link option allows you to remove the link on the image by setting it's value to "none" or to change the URL of the link by setting it's value to anything else. The URL must be URL-encoded and be an absolute URL. You must also not forget to URL-encode the URL of the main wIMG request and specify it in the wIMG options.

URL encoder/decoder
example:
<iframe FRAMEBORDER=0 MARGINWIDTH=0 MARGINHEIGHT=0 SCROLLING=NO WIDTH=256 HEIGHT=192 src="http://wimg.ca/mode_iframe_w_256_h_192_uc_y/http%3A%2F%2Fmysite.com%2F?link=none"></iframe>
Will show an image for http://mysite.com/ but with no link on it.
<iframe FRAMEBORDER=0 MARGINWIDTH=0 MARGINHEIGHT=0 SCROLLING=NO WIDTH=256 HEIGHT=192 src="http://wimg.ca/mode_iframe_w_256_h_192_uc_y/http%3A%2F%2Fmysite.com%2F?link=http%3A%2F%2Fyoursite.com%2F"></iframe>
Will show an image for http://mysite.com/ in an Auto-Reloading Iframe but the link on the image will go to http://yoursite.com/.
Link Target target blank, parent, top or the name of a frame (default: blank) The target option allows you to change the target from the default which is "_blank" (opens in another page). If you set it to "blank", "parent" or "top" it will set the target to "_blank" "_parent" or "_top" respectively. If you set it to something else it will set it to exactly what you have written. Since the link itself will be on the picture which is inside of the iframe, to make the link open in the same window, you need to set the target to "parent" and the "self" target has been omitted because that would cause the page to open only inside of the wIMG iframe.
example:
<iframe FRAMEBORDER=0 MARGINWIDTH=0 MARGINHEIGHT=0 SCROLLING=NO WIDTH=256 HEIGHT=192 src="http://wimg.ca/mode_iframe_w_256_h_192_uc_y/http%3A%2F%2Fmysite.com%2F?target=parent"></iframe>
Will show an image for http://mysite.com/ in an Auto-Reloading Iframe but the target of the link will open in the same window instead of in another window like the default.
<iframe FRAMEBORDER=0 MARGINWIDTH=0 MARGINHEIGHT=0 SCROLLING=NO WIDTH=256 HEIGHT=192 src="http://wimg.ca/mode_iframe_w_256_h_192_uc_y/http%3A%2F%2Fmysite.com%2F?target=bobijob"></iframe>
Will show an image for http://mysite.com/ in an Auto-Reloading Iframe but the target of the link will open in the frame named "bobijob" instead of in another window like the default.

Link Preview Script

The Link Preview Script is a ready to use javascript code that will automatically add wIMG screenshots opening in a cute cartoonish thought bubble to either all the links on the page or certain links based on the class, target or id. Example

Usage:

<script type="text/javascript">
//options:
var wimg_preview_links_from_following_classes=new Array();
var wimg_preview_links_from_following_targets=new Array();
var wimg_preview_links_from_following_ids=new Array();
var wimg_preview_links_inside_elements_with_following_id=new Array();
var wimg_preview_all_links = 1;
var wimg_default_size = 1;
</script>
<script type="text/javascript" src="http://wimg.ca/linkpreview.js"></script>

You can place this HTML code virtually anywhere in the HTML of a page (It will work either in the <head> or in the <body> tag) and the wIMG Link Previews will automatically appear on certain or all of the links on the page depending on the selected options.

The example above will place a Link Preview on all the links on the page and sets the default size to the smallest. You can change the values of the variables in the "options" section of the code to make a more specific selection of links to be previewed or to change the default size. I believe that the option names are rather self-explanatory, but just to be sure the following paragraph will explain in detail each of these options.

Options:



option name value description
Array of classes to be previewed wimg_preview_links_from_following_classes array elements The links with a class name contained in this array will have a wIMG Link Preview on them.
example:
<script type="text/javascript">
//options:
var wimg_preview_links_from_following_classes=new Array("superlink1","superlink2");
var wimg_preview_links_from_following_targets=new Array();
var wimg_preview_links_from_following_ids=new Array();
var wimg_preview_links_inside_elements_with_following_id=new Array();
var wimg_preview_all_links = 0;
var wimg_default_size = 1;
</script>
<script type="text/javascript" src="http://wimg.ca/linkpreview.js"></script>
Will add link previews to all the links that have classes named superlink1 or superlink2, like <a href="http://URL" class="superlink1">test</a>.

Array of targets to be previewed wimg_preview_links_from_following_targets array elements The links with a target contained in this array will have a wIMG Link Preview on them.
example:
<script type="text/javascript">
//options:
var wimg_preview_links_from_following_classes=new Array();
var wimg_preview_links_from_following_targets=new Array("_blank","frame_number9");
var wimg_preview_links_from_following_ids=new Array();
var wimg_preview_links_inside_elements_with_following_id=new Array();
var wimg_preview_all_links = 0;
var wimg_default_size = 1;
</script>
<script type="text/javascript" src="http://wimg.ca/linkpreview.js"></script>
Will add link previews to all the links that have their target set to "_blank" or "frame_number9", like <a href="http://URL" target="_blank">test</a>.

Array of link id to be previewed wimg_preview_links_from_following_ids array elements The links with an id contained in this array will have a wIMG Link Preview on them.
example:
<script type="text/javascript">
//options:
var wimg_preview_links_from_following_classes=new Array();
var wimg_preview_links_from_following_targets=new Array();
var wimg_preview_links_from_following_ids=new Array("gabbo","gabba");
var wimg_preview_links_inside_elements_with_following_id=new Array();
var wimg_preview_all_links = 0;
var wimg_default_size = 1;
</script>
<script type="text/javascript" src="http://wimg.ca/linkpreview.js"></script>
Will add a link preview on the links that have "gabbo" and "gabba" for id, like <a href="http://URL" id="gabba">test</a>.

Array of elements id to preview links inside wimg_preview_links_inside_elements_with_following_id array elements All the links inside elements with an id contained in this array will have a wIMG Link Preview on them.
example:
<script type="text/javascript">
//options:
var wimg_preview_links_from_following_classes=new Array();
var wimg_preview_links_from_following_targets=new Array();
var wimg_preview_links_from_following_ids=new Array();
var wimg_preview_links_inside_elements_with_following_id=new Array("link_container");
var wimg_preview_all_links = 0;
var wimg_default_size = 1;
</script>
<script type="text/javascript" src="http://wimg.ca/linkpreview.js"></script>
Will add a link preview on all the links inside of the element with "link_container" for id, like <div id="link_container"><a href="http://URL">test</a></div>.

Enable preview on all links wimg_preview_all_links 0 or 1 If you set this variable to 1 there will be a wIMG preview on all links on the page regardless of the values set in the arrays of classes, targets and id to preview. If you set it to 0, only the links matching with your selections in the arrays will have a preview.
example:
<script type="text/javascript">
//options:
var wimg_preview_links_from_following_classes=new Array();
var wimg_preview_links_from_following_targets=new Array();
var wimg_preview_links_from_following_ids=new Array();
var wimg_preview_links_inside_elements_with_following_id=new Array();
var wimg_preview_all_links = 1;
var wimg_default_size = 1;
</script>
<script type="text/javascript" src="http://wimg.ca/linkpreview.js"></script>
Will add a link preview on all the links on the page.

Set default size wimg_default_size 1, 2 or 3 At first, when a new visitor visits your site, the Link Previews will be of the size you chose as the default size with this variable. The visitor will still always be able to change the sizes and a cookie will rememeber his/her selection as well.
1: small
2: medium
3: large
example:
<script type="text/javascript">
//options:
var wimg_preview_links_from_following_classes=new Array();
var wimg_preview_links_from_following_targets=new Array();
var wimg_preview_links_from_following_ids=new Array();
var wimg_preview_links_inside_elements_with_following_id=new Array();
var wimg_preview_all_links = 1;
var wimg_default_size = 2;
</script>
<script type="text/javascript" src="http://wimg.ca/linkpreview.js"></script>
The default size of the Link Previews will be medium.

Delayed execution:

By default the Link Previews script will add previews to links matching the selection on page load. If you want the script to add previews to links matching the selection that appear on the page after the page has finished loading (example, ajax content) you can do it by calling the wimg_putpreviews() function (this function takes no arguments).

Premium Service

The wIMG service is available to all for free, with all of its options and without any restritcion. But for the purpose of making wIMG a viable business model that can survive, wIMG offers two levels of service; The free service and the "Premium service". While the free service displays a wimg.ca signature in the corner of each screenshot, the Premium service does not. Additionally elements queued by the Premium service are given priority in the queue.

Free wIMG
  Premium wIMG

Usage:

The code to use either the free or the Premium service is the same; instead wIMG looks at the domain on which the screenshot is requested to decide if the screenshot should be signed or not. If the domain is registered to the Premium Service, then the signature will be omitted. The signature will also be ommited if the referer is blank. So that means that if your browser has some addon that blanks the referer, the signature would never display for you, even on websites that are not registered to the Premium service. But keep in mind that most browsers do transmit the referer correctly, so most visitors will see the signature on websites which are not registered. Note also that since no change in the code is required, you can start by using the free wIMG service and register to the Premium service later, that will cause the signature to stop appearing without requiring you to change anything on your site and your requests to start being prioritised in the queue. Also if you are using the Premium service and your subscription expires, the worst that can happen is the signature will start showing and you will wait a bit longer in the queue, the screenshots will always continue to work the same.

Click here to sign up your domain for the wIMG Premium Service.