Our in house designers are responsible for the design of this page. It’s a little bit of Facebook’s original timeline layout – but a lot simpler and minimalist. Here is a preview of how it looks:

In a nutshell, this is what we’re going to accomplish: We’re going to use custom post types (CPT) for each entry in the Timeline. We’re grabbing them via JavaScript – using the WP Rest API as the endpoint. We’re also using Boostrap’s grid system – so our timeline behaves well in mobile.

We are going to build everything as part of the theme. For more advanced users – you can also build it as a plugin.

Note that you have to be familiar with WordPress, PHP and Front end to follow. There is no download for this – you simply have to follow along.

Ready to get started? Let’s begin:

The Back-End

First off, let’s take care of the data. We need to register the CPT with WordPress and make sure we have the right custom fields. Actually, we only have one custom field necessary – and that is the year. The year is what the timeline is sorted by (newest to oldest).

Open up functions.php in your theme. First let’s add the CPT initialization.

function registerTimelineCPT() {
        $labels = array(
            'name' => __( 'Timeline' ),
            'singular_name' => __( 'Timeline' ),
            'add_new_item'       => __( 'Add New Timeline'),
            'new_item'           => __( 'Timeline'),
            'edit_item'          => __( 'Edit Timeline'),
            'view_item'          => __( 'View Timeline'),
            'all_items'          => __( 'View All'),
        );
        register_post_type( 'timeline',
            array(
                'labels' => $labels,
                'public' => true,
                'has_archive' => false,
                'rewrite' => false,
                'publicly_queriable' => true,
                'exclude_from_search' => true,
                'show_ui' => true,
                'show_in_nav_menus' => false,
                'show_in_menu' => true,
                'show_in_admin_bar' => false,
                'menu_icon' => 'dashicons-backup',
                'show_in_rest' => true,
                'public' => false, //removes the "permalink"
                'supports' => array(
                    'title',
                    'excerpt',
                    'thumbnail',
                    'custom-fields'
                )
            )
        );
        //REMOVES COMMENTS
        remove_post_type_support( 'timeline', 'comments' );
}
add_action( 'init', 'registerTimelineCPT' );

Above, we’re simply creating our CPT called “Timeline”. We’re setting up the labels, what it supports and what it doesn’t support. Upon logging in you should see a “Timeline” in your admin area.

Now for the  custom fields – you can easily add this the default way according to WordPress. In my case, I wanted to make it easier for the users to update – so I’m using this plugin called “Meta Box“.

Our custom field is now easier to set up and become much cleaner to the users.
If you have MetaBox installed, adding the field is as simple as below. This goes into your functions.php.

function createMetaBoxes($meta_boxes ){
	$prefix = 'tl_';
	$meta_boxes[] = array(
		'id' => 'timeline_metabox',
		'title' => esc_html__( 'Other', $prefix ),
		'post_types' => array( 'timeline' ),
		'context'    => 'normal',
		'priority'   => 'low',
		'autosave'   => true,
		'fields'     => array(
			array(
				'name' => esc_html__( 'Timeline',  $prefix  ),
				'id'   => 'timeline_year',
				'label_description' => esc_html__( 'Year', $prefix ),
				'type' => 'range',
				'min'  => '1930',
				'max'  => date("Y"),
				'step' => 1,
				'std'  => date("Y"),
			)
		)
	);
	return $meta_boxes;
}
add_filter( 'rwmb_meta_boxes', 'createMetaBoxes' );

Now if you go to the Timeline page, you should see our nice range slider:

We’re also using the following default WordPress fields:

• Title
• Excerpt
• Featured Image

So as you’re following along, go ahead and add several timelines and make sure these fields are filled out.

REST Endpoint

Before we can call our Timelines through REST, we have to do some setup. Still in functions.php, add the code below:

function restProperties(){
	register_rest_field( 'timeline',
		'timeline_year',
		array(
		   'get_callback' => 'registerRestCb',
		   'update_callback' => null,
		   'schema'          => null,
		)
	 );
	function registerRestCb($object, $field_name, $request){
		return get_post_meta( $object[ 'id' ], $field_name, true );
	}
}
add_action( 'rest_api_init', 'restProperties');

So the above makes the ‘timeline’ available as and endpoint in REST. Also, we’re adding the ‘timeline_year’ as a property in the response. To find out more about WP REST API, check their documentation.

Now, when you hit the endpoint: YOURURL +’/wp-json/wp/v2/timeline?_embed&per_page=100‘, you should now see data as a JSON string. This is enough for us to work with in our Front End. Let’s go do that now.

The Front-End

Before we continue, I forgot to mention the libraries that we need to work with:

• jQuery
• Bootstrap
• Handlebars

Markup

I’m going to add the markup first (the handlebar templates), then we’ll move on to the logic.

This is the main template:

