“Television News Ticker” Documentation by “DAEXT” v1.05

“Television News Ticker”

Created: 14/03/2018
By: DAEXT
Email: support@daext.com

Thank you for using Television News Ticker. If you have any questions that are beyond the scope of this help file please contact us via email or with the contact form available in our CodeCanyon Profile.

Installation
News Sources
Options
Credits
FAQ

A) Installation

The installation of Television News Ticker can be completed in four simple steps:

1 - Add the Open Sans font

The default font used by the news ticker is the bold variation of the Open Sans font. To embed this font in your webpage copy this code in the <head> of your html document:

<link href="https://fonts.googleapis.com/css?family=Open+Sans:700" rel="stylesheet">

Please note that you can skip this step if you are planning to use a different font family for the news ticker. More information on how to change the font family are available in the Options section.

2 - Load the CSS file

Add this <link> tag in the <head> section of the webpage:

<link rel="stylesheet" type="text/css" href="newsTicker.css">

You can find the compressed production version of the newsTicker.css file in the tnt/Production/css/ folder and the development version in the tnt/Development/css/ folder.

3 - Load the JavaScript file

Add this <script> tag in the <head> section of the webpage:

<script src="newsTicker.js"></script>

You can find the compressed production version of the newsTicker.js file in the tnt/Production/js/ folder and the development version in the tnt/Development/js/ folder.

4 - Initialize the News Ticker

Add this code at the end of the <head> section of the webpage:

<script>
newsTicker.initialize({
  newsDataJson: 'data.json'
});
</script>

The script above initializes the news ticker and the data.json file will be used as the source for the news.

To know more about the newsDataJson option and on the structure of the JSON file that should be provided to the news ticker please read the News Sources section.

If you are interested on all the 61 customization options available for the news ticker please read the Options section.

B) News Sources

The value associated with the newsDataJson option should point to a valid JSON resource in this format:

{
  "featurednews": {
    "newstitle": "",
    "newsexcerpt": "",
    "url": ""
  },
  "slidingnews": [
    {
      "newstitle": "",
      "url": ""
    }
  ]
}

This is an example with the featured news (the news included in the big area above the slider) enabled and two sliding news (the news that slide below the featured news):

{
  "featurednews": {
    "newstitle": "The featured news title",
    "newsexcerpt": "The featured news excerpt",
    "url": "http:\/\/example.com\/featured-news\/"
  },
  "slidingnews": [
    {
      "newstitle": "The title of the first sliding news",
      "url": "http:\/\/example.com\/first-sliding-news\/"
    },
    {
      "newstitle": "The title of the second sliding news",
      "url": "http:\/\/example.com\/second-sliding-news\/"
    }
  ]
}

This is an example with the featured news disabled and two sliding news:

{
  "featurednews": {
    "newstitle": "",
    "newsexcerpt": "",
    "url": ""
  },
  "slidingnews": [
    {
      "newstitle": "The title of the first sliding news",
      "url": "http:\/\/example.com\/first-sliding-news\/"
    },
    {
      "newstitle": "The title of the second sliding news",
      "url": "http:\/\/example.com\/second-sliding-news\/"
    }
  ]
}

You are free to generate the JSON data used by the news ticker with your favorite method, but consider that this product comes with three ready-to-use PHP files able to generate the JSON data required by the news ticker.

Generate the news from an RSS feed

A news ticker which receives the news from a specific RSS feed should be initialized with this code:

<script>
newsTicker.initialize({
  newsDataJson: 'source/rss.php',
  rssUrl: 'http://feeds.bbci.co.uk/news/world/rss.xml?edition=uk',
});
</script>

Two parameters are passed during the initialization process:

newsDataJson which points to the PHP file that dynamically generates the JSON data from an RSS feed
rssUrl which is the URL of the RSS feed (in this case the RSS feed of BBC World News has been used but you can obviously enter the URL of the RSS feed you are interested in)

Generate the news from Twitter

A news ticker which receives the news from a specific Twitter account should be initialized with this code:

<script>
newsTicker.initialize({
  newsDataJson: 'source/twitter.php',
  twitterUsername: 'envato',
});
</script>

Two parameters are passed during the initialization process:

