Version 1.4
Introduction
First of all, hello and welcome to the SuperMarquee library from SuperPlug.in.
We've tried to make the documentation as extensive as possible. If you have any questions after reading it, do let us know, if you've ran into trouble, please have a look at the faq and support section below.
Supported Frameworks
Currently SuperMarquee can be used in the following environments.
Compatibility
The SuperMarquee library has been successfully tested to work with the latest version of Google Chrome, Mozilla Firefox, Microsoft Edge and Apple Safari browsers.
Installation
You can install SuperMarquee with npm and modern builds tools, or get started quickly with just static hosting or a CDN.
Install from npm
To install the SuperMarquee npm module, open a terminal window in your project folder and run:
npm i sp-supermarquee
Alternatively using yarn:
yarn add sp-supermarquee
Import SuperMarquee into your application.
import SuperMarquee from 'sp-supermarquee';
Install from CDN
Pre-bundled scripts including all supported frameworks are available via jsDelivr.
<!-- Example for minified javasctipt version -->
<script src="https://cdn.jsdelivr.net/npm/sp-supermarquee@latest/dist/SuperMarquee.min.js"></script>
Getting started with Javascript
Make sure to import the SuperMarquee library in your project. Refer to Installation.
Create a placeholder in your html file.
<div id="supermarquee"></div>
Initialize the SuperMarquee instance.
const mySuperMarquee = new SuperMarquee(
document.getElementById( "supermarquee" ),
{
"content" : "Hello world!!!"
}
);
Getting started with jQuery
Include the latest jQuery version first and the jQuery version of SuperMarquee.
<script src="https://cdn.jsdelivr.net/npm/jquery@3.4.1/dist/jquery.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/sp-supermarquee@latest/dist/jquery.supermarquee.min.js"></script>
Create a placeholder in your html file.
<div id="supermarquee"></div>
Initialize the SuperMarquee instance.
$( '#supermarquee' ).supermarquee(
{
"content" : "Hello world!!!"
}
);
Getting started with Web Components
Include the latest web component version of SuperMarquee, e.g. via CDN.
<script src="https://cdn.jsdelivr.net/npm/sp-supermarquee@latest/dist/SuperMarqueeWC.min.js"></script>
Add web component tag entitled <super-marquee /> right in your HTML.
<super-marquee type="horizontal"
direction="ltr"
mode="continuous"
content="Hello from the super marquee web component!"
speed="medium"></super-marquee>
Getting started with Angular
To use SuperMarquee in your Angular projects, simply import the web component version of the library into your Angular project and add the CUSTOM_ELEMENTS_SCHEMA. That's it.
Have a look at the following Angular example on StackBlitz.
Getting started with React
Using the web component version of SuperMarquee, please set flags in your tsconfig.json to true, to ensure React works with custom elements. You might also define the JSX namespace so no warnings appear.
Check out the React example on StackBlitz. It contains all information you need.
Getting started with Svelte
Using SuperMarquee with Svelte is a breeze. Simple import the web component version and you are ready to go.
Working Svelte example can be found on StackBlitz.
Getting started with Vue
Import the web component version of SuperMarquee and you are ready to go.
Watch the following compiled Vue.js example on StackBlitz.
Instantiation
You can have multiple SuperMarquee instances on your web page running at the same time. The library handles all of this for you.
To create an instance, there is just one argument required. That is the HTML element. The second argument is option. It is a literal object for additional configurations.
Here is an example of how a SuperMarquee instance is created with explicitly naming the default configuration.
// This is the HTML tag
// <div id="supermarquee"></div>
new SuperMarquee( document.getElementById( "supermarquee" ), {
"license" : "YOUR-LICENSE-KEY",
"type" : "horizontal",
"speed" : "medium"",
"direction" : "ltr",
"mode" : "continuous",
"position" : "custom"",
"pauseonhover" : false,
"autostart" : true,
"easing" : false,
"content" : "SuperMarquee By SuperPlug.in Is Super !!!",
"spacer" : null,
"perspective" : '{"z":"none","originX":50,"originY":50,"rotateX":0,"rotateY":0,"rotateZ":0}'
});
// This is the HTML tag
// <div id="supermarquee"></div>
$( '#supermarquee' ).supermarquee({
"license" : "YOUR-LICENSE-KEY",
"type" : "horizontal",
"speed" : "medium"",
"direction" : "ltr",
"mode" : "continuous",
"position" : "custom"",
"pauseonhover" : false,
"autostart" : true,
"easing" : false,
"content" : "SuperMarquee By SuperPlug.in Is Super !!!",
"spacer" : null,
"perspective" : '{"z":"none","originX":50,"originY":50,"rotateX":0,"rotateY":0,"rotateZ":0}'
});
In addition to the programmatic approach above you can also set the options via data-attributes directly within your HTML code.
Below you see a super scroll instance with default configuration completely described as an HTML element.
<div
id="supermarquee"
data-license="YOUR-LICENSE-KEY"
data-type="horizontal"
data-speed="medium"
data-direction=""
data-mode="continuous"
data-position="custom"
data-pauseonhover="0"
data-autostart="1"
data-easing="0"
data-content="SuperMarquee By SuperPlug.in Is Super !!!"
data-spacer=" "
data-perspective='{"z":"none","originX":50,"originY":50,"rotateX":0,"rotateY":0,"rotateZ":0}'
>/div>
<!-- Simple instantiate this div with no additional configurations in your script-logic -->
Note concerning Web Components
Web Components by its nature are automatically instantiated as soon as they are added to the DOM.
Options
A SuperMarquee instance can be created with the following options.
| Name | Type | Values | Comment |
|---|---|---|---|
license
|
String
|
default: null
|
Your license key. Refer to Pricing. |
type
|
String
|
- "horizontal"
|
Defines the scrolling type. |
speed
|
String | Number
|
- "superslow"
|
You can use the predefined string constants. Alternatively, you can use any numeric value. We recommend using values between 0.0125 (eq. superslow) and 0.2 (eq. superfast). |
direction
|
String
|
- "ltr"
|
"ltr" eq. left-to-right, "rtl" eq. right-to-left, "btt" eq, bottom-to-top, "ttb" eq. top-to-bottom. |
mode
|
String
|
- "continuous"
|
"continuous" mode repeats the scroll content immediately without a gap. |
position
|
String
|
- "custom"
|
Set the scroll content position attribute. |
pauseonhover
|
String | Bool
|
default: false (="0")
|
If enabled, the scroll animation pauses on hover event. |
autostart
|
String | Bool
|
default: true (="1")
|
If enabled, the scroll starts immediately after instantiation. |
easing
|
String | Bool
|
default: false (="0")
|
If enabled, it smoothly eases the scroll speed. Turn this on when change the scrollspeed of a running instance and you want some smoothness. |
content
|
String
|
String
|
The scroll content. Note. If both, content and rssFeedUrl are set, the content is prepended. |
rssFeedUrl
|
String|null
|
default : null ie. no feed
|
Add the title and link of the rss feed items to the scrolltext. |
rssFeedTemplate
|
String|null
|
default : null ie. no feed
|
A template literal for the rss feed items. |
spacer
|
String | null
|
default is: " " if type is horizontal, else "<br/>"
|
Spacer is appended to the content. |
perspective
|
JSON String | null
|
The JSON string contains the following fields:
- "z" : number, perspective in pixel, default: "none"
|
Perspective settings. |
Methods
A SuperMarquee instance provides the following methods.
| Signature | Arguments | Return | Description |
|---|---|---|---|
play()
|
void |
void
|
Plays/resumes a paused scroll instance. |
pause()
|
void |
void
|
Pauses the scroll animation. |
setScrollContent(String content)
|
content: The content of the scroller
|
void
|
Replaces the scroll content of the current instance. |
setScrollSpeed(String|Number speed)
|
speed: The speed of the scroll animation
|
void
|
Sets new speed value. |
setPauseOnHover(String|Bool pauseonhover)
|
pauseonhover: false|"0" means disabled, true|"1" means enabled
|
void
|
Toggles the pauseOnHover flag. |
setPerspective(JSON String perspective)
|
perspective: The perspective settings as serialized JSON string.
|
void
|
Updates the perspective settings. |
destroy()
|
void
|
void
|
Destroys an instance, ie. stops animation, removes all listeners, observers and template codes. |
The example below shows how to call a method including an argument.
// This is the HTML tag
// <div id="supermarquee"></div>
// First create an instance
const mySuperMarquee = new SuperMarquee( document.getElementById( "supermarquee" ) );
// Change the speed value to "superslow"
mySuperMarquee.setScrollSpeed( "superslow" );
// This is the HTML tag
// <div id="supermarquee"></div>
// First create an instance
$( '#supermarquee' ).supermarquee();
// Change the speed value to "superslow"
$( '#supermarquee' ).supermarquee( "setScrollSpeed", "superslow" );
Examples
Some people like to learn by example instead of reading the API documentation. Therefore, we have created several simple examples and use cases of the library.
Please refer to the list below. All examples are fully documented with jQuery- and javascript source code.
F.A.Q.
Below we compiled a list of frequently asked questions.
If you have a problem it might already be answered. So, please have a look here first.
If you question is not ansered in here, please don't hesitate to contact us.
Can I get rid of this watermark console output?
Absolutely. When buy a license you receive a license key. Pass this license key in the constructor settings (refer to Instantiation) and the watermark will not be shown anymore.
When should I instantiate my SuperMarquee instances?
Make sure you instantiate after everything is loaded, ie. in the window onLoad event.
Should I take care about performance when using multiple instances on a page?
No. This is all done by the library itself. The SuperMarquee library is highly optimized, e.g. it only animates a SuperMarquee instance if it is in the viewport of the browser page.
Not all scroll content is shown when using images and videos?
The dimension of the scroller is calculated during instantiation. If you scroll content contains media elements (e.g.
images and videos), please make sure that all media is loaded before instantiate the SuperMarquee element.
We recommend to explicitly set the width/height properties. Have a look at the Mixed Content example as a reference.
Support
We hope this documentation, the examples and the F.A.Q. section help you with most of the questions you might have. However, if you still have any questions feel free to contact us.
Premium support is offered via our official support page. All requests by premium members have of course a higher priority and fast response time.
All non premium users of the library please refer to the github issues section.
For any suggestions and feature requests feel free to drop us a line at
support@superplug.in
Changelog
The history of notable changes.
- Version 2.0 (15-08-2022)
- Core rework for even more performance and flexibility
- Added a visual editor for easier creation and code generation
- Multiple small bug fixes
- Version 1.4 (27-06-2022)
- Added RSS feed support
- Fixed spacer bug for empty spaces
- Version 1.3 (31-03-2022)
- Added Angular, React, Svelte, Vue support
- Fixed visibility bug
- Version 1.2 (30-03-2022)
- Fixed web component bug with setting default configuration
- Changed web component build file name
- Version 1.1 (13-02-2022)
- Added support for Web components
- Added two more showcase demos (on codepen.io)
- Version 1.0 (28-12-2021)
- Initial release