Swift News - jQuery Plugin

v1.3

Created: 06/12/2013
Latest update: 10/03/2015
By: LCweb
Website: http://www.lcweb.it
E-mail: support@lcweb.it

Thank you for purchasing my plugin. If you have any questions that are beyond the scope of this help file, please feel free to open a ticket on my support platform. Thanks so much!


PRIOR NOTE:
on August 08, 2015, the plugin name changed to Swift Box due to a copyright dispute

Installation

Swift News requires at least jQuery v1.7 in order to work with all its features.
If you don't use the lightbox, the minimum requirement is jQuery v1.5

The plugin is modular, therefore is coded to append automatically themes and additional javascript resources.
The basic installation requires only the main javascript and css files to be added in the website.

<!doctype html>
<html>
    <head>
        <link rel="stylesheet" type="text/css" href="swift-box-js/swift-box-layout.min.css" />
    
        <script src="swift-box-js/js_assets/jquery-1.12.4.min.js"></script>
        <script src="swift-box-js/swift-box.min.js"></script>
    </head>
    <body>
        <div id="swift_box"></div>
    
        <script type="text/javascript">
        $(document).ready(function(e) {
             $('#swift_box').lc_swift_box({

             });
        });
        </script>
    </body>
</html>

As good practice, to improve page loading performance, always call the javascript file in the website footer. Just before the BODY tag closing

            <!doctype html>
            <html>
                <head>
                    <link rel="stylesheet" type="text/css" href="swift-box-js/swift-box-layout.min.css" />
                    <script src="//ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js">
                </head>
                <body>
                    

                
                	<script src="swift-box-js/swift-box.min.js">
                    <script type="text/javascript">
                    $(document).ready(function(e) {
                         $('#swift_box').lc_swift_box({
    
                         });
                    });
                    </script>
                </body>
            </html>


IMPORANT:

Since the plugin auto-loads themes and scripts, is essential to not change the position or rename or delete any file inside the "swift-box-js" folder.

Basic Usage

To create your first news box the required code is very basic. This example will fetch news from the CNBC rss feed:

            <link rel="stylesheet" type="text/css" href="swift-box-js/swift-box-layout.min.css" />
            <script src="swift-box-js/swift-box.min.js">
            <script type="text/javascript">
            $(document).ready(function(e) {
                 $('#swift_box').lc_swift_box({
                    src : [
                        {
                            type: 'rss',
                            url: 'http://www.cnbc.com/id/100727362/device/rss/rss.xml'
                        }
                    ]
                 });
            });
            </script>

Content sources

The plugin is able to fetch contents from any RSS feed, inline texts and from Socials (Facebook, Google+, Twitter, Youtube and Pinterest).
How to use:

RSS feed

Simply copy the feed URL (example for CNBC and Envato Notes)

                 $('#swift_box').lc_swift_box({
                    src : [
                        {
                            type: 'rss',
                            url: 'http://www.cnbc.com/id/100727362/device/rss/rss.xml'
                        }
                    ]
                 });

Facebook pages

Is possible to fetch posts only from pages. What you need to know is the page ID, that is easily recoverable using this website.
For example the Envato's page ID is 80655071208

                 $('#swift_box').lc_swift_box({
                    src : [
                        {
                            type: 'facebook',
                            id: '80655071208'
                        }
                    ]
                 });

Google+

Use the profile URL that you want to use as source
For example, to fetch contents from the Envato's profile use this URL:https://plus.google.com/107285294994146126204/posts

                 $('#swift_box').lc_swift_box({
                    src : [
                        {
                            type: 'google',
                            id: 'https://plus.google.com/107285294994146126204/posts',
                            use_avatar: true
                        }
                    ]
                 });

Enabling the "use_avatar" option you can set the profile avatar as fixed image for the news

Twitter

IMPORANT: latest Twitter API doesn't support javascript fetching. A PHP OAuth is required.
Swift News already has everything is needed, but you must use it on a proper linux server.