newsDataJson which points to the PHP file that dynamically generates the JSON data from a Twitter account
twitterUsername which is the Twitter username from which the data are retrieved (in this case the "envato" username has been used but you can obviously enter the username you are interested in)

Note that the initialization above is not enough to actually receive data from Twitter, you should also provide the proper keys and access tokens to Twitter.

To generate your keys and access tokens follow this procedure:

Create a Twitter App from this page
In the Permissions tab keep the Access to Read Only
Visit the Keys and Access Tokens tab

Once you have your keys and access tokens edit the source/twitter.php file and fill the four following PHP variables with your keys and access tokens: (line 4 to 7)

$oauth_access_token = '';
$oauth_access_token_secret = '';
$consumer_key = '';
$consumer_secret = '';

It's important to note that local development environment (like WAMP, XAMPP, etc.) are usually not properly configured to retrieve the required information from Twitter. For this reason it's recommended to use Twitter as a source only on real web servers.

Generate the news from a custom database table

A news ticker which receives the news from a database table should be initialized with this code:

<script>
newsTicker.initialize({
  newsDataJson: 'source/database.php',
});
</script>

One parameter is passed during the initialization:

newsDataJson which points to the PHP file that dynamically generates the JSON data from a database table

The sources/database.php file should be configured with all the information required by PHP to perform a database connection, to achieve this simply replace the default value of these constants: (line 32 to 35)

DEFINE('DB_HOST', 'localhost');
DEFINE('DB_USER', 'root');
DEFINE('DB_PASSWORD', '');
DEFINE('DB_NAME', 'db1');

The default name of the database table and the default names of the database table fields should also be replaced with the real names. (line 39 and subsequent references included in the while loop)

C) Options

This product has a total of 61 customization options. To use a customization option set its value during the initialization process of the news ticker.

This example demonstrates how to define a custom number of displayed news with the numberOfNews option.

<script>
newsTicker.initialize({
  newsDataJson: 'data.json',
  numberOfNews: 20,
});
</script>

Use this table to understand how each option should be used:

