Swift Box (JS) Documentation

Introduction

Before going through documentation chapters, thanks for purchasing Swift Box (JS) and trusting LCweb!

Need further help?

Need a customization?

Installation

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

The plugin is modular, therefore is coded to append automatically themes and additional javascript resources.
Basic installation requires only 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-3.3.1.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="swift-box-js/js_assets/jquery-3.3.1.min.js"></script>
	</head>
	<body>
		<div id="swift_box"></div>
	
		<script src="swift-box-js/swift-box.min.js"></script>
		<script type="text/javascript">
		$(document).ready(function(e) {
			 $("#swift_box").lc_swift_box({

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

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

Basic Usage

To create your first news box requires just some basic code. This example fetches news from the CNBC RSS feed:

<div id="swift_box"></div>
				
<script type="text/javascript">
$(document).ready(function(e) {
	 $("#swift_box").lc_swift_box({
        rss2json_token : "your-token", // read more about this parameter in the RSSfeed source chapter
		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, Youtube, Facebook (pages), Pinterest and Tumblr.

Let's analyze how to implement these sources:

RSS Feed

From January 2019 you must get an rss2json token to use this source.
Remember to use also the "rss2json_token" option

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

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

It must be a proper RSS feed though: with a standard structure, containing elements date and texts.

Youtube

From February 2021 you must get an Youtube API key to use this source (video guide).
Remember to use also the "youtube_key" option

Use the profile/channel ID, contained in the profile/channel 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"
	  }
  ]
});

You can also display elements from a specific playlist: in this case use the playlist ID.
Assuming you are playing a video belonging to a playlist, like this one: https://www.youtube.com/watch?v=8NZXG3kU94Q&list=PLXWu0OP8--WQJb01DUSFvGqINdezZra0u&index=1, the playlist ID is PLXWu0OP8--WQJb01DUSFvGqINdezZra0u

$("#swift_box").lc_swift_box({
  src : [
	  {
			type: "youtube",
			playlist: "PLXWu0OP8--WQJb01DUSFvGqINdezZra0u"
	  }
  ]
});

Facebook Pages

Facebook requires special app permissions to fetch contents.
Luckily we can use the FetchRSS service to get a true RSS feed for Facebook Pages.

Head to this page
Paste the Facebook page you want to get contents from and register
Go on your "My Feeds" page and copy the resulting feed URL (right click on the title and copy the link)
Use this feed link as a normal RSS source

Pinterest

From January 2019 you must get an rss2json token to use this source.
Remember to use also the "rss2json_token" option

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

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

Tumblr

From January 2019 you must get an rss2json token to use this source.
Remember to use also the "rss2json_token" option

Use Tumblr blog's URL. NOTE: only photo/text/link posts can be fetched).
Here's the example for "Yacht Cats" blog:

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

Zapier Feed

From January 2019 you must get an rss2json token to use this source.
Remember to use also the "rss2json_token" option

Zapier is a great (free) service allowing you to create RSS feed starting from various actions.
In this video you can see how to create a feed starting from your Facebook page contents

Once you configured the Feed composition, simply copy and use its URL

$("#swift_box").lc_swift_box({
  rss2json_token : "your-token",
  src : [
	  {
		  type: "rss",
		  url: "the-feed-url"
	  }
  ]
});

Inline HTML

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

<div id="swift_box">
	<div class="nb_news_wrap" style="display: none;">
	
		<article datetime="2014-12-31T21:09:36+01:00" >
			<header>Article 1</header>
			<img src="" lazy-src="the_image_url.jpg" />
			<div class="lcnb_video" src="http://www.youtube.com/watch?v=Lv-sY_z8MNs"></div>
			
			<section>Lorem ipsum dolor sit amet, <a href="link_to_somewhere">consectetur adipisici elit</a>, sed eiusmod. <p>Quis aute iure reprehenderit in voluptate velit esse cillum dolore eu fugiat</p> nulla pariatur. Excepteur sint obcaecat cupiditat non proident.
			</section>
			
			<blockquote>News excerpt 1</blockquote>
			<a href="link_to_article" class="lcnb_inline_link">link</a>
		</article>
		
		<article datetime="2014-12-30T21:09:36+01:00" >
			<header>Article 2</header>
			<img src="" lazy-src="the_image_url.jpg" />
			<div class="lcnb_video" src="http://vimeo.com/40291524"></div>
			
			<section>Lorem ipsum dolor sit amet, <a href="link_to_somewhere">consectetur adipisici elit</a>, sed eiusmod. <p>Quis aute iure reprehenderit in voluptate velit esse cillum dolore eu fugiat</p> nulla pariatur. Excepteur sint obcaecat cupiditat non proident.
			</section>
			
			<blockquote>News excerpt 2</blockquote>
			<a href="link_to_article" class="lcnb_inline_link">link</a>
		</article>
	</div> 
</div> 

<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. It supports LAZY-SRC attribute, to defer images loading and improve page's speed
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.

Mix Sources

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

$("#swift_box").lc_swift_box({
	rss2json_token : "your-token",
	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 Contents Management

Each external content fetched by Swift Box 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",
		  
          match_words: ["keyword1", "keyword2"],
		  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},
          group_exp_images: false,
	  }
  ]
});

Name	Data Type	Description	Example
match_words	array	Subjects content will be kept as plain text and the tags removed	"p, span, strong"
strip_tags	javascript selectors split by commas	Keywords array to filter fetched contents. Only matching posts will be kept	["keyword1", "keyword2"]
remove_tags	javascript selectors split by commas	Subjects and contents will be removed	"table, img, ul"
hide_elements	array	Remove chosen 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}
group_exp_images	boolean	Source-specific option to group images in expanded mode, creating a sort of a gallery after textual contents	false