<script id="timeline-template" type="text/x-handlebars-template">
    {{#each this}}
    <div class="decade-wrap" id="decade-{{decade}}">            
    <h1>{{decade}}s</h1>
    {{#each @this}}                    
        <div class="col-lg-6 col-md-6 col-sm-6 col-xs-12 timeline-item timeline-index-{{@index}} timeline-{{leftOrRight @index}}">
            <div class="timeline-year">{{year}}</div>
            <div class="timeline-inner-wrap col-lg-8 col-md-8 col-sm-8 col-lg-12 {{pull @index}}">                
                <div class="timeline-thumbnail" style="background:url('{{img}}') no-repeat #ccc">                 
                </div> 
                <div class="timeline-title">{{title}}</div>
                <div class="timeline-excerpt">{{{excerpt}}}</div>
            </div>
        </div>
        {{{closeWrap @index}}}
    {{/each}}
    </div>
    {{/each}}
</script>

As you can see, we’re using the Bootstrap col classes to make each item responsive. We’re also using pull classes – so the alternate item will be pulled to the left.

The decades scroller:

<script id="timeline-decades-template" type="text/x-handlebars-template"> 
{{#each this}}
    <div class="timeline-decades-link-item decade-{{decade}} {{showingOrNot @index}}">
            <a href="#decade-{{decade}}">{{decade}}s</a>
    </div>
{{/each}}
</script>

Nothing fancy here, just a list of decades that is clickable.

Lastly, let’s build the wrapper:

<div class="timeline-decade-links-wrapper">
  <div class="timeline-decade-links">
       <div class="getting-items">Getting Items</div>
  </div>
</div>
<div class="timeline-wrapper"></div> 
<div class="show-more-wrap">
   <a href="#"><img src="showmore.png"></a>
</div>

The above markup simply holds the timelines together. It also has the text “Getting Items” – which acts as our loader – until our AJAX call completes. Also, we have a “show more” button – so that when clicked – the rest of the items appear in the bottom.

So the above is our HTML. Now we need JavaScript, which is described below.

Getting and Grouping the Items

This is where we pull the data from our REST endpoint, and pass it on to the handlebars templates that we’ve created. We also need additional logic – specifically grouping the decades together to build the scroller.

Let’s grab our items via .ajax():

$(document).ready(function(){
	$.ajax({
		url : '/wp-json/wp/v2/timeline?_embed&per_page=100',
		success : function(data){
                        console.log(JSON.parse(data));
			//TODO :compileTemplates();
			//TODO: bindDecadeScroller();
		},
		error : function(data){
			console.log('Error in fetching timeline...')
		}
	})
});

All things are happening inside the document ready handler. Now if you refresh your browser, you shall see our data in a parsed JSON object.

Now that we have our objects in place, remove the console.log() line that we have. We have 2 TODOS: functions that we haven’t built yet, namely compileTemplates() and bindDecadeScroller(). You can guess what both of them do.

Let’s add the first function compileTemplates():

function compileTemplates(data){
	var parsed = JSON.parse(data);
	if(parsed.length > 0){
		var obj = buildTimeline(parsed);
		var source  = $("#timeline-template").html();
		var source2 = $("#timeline-decades-template").html();
		var template = Handlebars.compile(source);
		var template2 =  Handlebars.compile(source2);
		$('.timeline-decade-links').html(template2(obj));
		$('.timeline-wrapper').html(template(obj));
	}
}

The above simply compiles the JSON data and hands it over to our templates. This alone should get our views going. But don’t refresh the browser yet. There are plenty of logic that still needs to happen.

Notice the new function in line 4 called “buildTimeline()“.  On top of that, we have Handlebar helpers that we haven’t registered – so the browser will actually throw a fit. This will be covered in the section below “View Helpers“.

Let’s build the function called buildTimeline():

function buildTimeline(data){
    function comp(a, b){
        return b - a;
    }
    function compYear(a,b) {
        if (b.year < a.year)
            return -1;
        if (b.year > a.year)
            return 1;
        return 0;
    }
    function grabImg(el){
        var src = '';
        if(el._embedded){
            if(el._embedded['wp:featuredmedia']){
                src = el._embedded['wp:featuredmedia'][0]['source_url'];
            }
        }
        return src;
    }
    $.each(data, function(){
        $(this)[0].timeline_year = parseInt($(this)[0].timeline_year);
    })
    //add decade:
    $.each(data, function(){
        var year = $(this)[0].timeline_year;
        $(this)[0].timeline_year_decade = Math.floor(year / 10) * 10;
    })
    //group decades:
    var decades = [];
    $.each(data, function(){
        decades.push($(this)[0].timeline_year_decade);
    })
    var uniqueDecades = [];
    $.each(decades, function(i, el){
        if($.inArray(el, uniqueDecades) === -1) uniqueDecades.push(el);
    });
    decades = uniqueDecades.sort(comp);
    var clean = Array();
    var final = Array();
    $.each(data, function(i, el){
        var obj = {};
        obj.id = el.id;
        obj.img = grabImg(el);
        obj.title = el.title.rendered;
        obj.excerpt = el.excerpt.rendered;
        obj.year = el.timeline_year;
        obj.year_decade = el.timeline_year_decade;
        clean.push(obj);
    });
    clean = clean.sort(compYear);
    $.each(decades,function(i,el){
        var key = i;
        final[key] = Array();
        $.each(clean,function(x,xel){
            final[key]['decade'] = el;
            if(xel.year_decade == el){
                final[key].push(xel);
            }
        })
    })
    return final;
}

Okay this is the meat of our logic. We’re trying to grab all of the years in our timelines. And from each of those years, we need to calculate the decade, take out the duplicates and stuff them back to a final array, grouped by decade.

In lines 31-34 is where we calculate the decade, then stuffing it to a new property called “timeline_year_decade“. Then we’re doing a couple more loops to remove duplicates, sort and create a clean “decades” array – which we need for our final loop in lines 66-75.

Refresh your browser and see what our “final” array looks like.

Now we our compileTemplates() is done, let’s go and register our helpers and do some CSS.

View Helpers

Now we have to do add more scripting to determine additional classes that makes our timeline look the way it does.

In case you haven’t noticed, our templates are sprinkled with helpers for handlebars. Let’s register those helpers now.

Handlebars.registerHelper('leftOrRight', function(index) {
	return index %2 == 0 ? 'left' : 'right';
});
Handlebars.registerHelper('closeWrap', function(index) {
   return (index+1) %2 == 0 ? '<div class="clearfix"></div>' : '';
});
Handlebars.registerHelper('pull', function(index) {
   return index %2 == 0 ? '' : 'col-lg-push-4 col-md-push-4 col-sm-push-4';
});
Handlebars.registerHelper('showingOrNot', function(index) {
	if(index == 0){
		return 'showing';
	}
});

The above are view helpers – that cooperates with the HTML templates that we just built. For instance, the “leftOrRight” helper – determines if a class of “left” or “right” is to be added. Below are the images for that:

Left Line:

Right Line:

Arrow up:

Vertical Line:

The Styles

Finally, the styles that make our timeline look good. I’m not going to walk through what each style does. I’m just going to add this as a reference for you to plugin. You might have a different style depending on your preference.

.timeline-wrapper {
    position:relative;
    z-index: 99;
}
.decade-wrap {
    overflow:hidden;
    clear:both;
    display:block;
    background:url('vertical_line.png') #fff repeat-y;
    background-position-x: center;
}
.decade-wrap:first-child {
    padding-top: 40px;
}
.decade-wrap:last-child{
    margin-bottom: 75px;
}
.decade-wrap h1 {
    text-align: center;
    background:#fff;
    padding:25px 0 35px;
    font-size:45px;
    color: #0077C8;
}
.timeline-thumbnail {
    background-position-x: center !important;
    background-position-y: center !important;
    background-size: cover !important;
    height:319px;
}
.timeline-item,
.timeline-inner-wrap {
    padding-left:0;
    padding-right:0;
}
.timeline-left {
    background:url('left_line.png') no-repeat right center;
    margin-left: 8px;
}
.timeline-right {
     margin-top: 100px;
    background:url('right_line.png') no-repeat left center;
    margin-left: -15px;
}
.timeline-inner-wrap {
    padding-top: 25px;
}
.timeline-year {
    position: absolute;
    top: 39%;
    font-size:30px;
    font-weight: 500;
    color: #0077C8;
}
.timeline-right .timeline-year {
    padding-left: 35px;
}
.timeline-left .timeline-year {
    right:0;
    padding-right: 34px;
}
.timeline-title {
    font-size: 19px;
    font-weight: 500;
    color: #000;
    padding-top: 15px;
    padding-bottom: 10px;
}
.timeline-decade-links {
    background:#ececec;
    min-height: 60px;
    display: flex;
}
.timeline-decades-link-item {
    width: 100px;
    margin: 0 auto;
    text-align: center;
    font-size: 18px;
    padding-top: 18px;
    height: 60px;
}
.timeline-decades-link-item a:hover,
.timeline-decades-link-item a:focus{
    text-decoration:none;
}
.timeline-decades-link-item.showing {
    background:url('arrow-up.png') transparent no-repeat center bottom;
}
.timeline-decade-links-wrapper {
    overflow: hidden;
}
.timeline-decade-links-wrapper.fixed {
    position: fixed;
    top: 0px;
    z-index: 110;
    left:0;
    width:100%;
}
.admin-bar .timeline-decade-links-wrapper.fixed {
    top:32px;
}
@media(max-width:1199px){
    .timeline-thumbnail {
        height:253px;
    }
    .timeline-item {
        background-position-y: 33%;
    }
    .timeline-year{
        top: 21%;
    }
}
@media(max-width:991px){
    .timeline-thumbnail {
        height:190px;
    }
    .timeline-item {
        background-position-y: 28%;
    }
    .timeline-year{
        top: 18%;
        font-size: 23px;
    }
    .decade-wrap h1 {
        padding: 14px 0 24px;
        font-size: 31px;
    }
}
@media(max-width:768px){
    .timeline-thumbnail {
        height:354px;
        width:410px;
    }
    .decade-wrap {
        background:none;
    }
    .decade-wrap:first-child {
        padding-top:0;
    }
    .decade-wrap h1 {
        padding: 0px 0px 0px 0px;
    }
    .timeline-right {
        margin-top: 0;
    }
    .timeline-item {
        background:#fff;
        margin-left: 0 !important;
        margin-right:0 !important;
    }
    .timeline-year {
        position: relative;
        padding-left: 0 !important;
        padding-right:0 !important;
    }
    .timeline-decade-links {
        display: none;
    }
}
@media(max-width:500px){
    .timeline-thumbnail {
        height:302px;
        width:auto;
    }
}
@media(max-width:375px){
    .timeline-thumbnail {
        height:242px;
    }
}

 
After our helpers apply the classes, our CSS and images in place – Bootstrap will take care of the rest. If you refresh, you should see your timeline. Inspect and you see our classes applied.

Finally, let’s go ahead and bind that scroller:

function bindDecadeScroller(){
	 $('.timeline-decades-link-item a').on('click',function(){
		var id = $(this).attr('href');
		var offset = ($(id).offset().top - 150) ;
		$('html, body').stop().animate({
			scrollTop: offset
		}, 1000);
		return false;
	})
}

This should have a smooth animating effect when you click on the decades on the scroller. Note that our timelines are grouped by decades, encapsulated in a DIV with the ID – of the decade. So when our scroller is cicked – it has the ID of the DIV in it’s href attribute.

So technically, even without our animation – it will know where to focus naturally.

We’re using .animate() to make that jump smoother. Check jQuery’s documentation on .animate for more information.

Conclusion

And there you have it. We’ve just build a pretty cool timeline – grouped by decades, with a scroller that focuses on the decade when clicked. This is also responsive – so it looks real good in a mobile device.

Note that this is a pretty basic timeline – which you can greatly enhance by adding other things. For example, you can add a modal for more details for each of the item. Or even multiple images per item – one that you can scroll left to right like a slideshow. There are many possibilities.

For the live page, check out the Parsons timeline page. I hope you enjoyed this tutorial. Leave your comments below.

The post How to Build a Company Timeline using Bootstrap and WordPess REST API appeared first on Michael Soriano.

So all subsequent navigation will be done in the client side. This results to a smoother and better user experience.

View in Github

I wanted to build several themes, but would like a base theme to start with. Enter wp-vue-starter. A starter theme that is built on a popular framework called Vue, and WP’s REST API in the background.

Note that since all of the rendering is done in the client, SEO is not going to be available. But for sites that SEO will not matter, I think this is a good choice. Let me explain the theme design and structure and maybe you can use the theme in your next project.

Traditional Blog Design

If you do a search on WordPress Theme and Vue, there have been many attempts on it. This however, is slightly different. First of all, is the design. It uses the traditional blog design that many of us WordPress users have grown to like.

Here is a screenshot of the homepage:

As you can see, it has a “static” page that is called “home”. There is a big area (jumbotron) for your carousel or hero image, while the latest posts are directly below it. The CSS framework is Bootstrap (version 4). So editing the grid and elements is familiar to many. A sidebar is built in – which is pretty standard to most sites.

What is a site without “Search”. That of course is also included. A search form is in the header, and is a component called “search-form”. So this component can be used in the sidebar, footer – where ever you want the form to be.

The search results look look like below:

Also notice the paging. The paging system is inside a component called “the-loop”. For many of us theme developers, the “Loop” is the basis of a template inside a theme. So I wanted to keep the same concept here. So you will see the “archive” and “search” is basically using “the-loop” component, because it shares the same properties.

Single, Page and Comments Form

The “single” post page is also a Vue component. This accessed using the slug:

/post/post-name

The “page” page is another component, and can be accessed by:

/page/page-name

So the urls are not exactly as the traditional WordPress urls, but is quite clean in my opinion. So you need to update your permalink structure in WordPress to /post/%postname%/:

So you can still access most of the admin functionality such as viewing pages, posts and previewing.

Below is an example of the single page.

In addition, to the content – is the comments. This theme is built with the comment responses and the form in it. It is pretty basic in design – very “Bootstrapy”. But again, this is a starter theme – so what do you expect.

Theme Structure

So if you’re going to use wp-vue-starter, chances are, you’re going to edit it. So let’s go over the structure briefly. Note that you need to know WordPress and Vue a little bit to dive into this.
Everything goes in through index.php.

This is where your entire HTML wrapper is. From the opening HTML tag, header and footer is inside here. You will also see that all of the templates are included in this page as “template” tags.

This is also where the DIV called “app” is – so Vue is inserting the entire application into this DIV. The styles.css in the root is nothing but a marker. It just tells WordPress about the theme name and such.

There are actually no styles in here. Instead, the styles go into /css/dist/main.css The main.js is where all of the JavaScript logic is. This is where the components are declared, all of the methods as well the routing. If you want to change Vue or JS logic, this is the right file. Below shows a sample of the route mapping system.

Normal WordPress functions go inside the functions.php. This is where you will see modifying REST responses and such. Note that by default, the theme is allowing anonymous comments – so you might want to change this.

Lastly, inside the “templates” folder – are the components. They’re PHP files, but there’s no PHP logic in them. I just left it like that for consistency – and just in case you want to add some PHP in it, you can. The files resemble a traditional WordPress theme. Like 404, page, single, search etc.

Lastly, the “partials” are the files with the underscore prefix. So this the _header, _footer, _sidebar. Note that this “header” is the html header – not the “<head>”.

Installation

Installation is the same as any other theme. Simply upload and activate (don’t forget to update the permalinks). You can also use SASS – for CSS preprocessing. This is included by default, and is the best way to edit CSS. The source files are inside /src and output is /dist.

Gulp is the default build tool, so you can run

npm i -D gulp gulp-sass gulp-sourcemaps gulp-clean-css

For the SASS compiler and CSS clean up.

The theme is under MIT license, and is available in GithHub. I will be adding more features such as additional templates etc., so stay tuned.

The post New WordPress Starter Theme using VueJS appeared first on Michael Soriano.

Note that this will require the following files:

• jquery.min.js
• bootstrap.min.js
• handlebars.min.js
• moment.min.js
• editor.js
• editor.css
• bootstrap.min.css
• font-awesome.min.css

The plugin already includes the above files via CDN.

View in Github

We are building “Tab Containers“. Basically, content that is shown in different tabs in a page. The entire CRUD interface also comes with it – so we’ll be able to add, edit and delete tab content and items, all in one page (without refreshing).

Why is this Useful?

Well there really is no way to achieve this in SharePoint. If you want to add Tabs inside an SP page, you would have to paste the whole code inside their editor. But updating this is quite cumbersome to most users.

This solution provides you with a nice interface to manage your tab content, while the data is stored in an SP list. The good thing about this is, you can use multiple apps and utilize just one list. So if you convert this into a webpart or an app – you simply need one list per site to make it work.

Ready to get started? Also, I’m only going to discuss the meat of the logic. You will need some basic JavaScript and SharePoint to follow and complete this tutorial.

Create the List

The data for our application will be stored in a custom list. The list will basically contain four columns: 1) Title: which is the default title field, 2) content which is a Rich Text type 3) tab-order a single line text value 4) webpart-id – this will be the identifier for our webpart (in case you want multiple webparts in the site).

The title column will hold tab title, content is the contents of the tab, tab order is for ordering the tabs from left to right. You can go ahead and fill it out with dummy data for now, so we can go ahead and fetch the data for our front end. Note that that I have the list template also included in the Github page.

Fetch the Items

We are going to use a slight variation of the “Revealing Module” pattern to construct our code. This is especially useful when you are expecting your code to be reused multiple times in a page. In our case, users might want multiple of these web parts in a page, so a “modularized” approach is needed.

var SpTabs = function(){
   //ENTER REST OF CODE HERE
return {
    init : init,
    getContent : getContent
  }
}

As you can see, we are returning two public functions from our “SpTabs” object. The “init()” method will make the object unique per instance, while the “getContent()” will fetch the items for our view. Let’s build our init() function right below:

var init = function(obj){
    setListName(obj.listName);
    setWebPartId(obj.webPartId);
    setListItemEntityTypeFullName();
    checkPermissions();
}

Inside our “init()”, we have some setters. It simply sets our module up for execution. The setter functions are pretty self explanatory – and you can simply investigate what each of them does in the source code. Let’s continue getting our items:

var getContent = function(obj){
    var endpoint = "/_api/web/lists/getbytitle('"+listName+"')/Items?";
    endpoint = _spPageContextInfo.webAbsoluteUrl + endpoint + '$orderby=tab_x002d_order asc';
    endpoint += "&$filter=(webpart_x002d_id eq '"+webPartId+"')";
    var ajax = $.ajax({
      url: endpoint,
      method: "GET",
      headers: { "Accept": "application/json; odata=verbose" },
      success : function(data){
        items = data.d.results;
        buildTabsHtml();
        buildTabsContentHtml();
      },
      error : function(data){
        console.log(data);
      }
    });
    return ajax;
  }

This is the AJAX call that goes into our API to fetch our items. As you can see, we are returning the variable “ajax” from the getContent() function, in cases where we want to add additional stuff once the response is received. But the default behavior is inside the “success” method of jQuery’s $.ajax().

Note the two methods buildTabsHtml() and buildTabsContentHtml(), and our results are in our global var “items”. So we’re ready to build some output.

Output with Handlebars

Let’s create our Handlebars templates so we can use it to produce our content. In case you haven’t used it, Handlebars is a minimal template language for JavaScript. It just makes life easier. Note that we have to include our handlebars source to make it work. Also, we are using Bootstrap for our tab styles. So you have to include that in your source as well.

The code that will make this work is inside our two methods buildTabsHtml() and buildTabsContentHtml(). Let’s go ahead and build that now:

function buildTabsHtml(){
    var source = $("#tabs-navigation-template").html();
    var template = Handlebars.compile(source);
    $(getId() + '.tabs-navigation').html(template(items));
    //atach handlers
    $(getId()+'.tabs-navigation li a').on('click',function(){
      $(getId()+'.tabs-navigation li').removeClass('active');
      $(this).closest('li').addClass('active');
      var id = $(this).attr('data-id');
      $(getId()+'.tab-item').addClass('hidden');
      $(getId()+'div.tab-item[data-id="'+id+'"]').removeClass('hidden');
      if(id === 'addNew'){
        addNewForm();
      }
    })
  }

The above will output the content of our tabs. It also attaches the handlers to the tab navigation elements. Next up is the buildTabsContentHtml() method:

function buildTabsContentHtml(){
    var source = $("#tabs-content-template").html();
    var template = Handlebars.compile(source);
    Handlebars.registerPartial("tabForm", $("#tabs-content-form-template").html());
    $(getId() + '.tabs-content').html(template(items));
    $.each(items,function(i,item){
      $(getId()+'[data-id="'+item.Id+'"] .editable-content').Editor(EditorOptions);
      $(getId()+'[data-id="'+item.Id+'"] .Editor-editor').html(item.content);
    })
    $(getId()+'.save-changes').on('click',function(){
      var id =$(this).closest('.tab-item').attr('data-id');
      if(validateFields(id)){
        $(this).addClass('fetching').html(' Saving...');
        $(getId()+'.editmode').css({'opacity':'.4'});
        setTimeout(function(){
          var ajax = submitChanges(id);
          ajax.done(function(data, xhr){
              var ajax2 = getContent();
              ajax2.done(function(){
                $(getId()+'.tabs-navigation li a[data-id="'+id+'"]').trigger('click');
                addButton();
              });
          });
        },1000);
      }else{
        showErrorMessage(id);
      }
      return false;
    })

Now things got a bit hairy. First you’ll notice our handlebars compile – which is normal, but note the “registerPartial()” method. This means that we’re adding another handlebars template into our existing template. This is the form that handles our inline editing. I’m not going to post the code on here, instead you can see the #tabs-content-form-template from our text file – which simply contains a few input forms for our app.

Why use partials within templates?

This is another powerful feature of handlebars. This allows for more re-usability and “modularity” for your applications. In other words, we write once and re-use multiple times. In our case, the form can be reused multiple times across our application – in “edit” and “new” mode. This will become evident as you write along.

We’re also using a lightweight WYSWG editor called “Line Control“. Since we’re already using Bootstrap and FontAwesome, it just makes sense that we use a plugin that requires the same libraries. So this is what’s happening on lines 8-9 above: “.Editor(EditorOptions)”, where “EditorOptions” is declared on top of of our file as an array.

Insert, Update and Delete

Finally, we attach our “Save” and “Delete” buttons to do a couple of REST calls to our server when clicked. First our “Save” button is connected to our “submitChanges(id)” method (which takes care of both “edits” and “inserts”), while the next call is to “getContent()” – which is our main function to grab the tab items.

The “Delete” will also consist of two main REST calls, which is to delete and fetch the records. Our “deleteRecord()” function is shown below:

function deleteRecord(tab){
    var ajax = $.ajax({
       url: tab.__metadata.uri,
       type: "POST",
       headers: {
           "Accept": "application/json;odata=verbose",
           "X-RequestDigest": $("#__REQUESTDIGEST").val(),
           "X-HTTP-Method": "DELETE",
           "If-Match": tab.__metadata.etag
       },
       success: function (data) {
          console.log('record has been deleted');
       },
       error: function (data) {
          console.log('there was a problem with deleting the record');
       }
   });
   return ajax;
  }

While our “submitChanges()” method looks like so:

function submitChanges(id){
      var item = {
        "__metadata": { "type": ListItemEntityTypeFullName },
        "Title" :   $(getId()+'[data-id="'+id+'"] input[name="title"]').val(),
        "content" : $(getId()+'[data-id="'+id+'"] .Editor-editor').html(),
        "tab_x002d_order" : $(getId()+'[data-id="'+id+'"] input[name="tab-order"]').val()
      };
      if(id === 'addNew'){
        item.webpart_x002d_id = webPartId;
        var endpoint = "/_api/web/lists/getbytitle('" + listName + "')/items";
        ajax = $.ajax({
           url: _spPageContextInfo.webAbsoluteUrl + endpoint,
           type: "POST",
           contentType: "application/json;odata=verbose",
           data: JSON.stringify(item),
           headers: {
               "Accept": "application/json;odata=verbose",
               "X-RequestDigest": $("#__REQUESTDIGEST").val()
           },
           error: function (data) {
              console.log(data);
           }
       });
       return ajax;
      } //end addNew;
      var tabItem = findItem(id);
      ajax = $.ajax({
         url: tabItem.__metadata.uri,
         type: "POST",
         contentType: "application/json;odata=verbose",
         data: JSON.stringify(item),
         headers: {
             "Accept": "application/json;odata=verbose",
             "X-RequestDigest": $("#__REQUESTDIGEST").val(),
             "X-HTTP-Method": "MERGE",
             "If-Match": tabItem.__metadata.etag
         },
         error: function (data) {
            console.log(data);
         }
     });
     return ajax;
  }

Note that all of the REST calls all look similar, with a select few nodes that changes. First you’ll notice the “X-HTTP-Method” for edits is “MERGE” and “DELETE” for deleting. The rest are pretty much SharePoint REST API requirements – which you can find more on this page. Our “item” object is also mapped to the names of the list columns that we have. Depending on your list – you may need to modify this area as well.

In our UI, note the placement of our buttons and our form:

Lastly, you notice a couple of helper functions “getId()” and “findItem()”. The getId() simply returns our current div – with the “#” and a space as a string (or the CSS selector for the current div), while our findItem() loops through our global items object and returns the current item.

Moving forward, let’s look at a couple of important internal methods which includes our validation and error messaging mechanism.

Form Validation

Since we’re entering our data into our SharePoint lists through client side, we can implement a validation method using JavaScript as well. The cool thing about SP’s REST API has it’s own validation in the server side so all we have to worry about is the user experience.

function validateFields(id){
    errors = [];
    $('.error').remove();
    var title = $(getId()+'[data-id="'+id+'"] input[name="title"]');
    var content = $(getId()+'[data-id="'+id+'"] .Editor-editor');
    var tabOrder = $(getId()+'[data-id="'+id+'"] input[name="tab-order"]');
    if(title.val() == ''){
      var obj = {};
      obj.field = 'title';
      obj.message = 'Title cannot be empty'
      errors.push(obj);
    }
    if(content.html() == ''){
      var obj = {};
      obj.field = 'content';
      obj.message = 'Content cannot be empty'
      errors.push(obj);
    }
    if(tabOrder.val() == ''){
      var obj = {};
      obj.field = 'tab-order';
      obj.message = 'Tab order cannot be empty'
      errors.push(obj);
    }
    if(errors.length > 0){
      return false;
    }
    return true;
  }

Our very simple validation code is above. Note that this happens every time that “submit” button is clicked. So it simply goes through the fields – check for empty and puts the errors in an array. I’m not checking for anything else like valid data etc – and feel free to add your own rules. Simply keep pushing the error messages into our array when invalid. Our messaging is handled in the code below:

function showErrorMessage(id){
    $.each(errors,function(i,er){
      var field = '';
      if(er.field === 'content'){
        field = $(getId()+'[data-id="'+id+'"] .Editor-container');
      }else{
        field = $(getId()+'[data-id="'+id+'"] input[name="'+er.field+'"]');
      }

[the code above has been truncated due to an error w syntax highlighter… sorry]

The following screenshot shows our validation code in action. Error messaging is placed underneath each label and at the same time. This way, users can see where they had made an error and fix. Remember to add your own rules as necessary.

Checking Permissions

Finally, since we’re not using the regular SharePoint process in updating a page with tabs, we need to come up with our own. See, the entity we’re updating is not the current page – but a list. So we need to check if the current user has permission to edit the list – and give them access to our newly created UI.
I found this great article on how to effectively do this – since Microsoft’s documentation is a bit vague.

We’re using the “effectiveBasePermissions” REST endpoint along with SP.BasePermissions() class – which we need from SP.ClientContext object. Yes, it’s a bit of a mess so simply check the code below:

function checkPermissions() {
    SP.SOD.executeFunc('sp.js', 'SP.ClientContext', function () {
      var call = jQuery.ajax({
          url: _spPageContextInfo.webAbsoluteUrl +
              "/_api/Web/lists/getbytitle('"+listName+"')/effectiveBasePermissions",
          type: "GET",
          dataType: "json",
          headers: {
              Accept: "application/json;odata=verbose"
          }
      });
      call.done(function (data, textStatus, jqXHR) {
          var permissions = new SP.BasePermissions();
          permissions.initPropertiesFromJson(data.d.EffectiveBasePermissions);
          var permLevels = [];
          for(var permLevelName in SP.PermissionKind.prototype) {
              if (SP.PermissionKind.hasOwnProperty(permLevelName)) {
                  var permLevel = SP.PermissionKind.parse(permLevelName);
                  if(permissions.has(permLevel)){
                        permLevels.push(permLevelName);
                  }
              }
          }
          // console.log(permLevels);
          if($.inArray('editListItems',permLevels) != -1){
            userCanEdit = true;
            addButton();
          }else{
            console.log('You dont have "editListItems" permissions on '+ listName);
          }
      });  //end done
    });
  }

We’re still using jQuery’s ajax to get information, though it’s wrapped inside a “SP.SOD.executeFunc()” method – which is Microsoft’s way of loading and executing internal scripts. What we get back is an array we’re calling “permLevels” This array contains all the permissions a user has against our list.

We’re simply looking for the “editListItems” – and if found, we’re show the button and let the user edit.

Final Steps

Our code is now complete. Note that there is not a single line of .NET code above – it’s all JavaScript, HTML and CSS. All server interactions are done through the REST API. This code can be applied whichever way you want to implement – may it be a custom web part, an app part or simply add the code to a Content Editor.

Remember to update the initialize settings like below: The important part is the “webPartId” and “listName” parameters – which connects the plugin to the data you need.

Once that’s done, simply reload the page and you should see your SPA in action. Note that the code editor I used is very basic – so you might need to go to the list itself when updating content.

This editor was mostly designed for quick updates to your content.

Remember, the purpose of this article was really to expose you to the inner workings of REST and how to build a single page application right inside SharePoint with existing open technologies such as jQuery, Handlebars and Bootstrap.

Hope you enjoy this piece. Let me know your comments below.

The post Build a SharePoint Single-Page App using nothing but Front-End Code appeared first on Michael Soriano.

Note that this will require the following files:

• bootstrap.css
• magnific-popup.css
• jquery-1.12.0.min.js
• jquery.magnific-popup.min.js

The plugin already includes the above files via CDN. The Plugin JavaScript and CSS is also included via RawGit – so changes may affect your working files.

View in Github

Today, let’s look at something pretty simple. Let’s build a photo gallery using SharePoint Picture library as the backend, together with Handlebars.js – a good Javascript templating system. With this knowledge, you will gain good understanding on how to select items with SharePoint’s REST API, which I happen to have a post on.

Ready to get started? Roll up your sleeves and let’s write some code. Note that I will not go over the entire code base in this tutorial – just the meat of the logic.

Setup the Gallery

First we need to make sure we have a gallery to connect to. In SharePoint, you do this by going to “View All Site Content” and adding a new Picture Library. Note that for this demo I’m using SharePoint 2010 – I believe in newer versions you have to “Add an App” > “Photo Library“.

Be sure to note the name of your library:

Upload some images to your newly created library. Now we can continue and pull our images in the front end.

The Javascript

Create a Javasript file and name it sp-gallery.js. You can place it inside any SharePoint document library – and simply map to it using Windows Explorer so you can write to it just like you would as if it was a local file.

Let’s setup the wrapper for our gallery. We’re using the “Revealing Module” pattern so we can have methods that are public and private, as well as we keep our logic real tidy. We’re adding private variables inside our class so we can use it all over our code.

var gallery = function(list){
  var webUrl = _spPageContextInfo.webAbsoluteUrl;
  var listName = list;
  var limit = 20;
  var skip = 0;
  var total = 0;
}

Get the List Count

Our first method is to grab the number of photos in our library. This is important so we can decide whether to show our “show more” button or not. Note the use our our “webUrl” and “listName” variables in our method. Add this code inside our gallery wrapper. This method is internal, so we create a function declaration:

function getListCount(webUrl,listName) {
    var url = webUrl + "/_vti_bin/listdata.svc/" + listName + '/$count';
    var ajax = $.ajax({
        url: url,
        method: "GET",
        headers: { "Accept": "application/json;odata=verbose,text/plain" },
        error: function (data) {
          console.log('error in fetching list count');
          console.log(data.responseJSON.error);
        }
    });
    return ajax;
}

The above will return a “promise” object that we can use to manipulate later on. In the case above, it’s simply a number.

Get the Gallery Items

This method is the call to grab our list items. Again, we’re using jQuery’s “Ajax” method, returning a promise object.

function getListItems(webUrl,listName, itemId) {
    var url = webUrl + "/_vti_bin/listdata.svc/" + listName;
    if(itemId !== null){
      url += "(" + itemId + ")";
    }
    url += '?$top='+limit+'&$skip='+skip;
    var ajax = $.ajax({
        url: url,
        method: "GET",
        headers: { "Accept": "application/json; odata=verbose" },
        error: function (data) {
          console.log(data.responseJSON.error);
        }
    });
    return ajax;
  }

Compile with HandleBars

This method is taking the data that is returned from our ajax promise above, and compiling it with handlbars. We haven’t built our HTML yet – which contains the actual handebars template. Note that this is a public function, so we’re creating the function as a “function expression”:

var buildGallery = function(data){
      var source   = $("#photogallery").html();
      var template = Handlebars.compile(source);
      $('.photo-gallery-wrap').append(template(data));
      $('.popup').magnificPopup({
          type: 'image',
          gallery:{
            preload: [0,5],
            enabled:true
          },
          removalDelay: 300,
          mainClass: 'mfp-fade'
      });
  }

Also note that I’ve added a “popup” functionality which we’ve instantiated in the code above. We’re using magnificpopup.js for this awesome feature.

The “Show More” button

We’re only loading a certain subset of photos in our gallery. We will have a button in the bottom of our images that when clicked, will do another fetch to our list and add them below. Again, this is public, so it’s a “function expression”.

var showmore = function (){
      $('#showmore').addClass('fetching').html('Loading images...');
      skip = skip+limit;
      var ajax2 = getListItems(webUrl,listName, null);
      ajax2.done(function(data){
        buildGallery(data);
        $('#showmore').removeClass('fetching').html('Show More');
        if($('.thumbnail-wrap').length >= total){
            $('#showmore').hide();
        }
      });
      return false;
  }

This sort of acts like an “infinite scroll” functionality – but with a button. I’m not particularly fond of that automatic loading.

Initializing the Gallery

Now that our methods are in place, it is time to tie them all together and returning them so we can call them outside of our class. We do this by creating an “init” function.

var gallery = function(list){
//our private vars here...
var init = function(){
      var ajax1 = getListCount(webUrl,listName);
      var ajax2 = getListItems(webUrl,listName, null);
      ajax1.done(function(data){
        total = data;
        if(total <= limit){
          $('#showmore').hide();
        }
      });
      ajax2.done(function(data){
        buildGallery(data);
      });
  }
//the rest of the methods here...
//below returns our public methods for use:
 return {
    init : init,
    showmore : showmore,
    buildGallery : buildGallery
  }

Notice that we are only returning the public functions above. So we are keeping our variables and private functions inaccessible from the outside world. Let’s move on to our helpers:

HandleBar Helpers

These methods doesn’t have to be our gallery code. This can live outside, so it can be accessed by Handlebars. The code is namespaced using the Handlebars object. I’ll explain what the do below:

Handlebars.registerHelper('findGroup', function(data) {
    var remove = _spPageContextInfo.webServerRelativeUrl;
    var str = data.Path;
    return str.replace(remove+'/','');
});
Handlebars.registerHelper('imgSrc', function(data) {
    var url = _spPageContextInfo.siteAbsoluteUrl;
    url += data.Path;
    url += '/' + data.Name
    return url;
});
Handlebars.registerHelper('imgSrcThumb', function(data) {
    var thumb = data.Name;
    thumb = thumb.replace('.jpg', '_jpg.jpg');
    var url = _spPageContextInfo.siteAbsoluteUrl;
    url += data.Path;
    url += '/_t/' + thumb;
    return url;
});

We will use a “findGroup” helper inside our templates so we can “group” our photos together. This is what our “Magnificpopup” plugin requires – so when you click “next” or “previous” – it knows which photo to show.

The “imgSrc” helper simply returns the source of the images, while the “imgSrcThumb” returns the thumbnail path. Note that this helper only supports jpegs at the moment.

The CSS

We are simply displaying the thumbnails in a grid fashion, so our styles are quite basic. I’m using this inside a Bootstrap wrapper, so you can see the “.col” classes in our HTML later. Create a file and name it sp-gallery.css and add the code below:

.photo-gallery-wrap {
  overflow: hidden;
  margin-right: -30px;
}
.thumbnail {
  display: inline-block;
  width: 100%;
  height: 100px;
  background-position: center center !important;
  text-indent: -9999px;
}
.thumbnailHidden {
  display:none;
}
.showMoreWrap {
  clear:both;
  display:block;
}
#showmore {
  color:#fff;
}
#showmore.fetching {
  background:#AAD3AA;
  border:#9AC39A;
}
.thumbnail-wrap {
  margin-bottom: 25px;
}
.thumbnail-wrap.col-lg-3 {
  padding-left:0;
  padding-right: 30px;
}
@media(max-width:387px){
  .thumbnail-wrap.col-lg-3 {
    padding-right: 15px;
  }
  .col-xxs-6 {
    width:50%;
  }
  #showmore {
    display:block;
  }
}
@media(max-width:240px){
  .col-xxxs-12 {
    width:100%;
  }
}
/* overlay at start */
.mfp-fade.mfp-bg {
  opacity: 0;
  -webkit-transition: all 0.15s ease-out;
  -moz-transition: all 0.15s ease-out;
  transition: all 0.15s ease-out;
}
/* overlay animate in */
.mfp-fade.mfp-bg.mfp-ready {
  opacity: 0.8;
}
/* overlay animate out */
.mfp-fade.mfp-bg.mfp-removing {
  opacity: 0;
}
/* content at start */
.mfp-fade.mfp-wrap .mfp-content {
  opacity: 0;
  -webkit-transition: all 0.15s ease-out;
  -moz-transition: all 0.15s ease-out;
  transition: all 0.15s ease-out;
}
/* content animate it */
.mfp-fade.mfp-wrap.mfp-ready .mfp-content {
  opacity: 1;
}
/* content animate out */
.mfp-fade.mfp-wrap.mfp-removing .mfp-content {
  opacity: 0;
}

I’ve also added extra “col” classes for my own grid styles when the viewport is decreased. Also notice the .mfp classes are necessary for our magnific popup to work “magnificently”.

The HTML

Finally, this is the file that we add to any page of our SharePoint site. Create a text file – name it “sp-gallery.txt” and add the code below:

<script src="https://code.jquery.com/jquery-1.12.0.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/handlebars.js/4.0.5/handlebars.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/magnific-popup.js/1.0.1/jquery.magnific-popup.min.js"></script>
<script src="ADD-YOUR-PATH-HERE/sp-gallery.js"></script>
<script>
$(document).ready(function(){
  var photos = gallery('TestPhotoLib'); //change to your document library name
  photos.init();
  $('#showmore').on('click', photos.showmore);
})
</script>
<div class="photo-gallery-wrap"></div>
<div class="showMoreWrap">
<a id="showmore" class="btn btn-sm btn-success" href="#">Show More</a></div>

 
The above contains the references to the files we need.

We went ahead and create our gallery and pass in the name of our Photo Gallery above. We then initialize and add the “showmore” handler when our button is clicked.

Add our Handlebars template to the text file:

<script id="photogallery" type="text/x-handlebars-template">
{{#each d}}
<div class="col-lg-3 col-md-3 col-sm-3 col-xs-4 col-xxs-6 col-xxxs-12 thumbnail-wrap">
  <a href="{{imgSrc this}}" group="{{findGroup this}}" class="thumbnail popup" style="background:url('{{imgSrcThumb this}}');" >
    {{Name}}
  </a>
</div>
{{/each}}
</script>

 
The above template is what we need for our gallery to work. This code represents each tile that we will produce in our gallery.

Save this text file (along with the .js and .css) and add it to any SharePoint page. Add a Content Editor WebPart, and add a link to an external file – to our .txt file.

I usually edit the webpart to “NOT” show the chrome.

Final Result

Save the page and if everything works well, you should see something like below:

A simple photo gallery with popup and paging functionality. It surely looks better than the “out of the box” photo gallery that SP provides. Furthermore, you have complete ability to change the look as much as you want.

But the real value is the introductory lesson to working with SharePoint’s REST api. Be sure to stay tuned for more stuff like this.

Leave your comments below.

The post Build a Better Photo Gallery for SharePoint using REST and Handlebars appeared first on Michael Soriano.

So plenty of room for improvement here. Now we can basically recreate SharePoint’s front end: entire new CRUD interfaces and such. And the base of it all – is its REST API.
It is important to recognize that SharePoint REST API is using OData, which is a widely used convention when in comes to RESTful web services. You can learn more about the syntax from their website.
For this post I would like to cover Selecting Items.
Note that I prefer using jQuery’s $.ajax method. So all my calls will look like below:

$.ajax({
   url: url, //THE ENDPOINT
   method: "GET",
   headers: { "Accept": "application/json; odata=verbose" },
   success: function (data) {
        console.log(data.d.results) //RESULTS HERE!!
   }
});

All we’re doing is replacing the url
A special note on SP 2010 users: the querystring section of the examples below may be the same. The only difference I’ve seen is the endpoint part of the url. SP 2010 has below:

"/_vti_bin/listdata.svc/" + querystring

1) Selecting all items, all columns

The simplest way to grab list items is to get everything. This is done by using the endpoint below. Simply change the “list” value to your own:

/_api/web/lists/getbytitle('listname')/Items?$select=*

Again, this will select “almost” all columns that are available to the list.  Note that I said “almost”, because SharePoint’s REST API doesn’t really bring back everything. Things such as author information and values of lookups have to be queried differently (more on this below).

2) Selecting all items, custom columns

)I find it good practice to only grab the columns that I need. This makes the payload as lean as possible.

/_api/web/lists/getbytitle('listname')/Items?$select=ID,Title

This also makes it easier to find things because each Javascript object only contain the columns “ID” and “Title”. What I don’t understand is why “ID” and “Id” is present – maybe a configuration error with the list. But nevertheless, the result is more manageable:

3) Getting the total items in a list

To get the number of items in a list, append the “ItemCount” in the end of your query sting.

/_api/web/lists/getbytitle('listName')/ItemCount

I know that you can simply do a “.length” from the a regular call which brings you all of your results, but the above is useful for filtered results, or when paging. The output looks like below:

4) Retrieving specific list items

Now this endpoint will only get the list item with the ID of “4” (I’ve removed the “_spPageContextInfo.webAbsoluteUrl” component for easier read…

/_api/web/lists/getbytitle('listname')/items(4)

A more powerful solution is using the $filter key. Not that this option allows you to get items with more flexibility. Check out this example which grabs items with the title equals to “example 1”. Note the use of single quotes! Almost all values in SharePoint REST use single quotes!

/_api/web/lists/getbytitle('listname')/Items?$select=Title&$filter=Title eq 'example 1'

5) Multiple $filter keys + values

To get items that have Title that is equal to multiple values, use the endpoint below:

/_api/web/lists/getbytitle('listname')/Items?$select=Title&$filter=((Title eq 'example 1') or (Title eq 'example 2'))

Notice that I used parenthesis to enclose the multiple parameters. This is completely optional – but improves readability.
In the case of multiple “ANDs” and “ORs”, for a stricter and finer result set, you need to use the parenthesis to enclose filter sets. This example below:

/_api/web/lists/getbytitle('ListName')/Items?$&$select=Title&$filter=((ContentType eq 'Operating Policy') or (ContentType eq 'Procedure')) and (Subject eq 'Safety')

You see how we’re grabbing items with “ContentType” equaling to “Operating Policy” OR “Procedure” AND “Subject” equaling to “Safety”.

6) Using “startswith()” and “substringof()” functions with $filter