Name	Type	Default	Description
newsDataJson	String	source/static.json	The URL to the news data in JSON format.
cachedCycles	Number	0	The number of cycles that should be performed without retrieving the news.
tickerClosedInitial	Boolean	False	This option determines the initial status of the news ticker (Open or Closed). Please note that the cookie used to store the status has priority over this option.
layout	String	'ltr'	The layout of the news ticker. 'ltr' defines a left to right layout and 'rtl' defines a right to left layout.
moveInterval	Number	10	This value determines the interval in milliseconds used to move the sliding news. A low value increases the speed, a high value reduces the speed.
token	Number	0	Set this token if you plan to verify server-side the AJAX request with your custom mechanism before returning the news ticker data. The server-side generation of the token should be manually implemented based on your needs.
hideFeaturedNews	Boolean	False	This option determines if the featured news are displayed or not.
numberOfNews	Number	10	This option determines the number of news displayed in the news ticker.
rssUrl	String	''	This option should be used to set the URL of the RSS feed.
twitterUsername	String	''	The Twitter username for which you want to retrieve the news.
twitterStripLinks	Boolean	False	This option determines if the links should be removed from the imported tweets.
twitterStripHashtags	Boolean	False	This option determines if the hashtags should be removed form the imported tweets.
twitterStripUsernames	Boolean	Fasle	This option determines if the usernames should be removed from the imported tweets.
featuredNewsBackgroundColor	String	'#c90016'	The color of the featured news background. Should be provided as a string with the color in HEX format (eg. '#ff0000') or in RGBA format. (eg. 'rgba(255, 0, 0, 0.8)')
featuredNewsTitleColor	String	'#eee'	The color of the featured news title text. Should be provided as a string with the color in HEX format (eg. '#ff0000') or in RGBA format. (eg. 'rgba(255, 0, 0, 0.8)')
featuredNewsTitleColorHover	String	'#111'	The color of the featured news title text in hover state. Should be provided as a string with the color in HEX format (eg. '#ff0000') or in RGBA format. (eg. 'rgba(255, 0, 0, 0.8)')
featuredNewsTitleFontSize	Number	38	The font size of the featured news title text in pixels.
featuredNewsTitleFontWeight	Number	700	The font weight of the featured news title text.
featuredNewsTitleFontFamily	String	'\'Open Sans\', sans-serif'	The font family of the featured news title text.
featuredNewsTitleFontStyle	String	'normal'	The font style of the featured news title text. (possible values are 'normal', 'italic' and 'oblique')
featuredNewsTitleTextTransform	String	'uppercase'	The text transform value of the featured news title text. (possible values are 'none', 'capitalize', 'uppercase', 'lowercase')
featuredNewsTitleMaxLength	Number	255	The maximum number of characters displayed for the featured news title. If the actual title is longer than the limit imposed with this option the title will be truncated with final ellipsis.
featuredNewsTitleEnableLinks	Boolean	True	Whether to enable or not the link associated with the featured news title.
featuredNewsTitleOpenLinkTab	Boolean	False	Whether to open in a new tab or not the link associated with the featured news title.
featuredNewsExcerptColor	String	'#eee'	The color of the featured news excerpt text. Should be provided as a string with the color in HEX format (eg. '#ff0000') or in RGBA format. (eg. 'rgba(255, 0, 0, 0.8)')
featuredNewsExcerptFontSize	Number	28	The font size of the featured excerpt title text in pixels.
featuredNewsExcerptFontWeight	Number	700	The font weight of the featured news excerpt text.
featuredNewsExcerptFontFamily	String	'\'Open Sans\', sans-serif'	The font family of the featured news excerpt text.
featuredNewsExcerptFontStyle	String	'normal'	The font style of the featured news excerpt text. (possible values are 'normal', 'italic' and 'oblique')
featuredNewsExcerptTextTransform	String	'none'	The text transform value of the featured news excerpt. (possible values are 'none', 'capitalize', 'uppercase', 'lowercase')
featuredNewsExcerptMaxLength	Number	255	The maximum number of characters displayed for the featured news excerpt. If the actual excerpt is longer than the limit imposed with this option the title will be truncated with final ellipsis.
slidingNewsBackgroundColor	String	'#000000'	The color of the sliding news background. Should be provided as a string with the color in HEX format (eg. '#ff0000') or in RGBA format. (eg. 'rgba(255, 0, 0, 0.8)')
slidingNewsColor	String	'#eee'	The color of the sliding news text. Should be provided as a string with the color in HEX format (eg. '#ff0000') or in RGBA format. (eg. 'rgba(255, 0, 0, 0.8)')
slidingNewsColorHover	String	'#aaaaaa'	The color of the sliding news text in hover state. Should be provided as a string with the color in HEX format (eg. '#ff0000') or in RGBA format. (eg. 'rgba(255, 0, 0, 0.8)')
slidingNewsFontSize	Number	28	The font size of the sliding news text in pixels.
slidingNewsFontWeight	Number	700	The font weight of the sliding news text.
slidingNewsFontFamily	String	'\'Open Sans\', sans-serif'	The font family of the sliding news text.
slidingNewsFontStyle	String	'normal'	The font style of the sliding news text. (possible values are 'normal', 'italic' and 'oblique')
slidingNewsTextTransform	String	'uppercase'	The text transform value of the sliding news text. (possible values are 'none', 'capitalize', 'uppercase', 'lowercase')
slidingNewsPadding	Number	112	The padding between the sliding news in pixels.
slidingNewsMaxLength	Number	255	The maximum number of characters displayed for the sliding news text. If the actual sliding news text is longer than the limit imposed with this option the sliding news text will be truncated with final ellipsis.
slidingNewsEnableLinks	Boolean	True	Whether to enable or not the link associated with the sliding news.
slidingNewsOpenLinksNewTab	Boolean	False	Whether to open in a new tab or not the link associated with the sliding news text.
showClock	Boolean	True	Whether to show or not the clock.
clockColor	String	'#111'	The color of the clock text. Should be provided as a string with the color in HEX format (eg. '#ff0000') or in RGBA format. (eg. 'rgba(255, 0, 0, 0.8)')
clockFontSize	Number	28	The font size of the clock text in pixels.
clockFontWeight	Number	700	The font weight of the clock text.
clockFontFamily	String	'\'Open Sans\', sans-serif'	The font family of the clock text.
clockFontStyle	String	'normal'	The font style of the clock text. (possible values are 'none', 'capitalize', 'uppercase', 'lowercase')
clockUpdate	Number	1000	This value determines how frequently the clock should be updated in milliseconds.
clockBackgroundImage	String	The value is too long to be displayed in this reference	The image used as a background for the clock provided in base64 format. The recommended dimensions are 80x40 pixels. For details please see the FAQ How to use custom images.
showOpenCloseButton	Boolean	True	Whether to show or not the Open/Close button.
openButtonBackgroundImage	String	The value is too long to be displayed in this reference	The image used as a background for the open button provided in base64 format. The recommended dimensions are 80x40 pixels. For details please see the FAQ How to use custom images.
closeButtonBackgroundImage	String	The value is too long to be displayed in this reference	The image used as a background for the close button provided in base64 format. The recommended dimensions are 80x40 pixels. For details please see the FAQ How to use custom images.
enableMobileDevices	Boolean	False	This option determines if the news ticker should be enabled with mobile devices. The actual detection is performed via PHP with the Mobile Detect PHP library.
enableTabletDevices	Boolean	False	This option determines if the news ticker should be enabled with tablet devices. The actual detection is performed via PHP with the Mobile Detect PHP library.
enableDevices	Array[string]	[]	This option allows to enable the news ticker with specific mobile devices. The identifiers of the mobile devices should be provided as an array of strings. For details please see the FAQ How to enable the news ticker with specific mobile devices.
hideFeaturedNewsMaxWidth	Number	0	This option should be used to hide the featured news (with a media query that uses the max-width property) when the browser viewport width goes below the specified value in pixels.
hideFeaturedNewsMaxDeviceWidth	Number	0	This option should be used to hide the featured news (with a media query that uses the max-device-width property) when the device full screen size width goes below the specified value.
hideFeaturedNewsLandscape	Boolean	False	This option should be used to hide the featured news when the device orientation is 'landscape'.
hideFeaturedNewsPortrait	Boolean	False	This option should be used to hide the featured news when the device orientation is 'portrait'.
applyOnLoad	Boolen	True	This option determines if the news ticker should be initialized when the "load" event of the "window" object is triggered or directly when the initialization method is called.
callbacks	Object	{...}	This option allows to run custom code when specific events of the news ticker are triggered. For details please see the FAQ How to use the callbacks of the news ticker.

