1. Introduction top

Thank you for purchasing Modern News Ticker. I hope that it will serve all of your requirements and meet all of your expectations.

This guide explains everything that there is to know about working with, implementing and customizing the ticker.

If you need further assistance that this guide cannot help you with or if you have any questions, please contact me at [email hidden in preview].

If you find this project useful, it would be helpful if you could give it a rating on CodeCanyon.

You can view other projects in my portfolio, in case there is something else you may find valuable.

You can also Follow me on CodeCanyon so that when I launch new projects, you can see them on the front page.

2. About the ticker top

Modern News Ticker is a powerful, flexible, fast, easy to use and customize news ticker. It offers a varied number of features while still being lightweight and very easy to work with:

  • It comes with 15 different themes to choose from.
  • It has 4 different effects: scroll, fade, type and slide.
  • It has 4 different layouts that include news items, front label and control buttons.
  • The corners can be set to either round or square.
  • It can load RSS, JSON and Twitter feeds.
  • The feeds can be set to automatically refresh.
  • It has 21 settings that control the effects, the feeds and other behaviors.
  • It has 3 methods that control the autoplay and the feed refresh.
  • It is responsive.
  • It comes with a detailed guide.

3. The project files top

The project contains the following files:

  • Main folder: Contains the main files of the ticker, the only files that you need to work with when implementing it. Here you can find example implementations of the ticker as well as all of the assets files that the ticker is using.
    • HTML files: Contain example implementations of the ticker with different configurations. Open any example file in a text editor and you can see the source code together with basic instructions.
    • modern-ticker folder: Contains all of the assets files used by the ticker such as the JavaScript files, the main CSS files, the PHP files and the themes files.
    • load-files folder: Contains RSS and JSON example feed files.
    • preview-files folder: Contains only files used in creating the example files and are not required by the ticker.
  • Guide folder: Contains the user guide with complete information and instructions about the use and functionality of the ticker.
  • Sources folder: Contains the sources of different files used in the ticker that are useful for modifying and developing it.
    • js folder: Contains the JS source file of the ticker plugin.
    • themes folder: Contains all of the sources of the images used in the themes.

4. How to implement the ticker top

When implementing the ticker, the only files that you need to work with are the files located in the Main folder. Here you can find the main ticker folder, modern-ticker, as well as example HTML implementations of the 4 effects, 4 layouts and 3 feeds. To view an example, open the HTML file in the browser and to view the source code, open the file in a text editor.

At the top you will notice that the code contains basic instructions. These are for users that are not following this guide file and only prefer quick instructions. Since you are following this guide file, you can disregard the quick instructions at the top.

Implementing the ticker in your project is easy and and everything that you need to do is:

First step

If you have completed all of the above steps, the ticker should be implemented and functioning. If you encounter any problems, verify that you have properly completed all of the steps.

If you have any questions that this guide does not answer, please contact me at [email hidden in preview].

4.1. The ticker folder top

The ticker folder, modern-ticker, contains all of the files that the ticker is loading and using. You can find it in the Main global folder of the project.

Copy the modern-ticker folder into your project, in the same location as the HTML file in which you wish to place the ticker code.

Note that in the themes folder only the used theme is required, the files of the other themes can be removed. Which theme is used is controlled by the assets code that we will discuss a little later.

Read below to know more about this folder or go to Next step

Explaining the files

The ticker folder contains the following files:

  • css folder: Contains the main css file, modern-ticker.css.
  • js folder: Contains the jQuery library file and the ticker plugin file, jquery.modern-ticker.min.js, in minified form. The unminified version can be found in the Sources/js folder of the project files.
  • themes folder: Contains the files of all the themes.

4.2. The ticker code top

In the Main folder you can find example HTML implementations of the 4 effects, 4 layouts and 3 feeds. To view an example, open the HTML file in the browser and to view the source code, open the file in a text editor.

To implement the code of the ticker in your HTML file, you need to:

All of the code mentioned above is properly delimited by comments in the example files.

First step

4.2.1. The assets code top

The assets code specifies files that are needed by the ticker and that should be loaded by the page. You can find the assets code in the <head> of the file, delimited by comments:

<!-- Start ticker assets code -->
<link href="modern-ticker/css/modern-ticker.css" type="text/css" rel="stylesheet">
...
<!-- End ticker assets code -->