At times you need a more powerful filter in SharePoint REST API. See “eq” will only retrieve exact matches. If you want to get everything that starts with “test”, you use the “startswith()” function:

/_api/web/lists/getbytitle('ListName')/Items?$filter=((startswith(column,'test')))

Note that the “column” is the first parameter, then the value! This is a mistake that I’ve done several times because the documentation is pretty weak.
Now, if you want to get items that “contains” specific characters, you use the “substringof()” function.

/_api/web/lists/getbytitle('ListName')/Items?$filter=((substringof('test',column)))

Unlike startswith(), the substring() takes the “value” first, then the “column”. Again, note the difference between the two.

7) Limiting your results

The $top parameter basically limits your items to a specified number. The syntax is below:

/_api/web/lists/getbytitle('listname')/Items?$select=Title&$top=10

This is also useful for creating paging systems – in combination with an offset option (below).

8) Offsetting results (for paging)

So you know how to limit your results, and you know how to get the total items. All you need is to offset your results. You do this with the “$skip” parameter.

/_api/web/lists/getbytitle('listname')/Items?$top='10'&$skip='20'

Again, note the use of single quotes. The above will get a set of 10 items, starting from the 20th in the list. Combined with the total, you can create your own paging mechanism.
Update 8/10/2016: I just found out that the $skip parameter doesn’t work with list items. There is a property in the REST response that you can use – for paging. This is known as the “___next”. I will do another tutorial strictly on this subject – so stay tuned.