Use the profile ID without "@"
For example, to fetch tweets from the Envato's profile use: envato

                 $('#swift_box').lc_swift_box({
                    src : [
                        {
                            type: 'twitter',
                            id: 'envato',
                            include_retweet: true,
                            use_avatar: true
                        }
                    ]
                 });

Enabling the "use_avatar" option you can set the profile avatar as news image, if tweet has no image

Youtube

Use the profile ID, contained in the profile URL.
For example, to fetch videos from the Envato's profile (http://www.youtube.com/user/envato) use: envato

                 $('#swift_box').lc_swift_box({
                    src : [
                        {
                            type: 'youtube',
                            id: 'envato'
                        }
                    ]
                 });

Pinterest

Use the URL of a specific user's board.
For example, to fetch contents from the "Company Life" board of the Envato's profile use: envato

                 $('#swift_box').lc_swift_box({
                    src : [
                        {
                            type: 'pinterest',
                            url: 'http://www.pinterest.com/envato/inside-envato/'
                        }
                    ]
                 });

Soundcloud

Use the URL of a specific user's page. Example for the Anjunabeats channel:

                 $('#swift_box').lc_swift_box({
                    src : [
                        {
                            type: 'soundcloud',
                            url: 'https://soundcloud.com/anjunabeats'
                        }
                    ]
                 });

Tumblr

Use the Tumblr blog URL (note: only photo/text/link posts can be fetched). Example for "Yacht Cats" blog:

                 $('#swift_box').lc_swift_box({
                    src : [
                        {
                            type: 'tumblr',
                            url: 'http://yachtcats.net/'
                        }
                    ]
                 });

Inline contents

Swift News is ready to be integrated in any common website, fetching inline contents. However they must have a specific stucture: 

                    

                         
                 	
 

                    <script type="text/javascript">
                    $(document).ready(function(e) {
                         $('#swift_box').lc_swift_box();
                    });
                    </script>
  • Articles must be wrapped by an element having the nb_news_wrap class
  • The article tag has the datetime attribute where you have to place the timestamp in a valid format
  • The news image (optional) must be placed before the section tag
  • The header tag contains the news title
  • The section tag contains the news text. You can use other HTML elements within
  • The blockquote tag (optional) contains the news excerpt. You can use other HTML elements within
  • The news link must have the lcnb_inline_link clss
  • The news video (optional) must be placed before the section tag, with the "lcnb_video" class.
    It could be a youtube or a Vimeo url. It can handle also any embeddable url, like a dailymotion one.

To mix the news sources, just append multiple sources to the same newsbox:

         $('#swift_box').lc_swift_box({
            src : [
                {
                    type: 'pinterest',
                    url: 'http://www.pinterest.com/envato/company-life/'
                },
                {
                    type: 'rss',
                    url: 'http://www.cnbc.com/id/100727362/device/rss/rss.xml'
                },
                {
                    type: 'youtube',
                    id: 'envato'
                }
            ]
         });

Advanced news management

Each external content fetched by Swift News can be managed by a powerful system, letting you strip or remove HTML elements and have always a clean result.
Here's a full featured demoof what you can do with each source:

         $('#swift_box').lc_swift_box({
            src : [
                {
                    type: 'rss',
                    url: 'http://www.cnbc.com/id/100727362/device/rss/rss.xml',
                    
                    strip_tags: 'p, strong',
                    remove_tags: 'img',
                    hide_elements: 'title',
                    link_target: '_blank',
                    self_s_link: true,
                    author: 'World News:',
                    img: 'url_to_fixed image',
                    max_img_size: {w : 750, h : 750},
                    exp_img_manag: {pos : 'hidden', w : '1_3', h : 300}
                }
            ]
         });