Include this code and customize it, if needed, in the <head> of your HTML file.

Note that if you already have jQuery on your page, do not add it a second time. But make sure that your jQuery is added before the ticker assets code.

Read below to know more about this code and how to set the width or go to Next step

Explaining the code

To understand this code, let's take a look at each line and what files they specify:

<link href="modern-ticker/css/modern-ticker.css" type="text/css" rel="stylesheet">

Specifies the main CSS file of the ticker.

<link href="modern-ticker/themes/theme1.css" type="text/css" rel="stylesheet">

Specifies the current theme CSS file. In order to change the theme, the file referenced here should be changed. For more information see the Change the theme section below.

<script src="modern-ticker/js/jquery-3.2.1.min.js" type="text/javascript"></script>

Specifies the jQuery library. If you already have the library included on the page, do not add it a second time. But make sure that your jQuery is added before the ticker assets code.

<-- <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script> -->

This line is commented out and it is an alternative way of loading jQuery, from Google Hosted Libraries.

The reason why you would want this is because the loading time would be faster for the user if he were to load the library from a Google server rather than from your own site. Or, if the user visited a site using the same practice, he might already have jQuery in his browser cache.

I have added this as a useful option for people who want it, but I have not made it the default loading way as it always requires an Internet connection to preview the ticker. But, when deploying it on the web, it is not a bad idea to use this faster loading alternative.

If you use this option to load jQuery, by removing the comments, remember to delete the above line as not to load it two times.

<script src="modern-ticker/js/jquery.modern-ticker.min.js" type="text/javascript"></script>

Specifies the ticker plugin, in minified form. The unminified version can be found in the Sources/js folder of the project files.

Set the width

The ticker width is controlled from the main CSS file that you can find at modern-ticker/css/modern-ticker.css. Open this file in a text editor.

The width settings are at the top:

.modern-ticker {
	width: 100%;
	min-width: 300px;
	max-width: 1000px;
	...
}

Change the theme

The ticker offers 15 different themes that you can choose from. You can customize these or using them as examples, you can create new themes.

The used theme is specified by the following line of the assets code that you can find in the <head> of the file, which specifies which theme file to load:

<link href="modern-ticker/themes/theme1.css" type="text/css" rel="stylesheet">

To change the theme, all that is needed is to change the file specified in this code to the file of another theme:

  • modern-ticker/themes/theme1.css
  • modern-ticker/themes/theme2.css
  • And so on...

The files of the themes are located in the modern-ticker/themes folder. Only the files of the used theme are necessary and if you are only using a single theme, you can delete the files of the other unused themes from your project folder.

4.2.2. The markup code top

The markup code specifies the content displayed by the ticker such as the news items and the elements of the lauout. You can find the markup code in the <body> of the file, delimited by comments:

<!-- Start ticker markup code -->
<div class="modern-ticker">
	...
</div>
<!-- End ticker markup code -->

Include and customize, as needed, the markup code, in the <body> of your HTML file.

Read below to know more about this code, how to customize it and the available layouts or go to Next step

Explaining the code

Let's take a look at the structure of the code and how to customize it.

The whole HTML code is inside an element with the class modern-ticker:

<div class="modern-ticker">
	...
</div>

Inside this container there is the body:

<div class="mt-body">
    ...
</div>

And the body contains 3 components:

The label:

<div class="mt-label">NEWS:</div>

The label component displays a text on the left side as an indicator of the content of the ticker.

The news:

<div class="mt-news">
    <ul>
        <li><a href="#" target="_self">News 1 news 1 ...</a></li>
        ...
    </ul>
</div>

The news component contains the list of messages displayed by the ticker. Each <li> inside the <ul> is a message item. To add or remove a message item, simply add or remove an <li> element. The message text is specified in the <a> element and the link that is opened when the message is clicked is specified in the href attribute.

If you do not wish to have any link be opened when clicking, simply remove the href and target attributes from the <a> element and leave it blank, as so:

<a>News 1 news 1 ...</a>

And the controls:

<div class="mt-controls">
    <div class="mt-prev"></div>
    <div class="mt-play"></div>
    <div class="mt-next"></div>
</div>

The controls are a set of buttons that can show next and show previous messages and play and pause the ticker.