9) Getting the Author Information

You have to specify that using the “$expand” key. Also an additional parameter to the “$select” key is needed. For example, to grab the Id and the name of the author, simply append to your query:

/_api/web/lists/getbytitle('listname')/Items?$select=Author/Title,Comment&$expand=Author/Title

The above will return the author information in it’s own node called “Author”.

10) Document Libraries

SharePoint REST API supports querying document libraries. Remember, doc libs are also lists and for the most part, are handled through the same endpoint.

/_api/web/lists/getbytitle('Document Library Name')/Items?$select=Title,FileLeafRef,EncodedAbsThumbnailUrl,EncodedAbsUrl

The example above returns information about your file such as the name, full url and the internal “Title”:

For instances where you want to know the “type” of document library it is (example Picture Library vs Document Library), use:

/_api/web/lists/getbytitle('Document Library Name')/BaseTemplate

Although some information regarding document libraries require an entirely new endpoint. This includes file paths, subfolders, thumbnails and such.

/_api/web/GetFolderByServerRelativeUrl('"Folder Name"')/Files

The above contains an entire new set of information regarding your library.

11) Getting Current User information:

At times you want to grab the current user’s information. Use the endpoint below:

/_api/SP.UserProfiles.PeopleManager/GetMyProperties

I’ve also used the more current endpoint below:

