-
Notifications
You must be signed in to change notification settings - Fork 1
Docs
This page contains all the documentation of popup-js, a setup guide and code examples.
A demo can be found here.
The following intructions will provided the knowledge needed to import and implement popup-js into your project.
This component is a jQuery plugin, thus needing it in order to work. You need to include jQuery (min. version: 3.3.1) in your .html head section, before importing popup-js. jQuery can be downloaded from their download's page or imported from a CDN.
Either way, it needs to be included in the page as follows:
...
<head>
<script src="jquery-x.x.x.min.js"></script>
</head>
...Once completed, download or get the URL of the popup-js files and include them in under the jQuery import.
...
<head>
<script src="jquery-x.x.x.min.js"></script>
<link rel="stylesheet" type="text/css" href="popup-js.css" />
<script src="popup-js.js"></script>
</head>
...To check if everything is imported properly, type into the browser console $.fn.popup.defaults. If it returns an object, everything is ready.
To initialise a basic popup, there are two steps.
- Construct the popup by calling the
.popup()function. This can be done in a external script file or in the.html. Expanding the previous code, it would look like so:
...
<script type="text/javascript">
let myPopup = $().popup();
</script>
...In order for the popup to contain actual content, .popup(...) needs to have the following parameters:
...
<script type="text/javascript">
let myPopup = $().popup({ title: "My title", content: "My content"});
</script>
...- To open the popup, we need a trigger. This could be any element or even a method, provided the trigger calls
.openPopup()on the variable created before. Using the previous code and adding a<button>with anonclickattribute, we will implement the trigger:
...
<button onclick="myPopup.openPopup()">Click me</button>
...To make the popup visible by default and non-closeable, the following can be passed as arguments, when calling .popup():
...
<script type="text/javascript">
let myPopup = $().popup({
title: "My title",
content: "My content",
hidden: false,
controls: {
close: false
}
});
</script>
...The final result should look something like this:
...
<button onclick="myPopup.openPopup()">Open popup</button>
<script type="text/javascript">
let myPopup = $().popup({
title: "My title",
content: "My content",
hidden: false,
controls: {
close: false
}
});
</script>
...As shown in the previous section, popup-js offers out-of-the-box customising options, through the parameters of the .popup(...) function. All of those parameters are optional, with their default values available at Default Settings.
The two main parameters you will almost always use are title: "..." and content: "...". They do what you would assume, set the title and content of the popup respectively. They receive string type values, so raw HTML can be sent and will be rendered with no problem. For example:
...
<script type="text/javascript">
let myPopup = $().popup({
title: "<h3>My title</h3>",
content: "<div class='content'>My content is <span style='font-style: italics;'>sooo</span> interesting.</div>"
});
</script>
...Another parameter you may run into occasionally is hidden: .... This parameter is a boolean value (by default true), which tells the popup wether or not it should display by default.
<script type="text/javascript">
let myPopup = $().popup({
hidden: false
});
</script>The controls: { ... } parameter contains definitions for which popup controls should appear, such as the close: ... control (default is true), usually used with hidden: ....
...
<script type="text/javascript">
let myPopup = $().popup({
hidden: false,
controls: {
close: false
}
});
</script>
...Currently, controls: { ... } contains the following items:
controls: {
close: true,
confirm: false,
cancel: false,
submit: false
}The controls have actions assiciated to them. Those are stored in an array of objects. Those objects have the following format:
{
name: string, // The name of the button which will have the associated callback function
callback: function // The callback function
}They are stored and can be passed in the actions: [...] paramter. The defaults for those are the following:
actions: [
{ name: "close", callback: null },
{ name: "confirm", callback: null },
{ name: "cancel", callback: null },
{ name: "submit", callback: null }
]The fixed: ... attribute tells the popup whether it should stay in a fixed location on the page or on the screen. By default it is set to false, the popup staying in the same position on the screen when scrolling.
<script type="text/javascript">
let myPopup = $().popup({
fixed: true
});
</script>header: ... is another paramater that is a boolean value (default is true) which dictates wether or not the popup should have a header. Setting the value to false renders title: ... useless.
<script type="text/javascript">
let myPopup = $().popup({
title: "This won't show up",
header: false
});
</script>The animated: ... paramter is used to toggle on/off all of the popup animations. By default, it is set to true.
<script type="text/javascript">
let myPopup = $().popup({
animated: false
});
</script>popup-js has parameters used to changed the settings of its transitions, divided into two sets: OnOpen and onClose. Each of those sets contains to additional divisions, the first concerning the transition effect (such as fade and direction) and the second the amount (expressed in percentages, i.e. "20%") that the transition will use in its direction. The parameters are enumerated bellow, with a more indepth coverage found in Customise and their default values found in Default Settings.
{
...
transitionOnOpen: {...},
transitionOnOpenAmmount: "...",
transitionOnClose: {...},
transitionOnCloseAmmount: "...",
...
}popup-js has a support for themes, which can be either different stylings or layouts (such as the "modern" and "classic" layouts). Layouts can be changed using the layout: ... parameter. For example, if you wanted the close button to be in the lower part of the popup, the "classic" layout does that for you.
<script type="text/javascript">
let myPopup = $().popup({
layout: "classic"
});
</script>Currently supported layouts are: "modern", "classic".
For different styles, change the default .css classes, as shown in Default Settings.
popup-js has the following default settings which can be accessed and/or modify by using $.fn.popup.defaults:
$.fn.popup.defaults = {
title: "Popup Title",
content: "Popup Content",
header: true,
fixed: false,
layout: "modern",
controls: {
close: true,
confirm: false,
cancel: false,
submit: false
},
actions: [
{ name: "close", callback: null },
{ name: "confirm", callback: null },
{ name: "cancel", callback: null },
{ name: "submit", callback: null }
],
hidden: true,
animated: true,
transitionOnOpen: {
top: true,
right: false,
bottom: false,
left: false,
fade: true
},
transitionOnOpenAmmount: "20%",
transitionOnClose: {
top: true,
right: false,
bottom: false,
left: false,
fade: true
},
transitionOnCloseAmmount: "-100%",
style: {
main: "pu_popup", // Main body styling
header: "pu_popup-header", // Header styling
body: "pu_popup-body", // Body styling
controls: "pu_popup-controls", // Controls (as the parent of controls) styling
control: "pu_popup-ctrl", // Individual control styling
fixed: "pu_popup-fixed", // Styling which "fixes" popup on page
animated: "pu_popup-animated", // Styling for animating popup
hidden: "pu_popup-hidden", // Styling for hiding by default
transitionTop: "pu_popup-top", // Styling for transitioning from top (open/close)
transitionRight: "pu_popup-right", // Styling for transitioning from right (open/close)
transitionBottom: "pu_popup-bottom", // Styling for transitioning from bottom (open/close)
transitionLeft: "pu_popup-left", // Styling for transitioning from left (open/close)
modern: "pu_popup-modern", // Styling for the "modern" layout
classic: "pu_popup-classic" // Styling for the "classic" layout
}
};Basic customisation is dealt with in section Optional Parameters. This covers how to customise css and the default settings of popup-js.
A way to customise the popup is by changing its opening and closing transitions. This can be done by accessing the following parameters:
{
transitionOn*: {...},
transitionOn*Ammount: "..."
}The * is a placeholder for the transition to be changed. It can either be Open or Close. For example, we could change the transitions of popup and have it appear from the left, but only go a quarter of the distance towards the right edge of the page and exit to the right, like so:
<script>
let popup2 = $().popup({
transitionOnOpen: {
left: true
},
transitionOnOpenAmmount: "25%",
transitionOnClose: {
right: true
},
transitionOnCloseAmmount: "-100%",
});
</script>Right now it is not very pretty and we can see it go back to the left after it exits to the right. We can just add a fade to the transitionOnClose: {...} paramter to solve that:
<script>
let popup2 = $().popup({
transitionOnOpen: {
left: true
},
transitionOnOpenAmmount: "25%",
transitionOnClose: {
right: true,
fade: true
},
transitionOnCloseAmmount: "-100%",
});
</script>All of the popup-js classes can be found in $.fn.popup.defaults.styles. Here is the list of classes:
style: {
main: "pu_popup", // Main body styling
header: "pu_popup-header", // Header styling
body: "pu_popup-body", // Body styling
controls: "pu_popup-controls", // Controls (as the parent of controls) styling
control: "pu_popup-ctrl", // Individual control styling
fixed: "pu_popup-fixed", // Styling which "fixes" popup on page
animated: "pu_popup-animated", // Styling for animating popup
hidden: "pu_popup-hidden", // Styling for hiding by default
transitionTop: "pu_popup-top", // Styling for transitioning from top (open/close)
transitionRight: "pu_popup-right", // Styling for transitioning from right (open/close)
transitionBottom: "pu_popup-bottom", // Styling for transitioning from bottom (open/close)
transitionLeft: "pu_popup-left", // Styling for transitioning from left (open/close)
modern: "pu_popup-modern", // Styling for the "modern" layout
classic: "pu_popup-classic" // Styling for the "classic" layout
}If you wanted to change any of those classes and/or default settings, you can do so by accessing the setting and giving it a new value, as such:
$.fn.popup.defaults.hidden = false;
$.fn.popup.defaults.header = false;
$.fn.popup.defaults.styles.body = "my-special-class";