D) Credits

This product makes use of the following resources:

Mobile Detect licensed under the MIT License
Twitter API PHP licensed under the MIT License

For each library you can find the actual copy of the license inside the folder used to store the library files.

E) FAQ

Which versions of PHP are supported?

PHP 5.3 and later versions are supported.

How to use custom images?

You can set custom images for the clock, for the open button and for the close button by using the following options:

clockBackgroundImage
openButtonBackgroundImage
closeButtonBackgroundImage

The value of these option should be an image encoded in base64 format. This example demonstrates how to set a custom background image for the clock:

<script>
  newsTicker.initialize({
    newsDataJson: 'data.json',
    clockBackgroundImage: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAFAAAAAoCAMAAABevo0zAAAAIVBMVEUvL+0yMvsyMvwvL+wwMO4wMPEwMPAwMO8wMPIxMfMzM/28kAH0AAACNElEQVR42q1TW4LDIAg0NtWk9z/wKq8BWdP9WBIVEYenpX4+NdBxKFMX+i4fUEXgHi8ff4f9FHPqcBR2k7d9VFt0FFAOKk3rDT1dxDjmIdwIeSLkWwn1WcGIAfNZElV3ZWfePEyBWAi7azpsa0YUMFsyi8tdEmyiBSB+VAFztSW7ucrgYf2auzGeN+Khmcq1ro95zIuGzBJZhdFez/ezsRxyDaW1bW51qKWK+JDj+T713x/S3IaigMnmN+nc5TCYWnsn1/7X6u8aW6HCe0gZ1WUNShobh1vP4Nxio/oD8TC34S+p1z/HkkJ+yjmfhpe4efYK+G5nKa/yGjTXMYQGM/YiJI5UdM8CGyw625sBWXOspKd3DdYxalOG6BX+DFAsg9gjuWyLSlwQZpTVzz4A+8nO8eCZMA3aO8q7VTp556GCLF7SpAxs0cfS1f0BSB6KXgDQOrANK4TzFK7yCYdMHppKSKZu5k9cLIIlEQx7eHUBRP2IoT+EqrF5ZLtDKsghykfnGEAUXmSua80IikJ9g4TB4VBVhKfkDBNZDkPvh64QIe0jWTd7z83DwSJil0ib7dktfT/ldslV2SQIRCcxAKhoHAmiFKqHS5NpiePbR21CW8nKKeSnxyGjn2J0LLIAIQ7PUhu7XVIUe5BL2lF/F2NoMJr9W75aL0YnJl5K4u1chCNhoN6vcrd+/hu1912uq7XW+xjzV75PhqXCykTLEIq6Cfhv1wC87+s9PyJdM0HhgQbYD3S4F1iHv+hoAAAAAElFTkSuQmCC',
  });