By using these components inside the body, we can create the 4 different layouts. To add a component, add its HTML code, to remove a component, remove its HTML code. The ticker comes with 4 example files showing each layout implemented.

Layout 1: Label + News + Controls

<div class="mt-label">NEWS:</div>
<div class="mt-news">
    <ul>
        <li><a href="#" target="_self">News 1 news 1 ...</a></li>
        ...
    </ul>
</div>
<div class="mt-controls">
    <div class="mt-prev"></div>
    <div class="mt-play"></div>
    <div class="mt-next"></div>
</div>

An implementation of layout 1 is exemplified in the layout-1.html file.

Layout 2: Label + News

<div class="mt-label">NEWS:</div>
<div class="mt-news">
    <ul>
        <li><a href="#" target="_self">News 1 news 1 ...</a></li>
        ...
    </ul>
</div>

An implementation of layout 2 is exemplified in the layout-2.html file.

Layout 3: News + Controls

<div class="mt-news">
    <ul>
        <li><a href="#" target="_self">News 1 news 1 ...</a></li>
        ...
    </ul>
</div>
<div class="mt-controls">
    <div class="mt-prev"></div>
    <div class="mt-play"></div>
    <div class="mt-next"></div>
</div>

An implementation of layout 3 is exemplified in the layout-3.html file.

Layout 4: News

<div class="mt-news">
    <ul>
        <li><a href="#" target="_self">News 1 news 1 ...</a></li>
        ...
    </ul>
</div>

An implementation of layout 4 is exemplified in the layout-4.html file.

Set the font

By default, the ticker uses the font from the page. If you want it to use it's own font, simply add the mt-font class to the main div element:

<div class="modern-ticker mt-font">
	...
</div>

Change the corners

By default, the ticker has square corners. To have round corners, simply add the mt-round class to the main div element:

<div class="modern-ticker mt-round">
	...
</div>

All of the example files included already have this class added.

4.2.3. The initialization code top

The initialization code builds and customizes the ticker based on the settings supplied. You can find the initialization code at the end of the <body> in the file, delimited by comments:

<!-- Start ticker initialization code -->
<script type="text/javascript">
	jQuery(document).ready(function() {

		jQuery(".modern-ticker").modernTicker({
			...
		});
		
	});
</script>
<!-- End ticker initialization code -->

Include and customize, as needed, the initialization code typically at the end of the <body> of your HTML file.

Read below to know more about this code, the different configurations and the available settings or Finished!

Explaining the code

Let's take a look at what the code is and how to customize it.

After the page was loaded, the modernTicker method is called to which the settings are passed:

jQuery(".modern-ticker").modernTicker({
	effect: "scroll",
	...
});

All settings are separated between them by a comma (,).

The settings control the effect, the autoplay as well as loading data from a feed such as RSS, JSON or Twitter. Let's take a look below at the examples of different configurations. You can find more information about each setting in the settings table.

Scroll effect:

jQuery(".modern-ticker").modernTicker({
    effect: "scroll",
    scrollType: "continuous",
    scrollStart: "inside",
    scrollInterval: 20,
    transitionTime: 500,
    ...
});

An implementation of the scroll effect is exemplified in the effect-1.html file. For complete information about the settings used see the settings table below.

Fade effect:

jQuery(".modern-ticker").modernTicker({
    effect: "fade",
    displayTime: 4000,
    transitionTime: 300,
    ...
});

An implementation of the fade effect is exemplified in the effect-2.html file. For complete information about the settings used see the settings table below.

Type effect:

 jQuery(".modern-ticker").modernTicker({
    effect: "type",
    typeInterval: 10,
    displayTime: 4000,
    transitionTime: 300,
    ...
});

An implementation of the type effect is exemplified in the effect-3.html file. For complete information about the settings used see the settings table below.

Slide effect:

jQuery(".modern-ticker").modernTicker({
    effect: "slide",
    slideDistance: 100,
    displayTime: 4000,
    transitionTime: 350,
    ...
});

An implementation of the slide effect is exemplified in the effect-4.html file. For complete information about the settings used see the settings table below.

General settings:

jQuery(".modern-ticker").modernTicker({
    ...
    linksEnabled: true,
    pauseOnHover: true,
    autoplay: true
});

These settings relate to general things that are available for every effect.

