# 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:

                                      Article 1

                                      Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod. Quis aute iure reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint obcaecat cupiditat non proident.

                                      News excerpt 1
                                      link

                                      Article 2

                                      Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod. Quis aute iure reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint obcaecat cupiditat non proident.

                                      News excerpt 2
                                      link

                          <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

                            Article 1
                            Lorem ipsum dolor sit amet,

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>