Swift Box (JS)

Documentation for v2.21 and later


Introduction

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

Need further help?

Open a ticket

Need a customization?

Ask for a quote

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.5

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({
		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).

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.

Instagram

Use specific profile page URL.
Here's the example for the Envato channel:

$("#swift_box").lc_swift_box({
  src : [
	  {
		  type: "instagram",
          url: "https://www.instagram.com/envato/"
	  }
  ]
});

Facebook pages

Please check the Zapier Feed source chapter

Twitter

Twitter API doesn't support javascript fetching, a PHP OAuth is required.
Swift Box already has everything is needed, but you must use it on a server running PHP

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

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

Enabling "use_avatar" option you can set profile's avatar as news image (if your tweet has no image)

Youtube

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"
	  }
  ]
});

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/"
	  }
  ]
});

Soundcloud

Use specific user's page URL.
Here's the example for the Anjunabeats channel:

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

Tumblr

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

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",
		  
		  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 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}

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">
		<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

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

rss2json_token : "your-token",

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

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

LCweb - Copyright © 2019 - All Rights Reserved