</script>

You can find many encoder able to convert normal images in base64 format with the Google search engine, for example try this query.

How to enable the news ticker with specific mobile devices?

To enable the news ticker only with specific mobile devices you have to use the enableDevices option. The value of this option should be an array of strings and each string should be the identifier of the specific mobile device.

This example demonstrates how to enable the news ticker with iPhone and Samsung devices:

<script>
  newsTicker.initialize({
    newsDataJson: 'data.json',
    enableDevices: ['iPhone', 'Samsung'],
  });
</script>

This is the complete list of identifiers:

Iphone
BlackBerry
HTC
Nexus
Dell
Motorola
Samsung
LG
Sony
Asus
NokiaLumia
Micromax
Palm
Vertu
Pantech
Fly
Wiko
iMobile
SimValley
Wolfgang
Alcatel
Nintendo
AmoiI
NQ
GenericPhone

How to remove the news ticker from the page?

The destroy() method can be used to remove the news ticker from the page:

<script>
  newsTicker.destroy();
</script>

How to replace the existing news ticker with a new news ticker?

The destroy() method should first be used to remove the existing news ticker from the page, then the initialize() method should be used to create a new news ticker in the page. It's important to note that to create a news ticker in a page that is already completely loaded the applyOnLoad option should be set to false.

The example below demonstrate how to remove from the page the existing news ticker and create a new news ticker when the #create-new-news-ticker button is clicked:

<script>
  document.getElementById('create-new-news-ticker').addEventListener('click', function(){
    newsTicker.destroy();
    newsTicker.initialize({
      newsDataJson: 'source/rss.php',
      rssUrl: 'http://feeds.bbci.co.uk/news/world/rss.xml?edition=uk',
      applyOnLoad: false,
    });
  });
</script>

How to change the source of an existing news ticker?

The modifySource() method allows you to change the source of the news ticker. Note that, if the cachedCycles option is used to perform multiple cycles of news without retrieving the data, the changes determined with this method will be actually applied only when the news ticker has completed all the cached cycles.

The example below demonstrates how to change the URL of the RSS Feed when the #modify-source button is clicked:

<script>
  document.getElementById('modify-source').addEventListener('click', function(){
    newsTicker.modifySource({
      rssUrl: 'http://feeds.bbci.co.uk/news/world/rss.xml?edition=uk',
    })
  });
</script>

The following options are supported by the modifySource() method: (more information on the options are available in the Options section)

newsDataJson
token
enableMobileDevices
enableTabletDevices
enableDevices
hideFeaturedNews
numberOfNews
rssUrl
twitterUsername
twitterStripLinks
twitterStripHashtags
twitterStripUsernames

How to use the callbacks of the news ticker?

The script includes the following callback functions:

Callback	When it's executed
slidingNewsCompleted	Executed when the sliding news have completed a cycle
openButtonClicked	Executed when the open button is clicked
closeButtonClicked	Executed when the close button is clicked
ajaxRequestSent	Executed when the AJAX request used to retrieve the news ticker data is sent
ajaxRequestReceived	Executed when the AJAX request used to retrieve the news ticker data is received

This example demonstrates how to initialize a news ticker which displays an alert message when the close button is clicked:

<script>
  newsTicker.initialize({
    newsDataJson: 'source/rss.php',
    rssUrl: 'http://feeds.bbci.co.uk/news/world/rss.xml?edition=uk',
    callbacks: {
      closeButtonClicked: function(){alert("Close Button Clicked");}
    },
  });
</script>