Advanced HTML Content Parameters

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

<div id="swift_box">
	<div class="nb_news_wrap" style="display: none;" link_target="_blank" img_max_w="250" img_max_h="1000" exp_img_pos="side" exp_img_w="1_3" exp_img_h="225" strip_tags="em" remove_tags="h4" group_exp_images="0">
		<article datetime="2014-12-31T21:09:36+01:00" >
			<header>Article 1</header>
			<section>Lorem ipsum dolor sit amet,</section>
		</article>
	</div> 
</div>

As you can see the nb_news_wrap element 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
group_exp_images	1 or 0 (boolean)	Source-specific option to group images in expanded mode, creating a sort of a gallery after textual contents

Options List

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

$("#swift_box").lc_swift_box({
  theme: "minimal", 	// &lt;- option 1
  layout: "horizontal", // &lt;- option 2
  height: 350, 			// &lt;- option 3
  social_share: true, 	// &lt;- 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
rss2json_token	Introduced in January 2019 after YQL shut down, requires you to register and get a token from rss2json. It is mandatory to use RSS and Pinterest sources	string
youtube_key	Introduced in February 2021 because of excessive single-key usage, requires you to get a personal site key.Get the key here (video guide). It is mandatory to use Youtube source	string
only_w_images	Just keeps news with an image	boolean		false
preloader	Whether to show a preloader waiting for news to be fetched	boolean		true
theme	Swift Box theme to apply	string	Skin names: for minimal.css file, use "minimal"	"light"
layout	Main layout to use	string	horizontal, vertical	"horizontal"
height	Swift Box height in pixels	integer number		300
min_news_h	Minimum news height in pixels (value used in vertical layout)	integer number		100
min_news_w	Minimum news width in pixels (value used in horizontal layout)	integer number		150
min_horiz_w	Minimum box width (in pixels) to switch from horzontal to vertical mode, to better fit mobile screens	integer number		400
horiz_img_h	Images height (in pixels) for horizontal layout, use false to inherit CSS sizes	integer/false		false
vert_img_w	Images width (in pixels) for vertical layout, use false to inherit CSS sizes	integer/false		false
read_more_txt	Text used on shortened descriptions end	string		".."
boxed_news	Display each news into a standalone 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 + vertical layout	string	bottom, top, side	bottom
max_news	Maximum news number to fetch	integer number		6
news_per_time	How many news to show per time (value dynamically managed in relation to min_news_VAL)	integer number		3
social_share	Whether to show social share button	boolean		true
hide_elements	Remove chosen elements from boxes	array	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	[]
script_basepath	Basepath to plugin's folder. Using false the plugin will try retrieving it	string/false		(automatic)
scripts_man_added	Use true to avoid dyamic scripts inclusion. Comes handy if you concat an minify scripts	boolean		false
touchswipe	Whether to enable touchswipe support	boolean		true
lightbox	Whether to enable lightbox for images, youtube videos and soundcloud	boolean		true
oneline_title	Whether to keep title on one line, shortening it with ellipsis	boolean		false
title_behavior	Sets title's behavior on click	string	none → no action associated expand → expand news link → redirect users to news link	expand
img_behavior	Sets 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	Whether to show elapsed time instead of news date	boolean		false
html_titles	Strings arrayused to localize the plugin	array	[ "check original source", "expand text", "share", "share on Facebook", "share on Twitter", "share on Pinterest" ]
read_more_btn	Whether to replace date box with a "read more" button	boolean		false
read_more_btn_txt	Text displayed in "read more" button	string		Read more

Navigation

Name	Description	Data Type	options	Default Value
nav_arrows	Defines navigation arrows position	string / false	false, side, top_l, top_c, top_r, bottom_l, bottom_c, bottom_r	false
autoplay	Whether to autostart slideshow on box show	boolean		false
animation_time	Slideshow animation timing in millisecods	integer number		400
slideshow_time	Slideshow interval time in millisecods	integer number		6000
carousel	Whether to use the infinite carousel mode	boolean		false
pause_on_hover	Whether to pause and restart the autoplay on box hover	boolean		true
slide_all	Whether to slide every visible box per time	boolean		false

Expanded Mode

Name	Description	Data Type	options	Default Value
expandable_news	True to allow news expansion, seeing full contents	boolean		true
scroll_exp_elem	Whether to keep side-image and close button always visible on high expanded news	boolean		true
exp_main_img_pos	Sets main image position in expanded mode	string	inside → prepend it in news text side → put on left column hidden → hide it	inside
manage_exp_images	Whether to manage news images to become sizable and add lightbox support in expanded mode	boolean		true
group_exp_images	Whether to group images in expanded mode, creating a sort of a gallery after textual contents	boolean		false
exp_img_w	Images container width for expanded layout (sizes are basically width fractions)	string	1_1 → fullwidth 1_2 → half wrapper's width 1_3 → one third's wrapper width 1_4 → one fourth's wrapper width	1_2
exp_img_h	Images container height for expanded layout (in pixels). Use auto to keep image proportions	integer/string		225
exp_img_on_row	Whether to create an horizontal row with managed expanded images	boolean		false
autop_after_exp	Whether to resume autoplay after expanded news closing	boolean		false
exp_in_lightbox	Expand news contents in lightbox instead of increasing box size. NB: won't be possible to use lightbox for expanded news images	boolean		false
exp_lb_w	Percentage representing lightbox elastic width	string		90%
exp_lb_max_w	Maximum lightbox width on desktop screens	int		1200

How to 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 cloning one of them.

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

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

Finally, use it in Swift Box:

$("#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 you just have to set an high animation_time value and slideshow_time equal to zero.
The plugin is coded to recognize this setup and change its behavior, creating a continuous sliding system.

$("#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 news sources chapter, you can use also HTML in author option.
This is an example of what you can do adding a bit of code to display news categories:

$("#swift_box").lc_swift_box({
	src : [
	  {
		  type: 'rss',
		  url: 'http://www.cnbc.com/id/100727362/device/rss/rss.xml',
		  author: '<span style="background-color: #930000; color: #fff; border-radius: 3px; font-size: 80%; padding: 2px 5px;">Top News</span>'
	  },
	  {
		  type: 'rss',
		  url: 'http://www.cnbc.com/id/20910258/device/rss/rss.html',
		  author: '<span style="background-color: #016942; color: #fff; border-radius: 3px; font-size: 80%; padding: 2px 5px;">Economy</span>'
	  }
	]
});

Inline CSS has been used, but as good practice you should use classes and write targeted CSS code in the Swift Box theme file.
This is the result:

Custom date rapresentation

As explained in main options chapter, you can use also symbols and codes to compose the date format.
This includes also HTML, taking care to not use placeholders.

This is a little example of what you can achieve:

$("#swift_box").lc_swift_box({
	date_format: '<span style="position: relative; top: 7px; font-size: 22px; color: #666;">d/</span>'+
					'<span style="text-transform: uppercase; vertical-align: top; margin: 0px 0px 0px 6px;">mmm</span><br/>'+
					'<span style="float: right; margin: -2px -1px 0px 0px;">yyyy</span>',
                    
	src : [
		{
			type: 'pinterest',
			url: 'http://www.pinterest.com/envato/company-life/'
		}
	]
});

Inline CSS has been used, but as good practice you should use classes and write targeted CSS code in the Swift Box theme file.
This is the result:

Date Localization

Swift Box is ready to be translated in any language: 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. Here's the 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 placeholders list to compose dates. Examples are done using July 06 2013 - 09:05:20

Remember 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's 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>