/_api/web/currentUser

Again, there may be additional information that is not returned by the above, such as user groups (below) which requires a different endpoint.

12) Getting Current User Groups

For some reason, this information is separate from getting the current user information described above. But in order to get the current user groups, you need to pass the ID:

/_api/web/GetUserById('"+ userId +"')/Groups

So you need to get the “userId” first, then do the above ajax call. Something like below:

function getCurrentUser(){
   var ajax = $.ajax({
       url:   _spPageContextInfo.siteAbsoluteUrl + "/_api/web/currentUser",
       method: "GET",
       headers: { "Accept": "application/json; odata=verbose" },
       error: function (data) {
           console.log(data);
          }
        });
       return ajax;
}
function getUserGroups (userId) {
   var ajax = $.ajax  ({
        url:  _spPageContextInfo.siteAbsoluteUrl + "/_api/web/GetUserById('"   + userId + "')/Groups",
        method: "GET",
           headers: { "Accept": "application/json; odata=verbose" }
     });
    return ajax;
    }
getCurrentUser().done(function(userId){
   getUserGroups(userId.d.Id).done(function(groups){
       console.log(groups.d.results);
   });
});

Above is an example of a “promise”. For more on that, read my Working with jQuery’s AJAX, Promises and Deferred objects.

13) Retrieving”Choice Column” values