Name Data Type Description Example
strip_tags javascript selectors split by commas Subjects content will be kept as plain text and the tags removed 'p, span, strong'
remove_tags javascript selectors split by commas Subjects and contents will be removed 'table, img, ul'
hide_elements elements devided by commas Remove the selected elements from boxes. Available options: title, image, link 'title, link'
link_target <a> tag, target attributes Apply the attribute to the news link '_blank'
self_s_link boolean Use the page's URL in sharing systems true
author plain text or HTML Prepend some content to each news text. Useful to write the news author or the news subject 'World News:'
img image URL Apply a fixed image to every news '//www.domain.com/link_to_image.jpg'
max_img_size object (PHP server required) Image size check. Each news image is checked and eventually resized, is useful to keep images light. Values are intended in pixels. {w : 750, h : 750}
exp_img_manag object

Overrides default images management settings in expanded mode. You can override one value more values

pos → overrides exp_main_img_posoption
w → overrides exp_img_woption
h → overrides exp_img_hoption

Follow related option guide to know which values to use. 		{pos : 'hidden', w : '1_3', h : 300}

Inline contents

Also with inline contents you can control images management. This is the complete syntax to use

As you can see the nb_news_wrap wrapper has got specific attributes

Name Data Type Description
link_target string Overrides standard link target. Values: "_top", "_self", "_blank"
img_max_w integer (PHP server required) Set images max width and eventually resizes them
img_max_h integer (PHP server required) Set images max height and eventually resizes them
exp_img_pos string overrides exp_main_img_posoption (follow related option guide to know which values to use)
exp_img_w string overrides exp_img_woption (follow related option guide to know which values to use)
exp_img_h integer/string overrides exp_img_hoption (follow related option guide to know which values to use)
strip_tags javascript selectors split by commas Subjects content will be kept as plain text and the tags removed
remove_tags javascript selectors split by commas Subjects and contents will be removed

Main Options

Swift News has a lot of options to customize its aspect and behaviors. The syntax to apply them is:

         $('#swift_box').lc_swift_box({
            theme: 'minimal', 		// <- option 1
            layout: 'horizontal', 	// <- option 2
            height: 350, 			// <- option 3
            social_share: true, 	// <- option 4
            
            src : [   
                {
                    type: 'rss',
                    url: 'http://www.cnbc.com/id/100727362/device/rss/rss.xml',
                }
            ]
         });

Initial mode

Name Description Data Type options Default Value
theme Swift News theme to apply string Skin names: for the minimal.css file, use "minimal" 'light'
layout Main layout to use string horizontal, vertical 'horizontal'
height Swift News height in pixels integer number 300
min_news_h Minimum news height in pixels. The value is used for vertical layout integer number 100
min_news_w Minimum news width in pixels. The value is used for horizontal layout integer number 150
min_horiz_w Minimum width (in pixels) for the horizontal layout. If the news box is shorter than this value, the main layout will be changed to vertical, to fit better mobile screens integer number 400
horiz_img_h Height in pixels for the news image on horizontal layout integer number 180
vert_img_w Width in pixels for the news image on vertical layout integer number 200
read_more_txt Code appended at the end of shortened code in every box string '..'
boxed_news display each news into a separated box boolean false
horiz_img_mode Full-height image and no description in horizontal layout (applied only if there's an image) boolean false
buttons_position Socials, link, expand and date position. Side position is usable only on boxed news and vertical layout string bottom, top, side bottom
btn_over_img Place bottons over the image (only for bottons_position : side) boolean false
max_news Maximum news number to fetch integer number 6
news_per_time News to show per time. This value might be affected by min_news_w/min_news_h integer number 3
cache_news Use the AJAX cache boolean false
social_share Show the social share button boolean true
hide_elements Same function of the one in each source, but acts globally string date → news date in buttons bar
title → news title
image → news main image
link → news link (disables also title and image "link behavior")
btn_bar → completely hides buttons bar + date
show_src_logo Show the news source's logo in the box (only for vertical layout) boolean false
script_basepath Basepath of the plugin folder. Is used to append automatically skins and scripts string (automatic)
touchswipe Activate the touchswipe interaction boolean true
lightbox Activate the lightbox for news images and youtube videos boolean true
title_behavior Set title's behavior on click. string none → no action associated
expand → expand news
link → redirect users to news link
 expand
img_behavior Set image's behavior on click (with related overlay's icon) string none → no action associated
expand → expand news
link → redirect users to news link
lightbox → launch lightbox
 lightbox