In order to load data from an RSS, JSON or Twitter feed, along the effect and general settings, you need to supply the feed settings. The news <ul> element in the markup code can either start empty or with existing data.

RSS feed:

jQuery(".modern-ticker").modernTicker({
    ...
    feedType: "rss",
    feedUrl: "load-files/feed.rss",
    loadType: "direct",
    feedCount: 5,
    linkTarget: "_blank",
    refresh: "10:00"
});

This feed displays the <title> of the RSS posts and when a message is clicked the <link> of the post is opened.

When loading a file, be sure to see the 4.2.4. Loading an RSS file section to understand better how the ticker works with loading.

An implementation of loading data from an RSS feed is exemplified in the load-rss.html file. For complete information about the settings used see the settings table below.

JSON feed:

jQuery(".modern-ticker").modernTicker({
    ...
    feedType: "json",
    feedUrl: "load-files/feed.json",
    feedCount: 5,
    linkTarget: "_blank",
    refresh: "10:00"
});

This feed can be used to load the news data from a JSON file.

Look over the 4.2.5. JSON feed file format section to see what the structure of the supplied JSON file should be.

An implementation of loading data from a JSON feed is exemplified in the load-json.html file. For complete information about the settings used see the settings table below.

Twitter feed:

jQuery(".modern-ticker").modernTicker({
    ...
    feedType: "twitter",
    twitterName: "twipsum",
    feedCount: 5,
    linkTarget: "_blank",
    refresh: "10:00"
});

This feed displays the Twitter messages and when a message is clicked, the original post is opened on the Twitter website.

An implementation of loading data from a Twitter feed is exemplified in the load-twitter.html file. For complete information about the settings used see the settings table below.

With the 1.1 update of the Twitter API, information can no longer be accessed anonymously and you need to setup an authentication process for your ticker in order for it to be able to access information through the Twitter API. Everything that you need to do is explained in the 4.2.6. Setup Twitter authentication section.

Since the Twitter feed uses a PHP file, it won't work when testing the HTML file on your computer. You need to upload the ticker online where it has access to a server to process the PHP file and retrieve the data from Twitter.

Settings

The settings are options that you can pass to the ticker when initializing it that affect the way that the ticker functions.

The available settings are listed below:

Setting Default value Description
effect "scroll" The animation effect of the ticker out of the 4 available effects: "scroll", "fade", "type" and "slide".
scrollType "continuous" The type of the scroll effect, either "continuous" or "discontinuous". If continuous, the news will scroll all the time with no interruption. If discontinuous, once the list of news finishes, there will be a space showing the end and then the news will start scrolling again.
scrollStart "inside" The initial position from where the news to start scrolling, either "inside" or "outside". If inside, the news will be visible from the beginning and will start scrolling, if outside, the news will not be visible from the beginning and will come into view by scrolling.
scrollInterval 20 The interval at which a scroll movement occurs (in ms), basically the speed of the scroll. Applicable only for the scroll effect.
typeInterval 10 The interval between displaying each letter (in ms). Applicable only for the type effect.
slideDistance 100 The distance that the message is sliding when appearing (in px). Applicable only for the slide effect.
displayTime 4000 The time that a message is displayed, when autoplay is running (in ms). Applicable only for the fade, type and slide effects.
transitionTime 300 The animation time of showing the next and previous messages when the next/prev buttons are pressed (in ms).
linksEnabled true

Whether or not news items have links that open whey they are clicked.

This controls both news that are added manually and news that are loaded.

pauseOnHover true Whether or not the ticker pauses the autoplay when hovering with mouse over the news.
autoplay true Whether or not the ticker should start playing automatically.
feedType - When loading data from an external feed, specifying the type of the feed. It can be either "rss" (or "rss-atom") to load data from an RSS feed, "json" to load the data from a JSON feed or "twitter" to load data from a Twitter feed.
feedUrl - The url from which the RSS or JSON file to be loaded. Applicable only the rss and json feed types.
loadType "direct" There are 2 types of loading functions available, "direct" and "process". For more information, see the 4.2.4. Loading an RSS file section.
loadProcess "YQL" There are 3 options that the ticker can use to process the loading of RSS files from other domains: "YQL" (developer.yahoo.com/yql), "rss2json" (rss2json.com) and "self" (load-rss.php file). For more information, see the 4.2.4. Loading an RSS file section.
forceNoCache false When loading a feed file, it forces to bypass loading a cached version of the file by appending a random number parameter at the end of the url.
twitterName - The name of the Twitter account from which the feed to be loaded. Applicable only for the twitter feed type.
feedCount 5