There are times when you want to build an application that requires you to drill down to a choice column, and grab it’s values. A “choice column” in SharePoint is a type of column where you add values for users to choose from.

You retrieve the values by doing an ajax call to the SharePoint REST API endpoint, specifying the column name you want. Below is an example:

/_api/web/lists/GetByTitle('LISTNAME')/fields?$filter=EntityPropertyName eq 'Subjects'

The above will query the choice column “Subjects” from the list “LISTNAME”.

**The __metadata object

You will notice that each result will have this __metadata object tied to it.

This contains important material that will help you later in update and delete operations. I’ll cover that in the next chapter.

Bonus: SharePoint Search API

If you have Search features turned on, you will be able to do powerful queries against any of your content inside your SharePoint farm. SharePoint search crawls through your material such as Word documents, Excel, PDF, Lists, Webpages – anything that you’ve configured to be searchable – you can query against in the SharePoint Search API.
Your application will go up an extra level – simply by integrating this capability. Here are a few common Search API calls – for selecting / querying items:

1) A Standard Search

Doing a regular is as simple as passing your search term to the endpoint below:

/_api/search/query?querytext='"+ TERM +"'

The tricky part is parsing the results.

Are you ready for this? The results are buried under: data.d.query.PrimaryQueryResult.RelevantResults.Table.Rows.results