date_format Date format displayed. Mix it freely (placeholders guide) string SS, MM, H, HH, HHH, d, dd, ddd, dddd, m, mm, mmm, mmmm, yy, yyyy "d mmmm yyyy"
elapsed_time Show the elapsed time instead of the news date boolean false
read_more_btn Replace date box with a "read more" button boolean false
read_more_btn_txt Text displayed in the "read more" button string Read more
Navigation

Name Description Data Type options Default Value
nav_arrows Show the navigation arrows and set their position. string / bool(false) false, side, top_l, top_c, top_r, bottom_l, bottom_c, bottom_r false
autoplay Automatic news sliding on page loading boolean false
animation_time Animation timing in millisecods integer number 400
slideshow_time Interval time of the slideshow in milliseconds integer number 6000
carousel Use infinite carousel mode boolean false
pause_on_hover Pause and restart the autoplay on box hover boolean true
slide_all Slide all visible elements per time (only in slideshow) boolean false
Expanded mode

Name Description Data Type options Default Value
expandable_news Add "+" button and allow to expand news to see full contents boolean true
scroll_exp_elem Keep image and close button always visible on high expanded news boolean true
exp_main_img_pos Set news main image position string inside → prepend it in news text
side → put on left column
hidden → hide it
 inside
manage_exp_images Manage news images to become sizable and add lightbox support boolean true
exp_img_w Image's container width string 1_1 → fullwidth
1_2 → half wrapper width
1_3 → one third's wrapper width
1_4 → one fourth's wrapper width
 1_2
exp_img_h Image's container height in pixels. Use auto to keep image proportions integer/string 225
autop_after_exp Resume autoplay after expanded element closing boolean false

Create Skins

The plugin has been built to support multiple themes and to let users customize it easily. By default it comes with three themes: white, dark and minimal.
To create a skin, simply start from one of them.

The most important thing is the CSS base selector. It must be in the .lcnb_THEME-NAME_theme format.
If your theme is called green the base selector must be .lcnb_green_theme

Once the theme complete, name it with the style name.
For the .lcnb_green_theme the file must be green.css and be kept in the themes folder of the plugin.

Finally, use it in Swift News:

         $('#swift_box').lc_swift_box({
            theme: 'green',
            src : [
                {
                    type: 'rss',
                    url: 'http://www.cnbc.com/id/100727362/device/rss/rss.xml',
                }
            ]
         });

Tip and Tricks

Some special usage examples:

Continuous sliding effect

To create a continuous sliding effect youjst have to set an high animation_time value and a slideshow_time equal to zero.
The plugin is coded to recognize this settings and change its behavior, creating a "breaking news bar" result.

                 $('#swift_box').lc_swift_box({
                 	min_horiz_w: 0,
                    autoplay: true,		
                    animation_time: 20000, // 20 seconds
                    slideshow_time: 0,
                    carousel: true,		
                    
                    src : [
                        {
                            type: 'rss',
                            url: 'http://www.cnbc.com/id/100727362/device/rss/rss.xml'
                        }
                    ]
                 });

Colored subject box

As explained in the news sources chapter, you can use also HTML in the author option.
This is an example of what you can do adding a bit of code to display the news categories:

                 $('#swift_box').lc_swift_box({
                    src : [
                        {
                            type: 'rss',
                            url: 'http://www.cnbc.com/id/100727362/device/rss/rss.xml',
                            author: 'Top News'
                        },
                        {
                            type: 'rss',
                            url: 'http://www.cnbc.com/id/20910258/device/rss/rss.html',
                            author: 'Economy'
                        }
                    ]
                 });

I used inline CSS, but as good practice you should use a CSS class and write the code in the Swift News theme file. This is the result:

Custom date rapresentation

As explained in the main options chapter, you can use also symbols and codes to compose the date format.
In fact you can customize it also with HTML, taking care to not use wrongly one of the placeholders.

