Documentation for all files associated with TF Popup.
Requirements
Place /assets/js/tf-popup.jquery.min.js, /assets/css/tf-popup.css and /assets/img/ajax-loader.gif on your server.
Include the css and js in your page, not forgetting to load in jQuery first:
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.6/jquery.min.js"></script>
<script src="/assets/js/tf-popup.jquery.min.js"></script>
<link href="/assets/css/tf-popup.css" rel="stylesheet" />
NOTE: If you move any of the files around and store them in a different location, you will need to edit the paths in the files.
That's it, you're good to go!
Public Variables
To use the public variables, you need to access the plugin object. This can be found in the data field TFPopup for each element you have applied the plugin to.
| Variable | Example | Description |
|---|---|---|
| version | $('#link').data('TFPopup').version | Returns the current version of the plugin |
| settings |
$('#link').data('TFPopup').settings $('#link').data('TFPopup').settings.content |
Returns the settings object for the popup |
| $element | $('#link').data('TFPopup').$element | Returns the actual element the jQuery object is applied to |
Public Methods
To use the public methods, you need to access the plugin object. This can be found in the data field TFPopup for each element you have applied the plugin to.
This way, you have access to all the settings that apply to that popup.
TFPopup.open()
Open the popup. This will use the default options initially supplied.
$('#link').data('TFPopup').open();
TFPopup.close()
Close the popup
$('#link').data('TFPopup').close();
TFPopup.loadContent(content, overrideAjax = false)
Load content into the popup. Can be a URL if loading in content via AJAX, or a string/jQuery object if injecting from the DOM. If you are loading in via ajax, and want to load something in from the DOM, simply pass true as the second argument. (See the last code example.)
@param string/object content
$('#link').data('TFPopup').loadContent('http://example.com/content');
$('#link').data('TFPopup').loadContent($('#link').attr('title'));
$('#link').data('TFPopup').loadContent($('#content'));
$('#link').data('TFPopup').loadContent($('#content'), true);
TFPopup.center()
Centres the popup
$('#link').data('TFPopup').center();
Form API
The plugin was originally made to accommodate login/mailing list forms easily. Therefore, a simple API was created. Using the API is optional, but it is recommended for ease of use.
When the form is submitted, it is serialized and submitted to the action of the form via AJAX. Here, you can do any validation that you require.
When you return (echo to the screen) the data, you need to supply the following fields:
| Key | Example | Description |
|---|---|---|
| status | 'error' | Status of the validation, either 'error' or 'success' |
| feedback | '<p class="error">Please fill in the missing fields'</p>' | The message to display. If you return a status or 'error', it will be placed at the top of the popup. If you return a status of 'success', it will replace the form. |
| errors (optional) |
{ 'username', 'password' } |
An object of errors with the input ID as the value. This will add the invalid row class to each of the form rows of the input. |
View the examples page to see samples of validation code.
Append Data to URL Dynamically
Sometimes, you'll have multiple links opening essentially the same popup, and you might want individual content passed to each. This is actually quite simple.
Using the data attribute data-tf_append, you can automatically pass across GET data to the popup.
<a href="#" class="link" data-tf_append="var=1">Link</a>
For instance, say you have a row of links, which when clicked showed a certain post on your forums. You could, when looping through the posts to spit out the links, put the post id in the append data.
Then when the popup is loaded, you can access the post id from $_GET['post_id'] or the equivalent in your language.
You can also pass multiple data across like so :
data-tf_popup="var=1&var=2"
To view this in action, check out the last demo on the demos page.
How to Access the Current Popup
When a popup is opened, the link it spawned from has a class applied (and removed upon closing the popup).
This allows you to target the popup at any time using:
var popup = $('.tf_active').data('TFPopup');
This is especially useful if you are dynamically replacing content and need to center the plugin, for instance.
Options
I like to make the plugins/scripts I create as flexible as possible. This does mean I have a habit of over complicating things!
Below are the many options available. Hopefully they are fairly self explanatory.
NOTE: The only required option is the content option.
| Key | Default Value | Description |
|---|---|---|
| content | '' | Content of the popup |
| modal | false | Determines if the popup acts as a modal (i.e. cannot be cloed if clicking off it) |
| popupWidth | null | Width of the popup |
| popupHeight | null | Height of the popup |
| backgroundOpacity | 0.7 | Opacity of the background |
| loader | The loader object that contains all the loader options | |
| ID | 'tf_loader' | CSS ID of the loader div |
| callback | Callback functions, pass a function for each | |
| onOpen | null | Called when the popup is opened |
| onClose | null | Called when the popup is closed |
| onError | null | Called when the popup returns an error on validation |
| onSuccess | null | Called when the popup successfully returns on validation |
| onSubmit | null | Called when a form is submitted in the popup. Return false to prevent the default inbuilt validation. |
| closeButton | Object containing all the close button options | |
| ID | 'tf_close_button' | CSS ID of the close button |
| content | 'Close' | Content for the close button |
| hidden | false | Show or hide the close button |
| hideFlash | false | Show or hide flash once the popup is opened |
| useMarkup | false | Use the default markup, or provide your own in the actual popup content |
| markup | Object that holds the markup options | |
| top | '<div class="popup">' | HTML for the top of the popup |
| bottom | '</div>' | HTML for the bottom of the popup |
| inputRowClass | 'form_row' | CSS class for each form row |
| invalidRowClass | 'invalid_row' | CSS class for the invalid row indicator |
| errorClass | 'error' | CSS Class for each error injected into the page |
| popupID | 'tf_popup_cont' | CSS ID of the popup container |
| backgroundID | 'tf_popup_background' | CSS ID of the popup background |
| activeClass | 'tf_active' | CSS class applied the link that spawned the popup |
| ajaxContent | true | Load in the content via ajax. (As opposed to injecting HTML already on the page.) |
| ajaxSubmit | true | Submit the form via ajax |