Skip to content

How to Use

Jump to bottom
markserbol edited this page Oct 27, 2014 · 3 revisions
## Getting Started

Include jquery.urlive.css inside the head tag of your html document.

<link href="jquery.urlive.css" rel="stylesheet" />

Include the latest jQuery library together with jquery.urlive.js on your documents <head>.

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script src="jquery.urlive.js"></script>

After files inclusion, call urlive() function on the element with the URL you want to show the snippet preview. And pass the selector of the element that will contain the preview.

$('selector').urlive({ container: '.urlive-container' });

As you've seen on the demo page, you can apply urlive to any element with a URL. If the element is <textarea> or <input> the plugin will extract the URL from its value. If the element is <a> tag the URL for the preview will come from its href attribute. Other elements like <span> or <div>, the URL should be a text inside the element.

## Options

In jQuery Urlive you can pass the following options to customize the preview behavior and functionality.

Option Default Description
container '.urlive-container' selector, element to contain the preview snippet
target '_blank' string, attribute specifies where to display or open the linked resource on click. See <a> target attribute.
imageSize 'auto' string, determine the size of the image. 'auto' by default checks for the image size first, if the image width is greater than its container then it will show it as large else it will set the image to small. Defining 'large' will set the image to fit its container's width and 'small' to render the image as a small thumbnail. See styling below.
render true Boolean, renders the snippet preview. If set to false nothing will be displayed but you can still retrieve the data via the onSuccess callback.
disableClick false Boolean, set true will disable the anchor tag default click behavior.
regexp /((https?:\/\/)?[\w-@]+(\.[a-z]+)+\.?(:\d+)?(\/\S*)?)/i regular expression pattern, set a regexp pattern to be used in retrieving URL in the element. The default regexp doesn't check for all the valid top-level domains because it would generate quite a long match list, but if you're interested in doing so, you can check out 'In search of the perfect URL validation regex'.
yqlSelect '*' string, specify the data scraping select location for YQL query. See Yahoo Query Language (YQL).
## Callbacks

You can define a callback function like this:

$(selector).urlive({
  callbacks: {
    onStart: function() {
      //execute this when urlive AJAX request starts
    }
  }
})

And here is list of callback functions you can define and execute on a given instance.

Callback Definition
onStart: function() {} a callback function that triggers when AJAX data request starts.
onSuccess: function(data) {} a callback function that triggers when AJAX successfully received a response with the data. This callback also returns the data using the first parameter data which is an Object. You can access the values by its properties using a simple dot-notation: onSuccess: function(data) { var image = data.image }
data Object properties:
* description
* image
* sitename
* title
* type
* url
onFail: function() {} a callback function that triggers when AJAX request fails or fails to connect with YQL server.
noData: function() {} a callback function that triggers when AJAX received a response but with an empty data. This so happens when the URL passed has a valid format but is not active/found or no meta data defined.
onLoadEnd: function() {} a callback function that is triggered once the plugin has finished (including the rendering of the image data).
imgError: function() {} a callback function that is triggered when there is an image data but the image URL cannot be found.
## Methods

When you call a method you can either use the element that you've applied the urlive preview or the container of the preview snippet.

Method Usage Definition
Close $(selector).urlive("close", 400); Calling the "close" method will close the existing preview snippet linked to the selector. This hides the preview with some fading effects but does not remove it so you can eventually re-open or show the preview snippet using the "open" method. This method has an optional paramater for the fadeOut duration, and this duration value can be either a string ('fast' or 'slow') or a Number.
Open $(selector).urlive("open", 400); Calling the plugin's "open" method will open the existing preview snippet, linked to the selector, that has been previously hidden using the "close" method. This method also has an optional paramater for the fadeIn duration, and this duration value can be either a string ('fast' or 'slow') or a Number.
Remove $(selector).urlive("remove", 400); Calling the plugin's "remove" method will remove the existing preview snippet linked to the selector. This method also fades out the preview snippet first before removing it from the DOM, so it also has an optional parameter for the fadeOut duration. The duration value can be either a string ('fast' or 'slow') or a Number.
Disable $(selector).urlive("disable") Calling the plugin's "disable" method will prevent the default on click behavior of the preview snippet. A similar function to the plugin's disableClick option that prevents the linked resource of the preview from opening.
Enable $(selector).urlive("enable") Calling the plugin's "enable" method will restore the default on click behavior of the preview snippet. This is intended to revert/remove the previously disabled (using the "disable" method or disableClick option) default click behavior of the preview snippet.
## Styling

You can style the preview snippet using the jquery.urlive.css file which contains the default style. The display orientation primarily depends on the image size, you can set the size orientation with the imageSize option. If the image is large the image will be displayed on top and will occupy the width of the preview snippet. If the image is set to small the image will be displayed on the left side before the text details.

There are also data by default not being displayed, these are the site_name and type. If you want to show these data, you can edit this line and set the display property to block.

.urlive-sitename, .urlive-type {
  display:none;
}

Clone this wiki locally