This is a little example of what you can achieve:

                 $('#swift_box').lc_swift_box({
                    date_format: 'd/mmm
yyyy',
                    
                    src : [
                        {
                            type: 'pinterest',
                            url: 'http://www.pinterest.com/envato/company-life/'
                        }
                    ]
                 });

I used inline CSS, but as good practice you should use a CSS class and write the code in the Swift News theme file. This is the result:

Date Localization

Swift News is ready to be translated in any language, in fact days/months/times names are kept in editable arrays.
Default english localization:

         $('#swift_box').lc_swift_box({
            short_d_names: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"],
			full_d_names : ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"],
			short_m_names: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
			full_m_names : ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"],
			elapsed_names: ["ago", "seconds", "minute", "minutes", "hour", "hours", "day", "days", "week", "weeks", "month", "months"],
            
            src : [
                {
                    type: 'rss',
                    url: 'http://www.cnbc.com/id/100727362/device/rss/rss.xml',
                }
            ]
         });

Then simply translate strings. Italian example:

         $('#swift_box').lc_swift_box({
            short_d_names: ["Dom", "Lun", "Mar", "Mer", "Gio", "Ven", "Sab"],
			full_d_names : ["Domenica", "Lunedì", "Martedì", "Marcoledì", "Giovedì", "Venerdì", "Sabato"],
			short_m_names: ["Gen", "Feb", "Mar", "Apr", "Mag", "Giu", "Lug", "Ago", "Sep", "Ott", "Nov", "Dic"],
			full_m_names : ["Gennaio", "Febbraio", "Marzo", "Aprile", "Maggio", "Giugno", "Luglio", "Agosto", "Settembre", "Ottobre", "Novembre", "Dicembre"],
			elapsed_names: ["fa", "secondi", "minuto", "minuti", "ora", "ore", "giorno", "giorni", "settimana", "settimane", "mese", "mesi"],
            
            src : [
                {
                    type: 'rss',
                    url: 'http://www.cnbc.com/id/100727362/device/rss/rss.xml',
                }
            ]
         });

Date Placeholders

Here's the placeholders list to compose dates. Examples are done using July 06 2013 - 09:05:20
Remember that you can mix them with symbols or also a bit of HTML to customize the result.

Placeholder Description Example
SS seconds (with leading zeros) 20
MM minutes (with leading zeros) 05
HHH hours with AM/PM 9 AM
HH hours (with leading zeros) 09
H hours (without leading zeros) 9
dddd day with Monday-Sunday format Saturday
ddd day with Mon-Sun format Sat
dd day number (with leading zeros) 06
d day number (without leading zeros) 6
mmmm month with January-December format July
mmm day with Jan-Dec format Jul
mm day number (with leading zeros) 07
m day number (without leading zeros) 7
yyyy year in four digits format 2013
mmm year in two digits format 13

Public Methods

Destroy plugin instance

                 <script type="text/javascript">
                 $(document).ready(function(e) {
					 $('#swift_box').lc_swift_box(); // initialize instance 
					 $('#swift_box').lcsb_destroy(); // destroy
				 });
                 </script>


Pagination

                 <script type="text/javascript">
                 $(document).ready(function(e) {
                     $('#swift_box').lc_swift_box(); // initialize plugin
                     
                     // show next element
                     $('#swift_box').lcsb_paginate('next');
                     
                      // show previous element
                     $('#swift_box').lcsb_paginate('prev');
                 });
                 </script>


Start / stop slideshow

                 <script type="text/javascript">
                 $(document).ready(function(e) {
                     $('#swift_box').lc_swift_box(); // initialize plugin
                     
                     // stop slideshow on mouse hover - then restart
                     $('body').on({
                        mouseenter: function () {
                           $('#swift_box').lcsb_stop_slideshow();
                        },
                        mouseleave: function () {
                           $('#swift_box').lcsb_start_slideshow();
                        }
                    }, '#swift_box');
                 });
                 </script>