2) Selecting specific Properties

At times, you want the payload to remain small. The SharePoint Search API supports selecting only the properties you need. Below is a good way to achieve this:

/_api/search/query?querytext='"+ TERM +"'&selectproperties='Title,Path,FileExtension,IsContainer'

Adding a “selectproperties” querystring along with a comma separated properties that we need will do the trick. Again, note the use of single-quotes.

3) Offsetting Results (for paging)

For instances where you want to return the set of rows that starts from a specific number:

/_api/search/query?querytext='"+ TERM +"'&startrow=10

Adding the “startrow” querystring will do it. Note that SharePoint Search API has a complex algorithm of sorting and returning results. Therefore, the total and the actual values are approximates.

4) Limiting Results

You don’t want to return everything! You simply want to limit your search:

/_api/search/query?querytext='"+ TERM +"'&rowlimit=25

The “rowlimit” querystring is your friend.

5) Only Results from a Specific List or Document Library

This one you will need the list Id. You can grab the list Id by going to your list / library, and clicking on “List Settings” or “Library Settings”. Once there, go to the URL and grab the value after “List=”. Note that this value is url encoded – with single quotes. So remove the leading “%7B”, and the trailing “%7D”. What you’re left with is the List Id.

/_api/search/query?querytext='"+ TERM +"'&sourceid='YOUR-LIST-ID'