Specifies the number of news items to be displayed.

For the RSS and JSON feeds, specifies how many items to be displayed from the total that are available. To load all available items, set to 0. If there are fewer items than the number specified, only the available items will be loaded. Thus, if the feed file has a variable number of items, this setting can be used to load a variable number of news up to the specified limit.

For the Twitter feed, specifies how many items to load and display. If set to 0, the Twitter API returns by default 20 items.

linkTarget "_blank"

The target page where the links should be opened, either "_blank" to open the the links in a new page or "_self" to open the links in the current page.

This is available for loaded data such as RSS, Twitter and JSON feeds. For static data, the target can be set directly in the HTML code.

refresh "10:00"

When displaying data from a feed, wether or not to automatically reload the data at an interval of time.

This can be false to disable it or a value specifying the time interval at which the refresh to occur. The time can either be a number of seconds such as 300, to specify 5 minutes, or a string with a time format, such as "5:00" for 5 minutes, "10:30" for 10 minutes and 30 seconds and so on, having the format "hh:mm:ss".

rssLoadFile "modern-ticker/php/load-rss.php" The url to the file that processes the RSS loading request and returns the data. Applicable when feedType: "rss", loadType: "process" and loadProcess: "self".
jsonLoadFile "modern-ticker/php/load-json.php" The url to the file that processes the JSON loading request and returns the data. Applicable when feedType: "json", loadType: "process" and loadProcess: "self".
twitterLoadFile "modern-ticker/php/load-twitter.php" The url to the file that processes the Twitter loading request and returns the data. Applicable when feedType: "twitter". The default file loads and uses the TwitterAPIExchange.php file located in the same folder.

Methods

Methods are functions belonging to the ticker that you can call through code.

Calling a method is similar to the initialization code except that the name of the method is passed when calling the ticker plugin:

jQuery(".modern-ticker").modernTicker("play");

The available methods are listed below:

Method Parameters Description
play - Starts the autoplay.
pause - Stops the autoplay.
refresh - When displaying data from a feed, reloads the data.

4.2.4. Loading an RSS file top

When it comes to loading files, browsers implement certain restrictions to the files that you can load, for security purposes.

By default, files can be loaded from the same domain as where the ticker is, but not from another domain. This limitation can be overcome in 2 ways, either by simply using the "process" load type that the ticker comes with implemented or by explicitly giving loading access through "Access-Control-Allow-Origin".

Let's take a look at each type of loading and learn more about them. We will be working with the settings of the initialization code to control the loading.

Loading from the same domain

If you want to load a file from the same domain, it is pretty easy and straight forward. Browsers allow loading from a location on the same domain, so there is no problem with access.

For example, let's say that you have a site called http://mysite.com. The whole site is a domain. You upload the ticker to mysite.com/ticker, upload the RSS file to mysite.com/ticker/rss/example.rss, and want to load the RSS into the ticker.

In the settings, the feedUrl will be simple, relative to the ticker, "rss/example.rss". It can be any location, as long as it is on the same domain.

And the loadType will be "direct". This is the default load function and it means that the ticker will simply try to load the file from the url provided.

The initialization code can look like this:

jQuery(".modern-ticker").modernTicker({
    ...
    feedType: "rss",
    feedUrl: "rss/example.rss",
    loadType: "direct",
    ...
});

You can upload both the ticker files and the RSS file to your domain and the ticker will load the RSS file and display the data.

Notice that some browsers may restrict loading files from your computer so, when testing, make sure that you upload the files online and make the test there.

Loading from another domain by using the "process" load type

If you want to load a file from another domain than the one the ticker is on, it is not so straight forward because browsers implement restrictions to loading files from a different domain.

For example, you have http://mysite.com that is your domain and there is another domain called http://othersite.com. You upload the ticker to mysite.com/ticker, the RSS is on othersite.com/rss/example.rss, and you want the ticker to load the RSS file.

