jPortilio

JQuery plugin to create nice responsive, filterable grid of items, such as portfolio

Start Demo Download Github

1. Introduction

JPortilio is a JQuery plugin intended for creating a responsive list of filterable items. Items are filtered by tags. JPortilio can be used to creating portfolio, but not only.

JPortilio is a new project, so if you've noticed any problem, please let us know: contact@codepany.com

2. Requirements

3. Usage

3.1 Download and Installation

Firstly, download jPortilio. At least, download jportilio.js (or jportilio.min.js in minimized version) and jportilio.css (or jportilio.min.css in minimized version). You can download also theme's CSS file, but is not required. Then copy CSS and Javascript files to your project.


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

<script type="text/javascript" src="js/jportilio.js"></script>

OR


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

<script type="text/javascript" src="js/jportilio.min.js"></script>

3.2 Preparing a basic structure

JPortilio frame contains two main elements: a group of tag buttons and a grid of items.


<!-- group of tag buttons -->
<div class='jprt-buttons'>
	<button class='jprt-btn' data-jprtgrid='jprt-1' data-tag='mobile' >Mobile</button>  
	<button class='jprt-btn' data-jprtgrid='jprt-1' data-tag='ux,design' >Design</button>
</div>			
	
<!-- grid of items -->
<div id='jprt-1' class='jprt-container'>

	<!-- first item -->
	<div class='jprt-item' data-tags='mobile'>
		<div class='jprt-caption'>
			<!-- caption -->
		</div>
		<div class='jprt-content'>
			<!-- content -->
		</div>
		<div class='jprt-hover'>
			<!-- hover -->
		</div>
	</div>
	
	
	<!-- second item -->
	<div class='jprt-item' data-tags='mobile,design'>
		<!-- ... -->
	</div>
	
	
	<!-- other items -->
		
</div>    

Important in buttons:

  • data-jprtgrid in button indicates on ID of grid,
  • data-tag contains a list of tags used in filtering.

Important in grid:

  • ID of grid DOM element is used by tag buttons (in example jprt-1),
  • Each item is created in div element with class jprt-item,
  • data-tags is a list of tags assigned to specific item,
  • Each item may have 3 layers:
    • jprt-caption - is shown as caption of item,
    • jprt-hover - is shown as hover layer of item, when cursor points on item,
    • jprt-content - contains a details and may be shown on few different ways.

The content of each layer can be freely created. It means that the fields with certain sizes are ready to fill in.

3.3 Javascript initialization

JPortilio initialization:


$(function () {
  $('.jprt-container').jportilio(); 
});

jprt-container is a DOM element containing the grid of items.
JPortilio can be initialized with custom options, e.g:


$(function () {
  $('.jprt-container').jportilio({'ratio': '0.75', 'ws_lg': '4'}); 
});

More details about options can be found in section Default settings

3.4 Example 1 (without showing content yet)

Example 1 bases on the previous section, so it hasn't full functionality. Example with source code you can find here Example 1

(Fonts from example can be different than in your project. We used 'Dosis' font from google fonts.)

3.5 Content show

Content can be shown in 3 different ways. In each case we need define at least data-content-show attribute for jprt-item.

A) Cover of item

The content layer covers the whole item. Add data-content-show='cover' to specific jprt-item element:


<div id='jprt-1' class='container jprt-container'>

	<div class='jprt-item' data-tags='mobile' data-content-show='cover'>
		<div class='jprt-caption'>
			<!-- ... -->
		</div>
		<div class='jprt-content'>
			<!-- ... -->
		</div>
		<div class='jprt-hover'>
			<!-- ... -->
		</div>
		
		<!-- ... -->
		
	</div>
</div>

B) Displayed in new window

Clicking on item redirects to another page. This solution requires two data attributes:

  • data-content-show='redirect' with value redirect causes that clicking on item will redirect user,
  • data-content-url='http://www.your-url.com' stores the url of redirection.

<div id='jprt-1' class='container jprt-container'>					
					
	<div class='jprt-item' data-tags='mobile,design' data-content-show='redirect' data-content-url='http://www.jportilio.com'>
		<div class='jprt-caption'>
			<!-- ... -->
		</div>
		<div class='jprt-content'>
					
		</div>
		<div class='jprt-hover'>
			<!-- ... -->
		</div>
	</div>
					
</div>

However, if you want display any content on item and then redirect to new page, you can use method A "cover". And in content you can place a button or link to another page.

C) Expand section below of item's row

This solution will show new section below the item's row. The content section has the same width as width of grid. To use this solution, it's needed to add data attribute: data-content-show='new_section':


<div id='jprt-1' class='container jprt-container'>	

	<div class='jprt-item' data-tags='ux' data-content-show='new_section'>
		<div class='jprt-caption'>
			<!-- ... -->
		</div>
		<div class='jprt-content'>
			<!-- ... -->
		</div>
		<div class='jprt-hover'>
			<!-- ... -->
		</div>
	</div>

</div>

3.6 Example 2

Example 2 presents the three methods of showing content. Example with source code you can find here Example 2

3.7 Optional decorations

Layers (caption, hover and content) can be created as you will. However, we prepared few decorations, which you can add to your project. More details about decorations, you can find in section Decorations.

4. Default settings

Default settings can be modified by plugin initialization in Javascript part. Following initialization uses default values:


$(function () {
  $('.jprt-container').jportilio(); 
});

Modifications can be done like below:


$(function () {
  $('.jprt-container').jportilio({
							  	'ratio': '0.75',
							  	 'ws_lg': '4'
  }); 
});

The list of settings:

  • ratio - the ratio of item's width to item's height (ratio = 0.75 => height = width * 0.75),
  • ws_xs - number of items in row for small devices ( <768px )
  • ws_sm - number of items in row ( 768px < x < 992px )
  • ws_md - number of items in row ( 992px < x < 1200px )
  • ws_lg - number of items in row ( 1200px < x )
  • item_margin - margin around each item

Default values of settings:

  • ratio: 0.75
  • ws_xs: 1
  • ws_sm: 2
  • ws_md: 3
  • ws_lg: 4
  • item_margin: 0

5. Decorations

JPortilio has a few prepared decorations, which can be easily added to any project.

Some features can be cover by other layers. If something is placed in caption layer, it can be invisible through hover and content layer due to z-index. Decorations can be visible over higher layers by changing its z-index. It can be done by adding depth-over-XXX class. More details in section Helpers.

5.1 Item status

It is a small icon indicating on status of item. It's placed in top-right corner by default. Use jprt-item-status class to add item status.


<div class='jprt-caption'>
	<div class='jprt-item-status' data-toggle="tooltip" data-placement="top" title="Working...">
		<span class="glyphicon glyphicon-cog" aria-hidden="true"></span>
	</div>
</div>

The glyphicon was used in above example (glyphs can be found in Bootstrap 3), but there can be anything.

If element should be visible over hover layer, please add class depth-over-hover:


<div class='jprt-caption'>
	<div class='jprt-item-status depth-over-hover' data-toggle="tooltip" data-placement="top" title="Working...">
		<span class="glyphicon glyphicon-cog" aria-hidden="true"></span>
	</div>
</div>

5.2 Item features

It is a list of attributes, placed in top-left corner by default. The features are provided by jprt-feature class.


<div class='jprt-caption'>
	<div class='jprt-features'>
		<ul>
			<li>Android</li>
			<li>iOS</li>
		</ul>
	</div>
</div>

5.3 Caption title

Caption title can be stylized by adding class jprt-item-title.


<div class='jprt-caption'>
	<h1 class='jprt-item-title'>"Cover"</h1>
</div>

5.4 Item tags

The tags can be stylized by class jprt-item-tags.


<div class='jprt-caption'>
	<p class='jprt-item-tags'>Tag: mobile, design</p>
</div>

5.5 Arrow linking item with content

It's possible to add arrow in circle linking the item's caption with its content element placed below. This item is available only for data-content-show='new_section'.

This element consists of three components: jprt-arrow-down-border, jprt-arrow-down-back, jprt-arrow-down.


<div class='jprt-caption'>
	<div class='jprt-arrow-down-border'>
		<div class='jprt-arrow-down-back'>
			<div class='jprt-arrow-down'></div>
		</div>
	</div>
</div>

It's possible to styling element by adding additional classes to proper elements. jprt-arrow-down-border is a div element and is covered by smaller circle: jprt-arrow-down-back. So it's possible to create gradient border by adding class with background in gradient to jprt-arrow-down-border.

6. Themes

JPortilio has a few themes ready to use. You can preview them on demo page. The using theme is very simple. Download and import to project CSS file with desirable theme and add to a group of buttons and grid of items the theme's basic class.

6.1 List of themes and basic class names

  • default - it is used by default
  • dark - jprt-dark-style
  • light - jprt-light-style
  • codepany - jprt-codepany-style

6.2 Usage

Add basic class of style to the group of tag buttons and the grid of items:


<!-- group of tag buttons -->
<div id='tag-buttons' class='jprt-buttons jprt-dark-style'>
	<!-- ... -->
</div>

<!-- grid of items -->
<div id='jprt-1' class='container jprt-container jprt-dark-style'>
	<!-- ... -->
</div>

7. Helpers

Z-index

Elements placed in specific layer can be not visible through higher layers. The layer hierachy from bottom to top is following:

  • item: z-index = 2
  • caption: z-index = 2
  • hover: z-index = 6
  • content: z-index = 10

If element placed in some layer should be visible through other layers, use class depth-over-XXX, where XXX is a layer name.

For example, element placed in caption layer can be visible through hover layer if depth-over-hover class is added.