Remember to wrap your list id in single quotes. This query will only return items from the specific list that you’ve specified.

6) Get People Results

For this one, it’s exacly the same as above.

/_api/search/query?querytext='"+ TERM +"'&sourceid='b09a7990-05ea-4af9-81ef-edfab16c4e31'

Simply replace the list id with this: “b09a7990-05ea-4af9-81ef-edfab16c4e31“. Yes it seems like it’s the same for everybody.

7) Getting Best Bets

“Best Bets” is SharePoint’s “elevated results”. These get pushed to the top of the result set, for specific queries. Note that these items are not included in the regular results – which means that it is not to be included in paging and filters and such.

/_api/search/query?querytext='"+ TERM +"'&processbestbets=true&enablequeryrules=true

The resultset you need to parse is in this property: data.d.query.SecondaryQueryResults.results[0].SpecialTermResults.Results.results
Haha! Ugly eh? Inside “results” is an array of objects you need. Note that the properties of each object may not be as complete as the primary results.

8) Filtering Results

Sometimes you don’t want the whole resultset to comeback. This is where filtering comes in. SharePoint Search API has “refinement filters” which does the job.

/_api/search/query?querytext='TERM'&refinementfilters='(FIELD:string("FILTERTERM", mode="phrase")'

The above will search for “TERM”, filtered with the “FILTERTERM”  in the field called “FIELD”.

9) Filtering Results in Multiple Fields

So now we need to filter by many fields. Yes it’s possible, and we still use “refinement filters” in the Search API.

/_api/search/query?querytext='TERM'&refinementfilters='and(COL1:string("COL1TERM", mode="phrase"),COL2:string("COL2TERM", mode="phrase"))'

Just like the single filter, but instead we add “and” in the beginning (you can also use “or”), plus separating the columns and terms with a comma.

10) Sorting Results

At times, the sorting of SharePoint’s Search API is not what you’re looking for. Well we can sort it.

/_api/search/query?querytext='TERM'&sortlist='LastName:ascending,FirstName:ascending'

The example above shows the results being sorted by “LastName”, ascending first, then “FirstName” etc.

Conclusion

As I’ve mentioned, SharePoint’s REST AND SEARCH API has some very powerful features. And with OData’s standard’s, you can create quite advanced queries. I will try to keep this article updated with more Select related queries, but for now I have to go. Stay tuned for the next part.

The post Understanding SharePoint’s REST and Search API Part 1 – Selecting Items appeared first on Michael Soriano.