There are 2 ways of doing this. The simplest is just to use the "process" load type that the ticker comes with implemented. What this does to overcome the loading restriction is it uses a service to process and load the file through. The ticker comes with 2 available processing services, "YQL" (developer.yahoo.com/yql) and "rss2json" (rss2json.com).

The feedUrl will have to be the complete url to the file, "http://othersite.com/rss/example.rss", not a relative one, so that the service knows where to load it from.

The loadType will be "process" and the loadProcess can be "YQL" (developer.yahoo.com/yql, default), "rss2json" (rss2json.com) or "self" (load-rss.php file).

The initialization code will look like this:

jQuery(".modern-ticker").modernTicker({
    ...
    feedType: "rss",
    feedUrl: "http://othersite.com/rss/example.rss",
    loadType: "process",
    loadProcess: "YQL",
    ...
});

Loading from another domain directly by using "Access-Control-Allow-Origin"

Another way of loading files from another domain is directly (loadType: "direct") and avoid using any processing service but you will need to have loading permission from that domain.

What you will need is to have an Access-Control-Allow-Origin header on that domain specifically allowing your own domain to load from there.

For more info see Access-Control-Allow-Origin and HTTP access control (CORS).

JSON files

The same logic applies to JSON files as well except that if loadType: "process", then loadProcess will automatically be "self", to load the file using the load-json.php file.

4.2.5. JSON feed file format top

When loading data using the JSON feed, the supplied JSON files needs to have the following minimum format in order for the ticker to recognize and read it properly:

{
	"status": "ok",
	"items": [
		{
			"title": "News 1 news 1 news 1 news 1 news 1",
			"link": "http://www.creativetier.com"
		},
		{
			"title": "News 2 news 2 news 2 news 2 news 2",
			"link": "http://www.creativetier.com"
		},
		...
	]
}

You can find an example file with this format at load-files/feed.json.

An error response can have the following format, where the message supplied will be displayed by the ticker:

{
	"status": "error",
	"message": "Error message here."
}

4.2.6. Setup Twitter authentication top

This section applies to when using a Twitter feed to load ticker data.

With the 1.1 update of the Twitter API, information can no longer be accessed anonymously and you need to authenticate your application in order to be able to access data from Twitter. To do this, follow the steps below:

These instructions have been updated based on the Twitter Developers site as of 23 April 2017. Some things may slightly differ as time goes by and Twitter changes their site but the underlying instructions should remain the same.

Go to dev.twitter.com and, from the top menu, click My apps. If you are not logged in, you will be prompted to do so.

Now you are on the page displaying your Twitter apps. What you need to do is to create a new app from which you will obtain the 4 necessary authentication keys (Consumer Key, Consumer Secret, Access Token and Access Token Secret) that you can use when requesting data via the Twitter API.

Click the Create New App button, complete the required information and press the Create your Twitter application button. After that, you are redirected to the newly created application page.

Select the Keys and Access Tokens tab. In the Application Settings section, you can find the Consumer Key and Consumer Secret keys.

In the Your Access Token section, click the Create my access token button and the 2 other keys will be created, Access Token and Access Token Secret. (This process might take a few seconds and if you don't see anything, you can try refreshing the page.)

With these 4 keys available, go to the ticker files and open the load-twitter.php file, by default located in the modern-ticker/php folder. (You can change the path to this file from the JS initialization settings.)

At the top, you can find the following code where you need to input the 4 authentication keys:

$settings = array(
    'consumer_key' => '',
    'consumer_secret' => '',
    'access_token' => '',
    'access_token_secret' => ''
);

Enter each key between the quotes on each line. Be careful not to enter any white space between the quotes, but only the characters of the keys.

After including this authentication data and having completed all of the previous implementation steps of the ticker, everything should be completed and the Twitter feed should be functional.

Since the Twitter feed uses a PHP file, it won't work when testing the HTML file on your computer. You need to upload the ticker online where it has access to a server to process the PHP file and retrieve the data from Twitter.

5. Contact top

If you have any questions or need some help, please contact me.

The fastest way that you can get in touch with me is to simply send me an email at [email hidden in preview].

Another option to send me a message is to use the contact form on my CodeCanyon profile page.

Or you can simply post a message on the project message board and I will answer you there.

6. Credits top

Thank you to the following for the resources used in this project: