Tuesday, July 22, 2014

Setting Up Your First Device Channel in SharePoint 2013

Hello!

Today I will be walking through how to set up your first device channel, as well as explaining what a Device Channel is.

So What Is a Device Channel?
Device channels are new to SharePoint 2013 and are only available when the publishing features are turned on, so if your site is a 2013 publishing site read on!  Device channels enable you to provide a different user experience based upon the device or even browser the user is accessing your site from.  Device Channels enables the site owner to route users to a specific master page and CSS file depending upon the device or browser which is being used to access the content.  An example scenario where this might be useful is to create a tablet friendly version of your publishing site for field users.

So What Will We Be Doing Today?
Today we will be setting up a very simple device channel for an iPad Mini where we customize the page to display the text “iPad Mini”, when accessed by an iPad Mini.

What We Need:
  • A SharePoint 2013 Publishing Site
  • The device we want to create the channel for
  • SharePoint Designer 2013
  • This website to find our User Agent String
    • Whatsmyuseragent.com
User Agent String:
The user Agent String is needed in order to set up the device channel and we will be using it in a later step when we fill out our Device Inclusion Rules.

Navigate to www.whatsmyuseragent.com on the device that you would like to create a channel for.  This site will provide the User Agent String, this is the one I used for the iPad Mini
Mozilla/5.0 (iPad; CPU OS 7_1 like Mac OS X) AppleWebKit/537.51.2 (KHTML, like Gecko) Version/7.0 Mobile/11D167 Safari/9537.53
Save the user string to Notepad++ or in any text editor so you can refer to it later

SharePoint Designer:
We will use SPD to copy the .HTML of the file that we would like to begin working from, for this example I will be using the default Seattle.html.  When we copy the .HTML and paste it into the Master Page gallery the corresponding Master Page will automatically be created (don’t copy and paste the Master).

  1. Open SharePoint Designer and then open the site you are creating the device channel for
  2. Select Master Pages under Navigation
  3. Right click and copy the .html file that you would like to use as a starting point
  4. Right click and paste the .html file that you copied in 3.1.  It will create an identical copy of the file except it will append a _copy(1) onto the end of your file name, which we will rename in our next step.
  5. Select the hyperlink of the .html page you just created in order to see its properties.  From this page we will rename our file.  For the purposes of this blog post I am going to rename mine to “blogPost.html” but you could name your page something which corresponds to your device channel i.e. iPadMini.html
  6. Right click the tab name at the top of the page and select Save
    1. Select Yes to the warning about renaming the page.  This dialog will rename the corresponding Master Page and update the links.
  7. Select Master Pages
    1. You should now have the .HTML file you just created as well as a corresponding .Master


Now that we have the html and master page file in place, we can add a simple change to the .html page in order to make sure our device channel is indeed working once we complete the set up.  For the purposes of the tutorial I will just be adding a <h1></h1> tag with the verbiage “iPad Mini”, but in a real world scenario we would most likely add styling and functionality.

HTML Page:
  1. Right click your page that you just created and select Edit File In Advanced Mode
  2. Right under your opening <body> tag add the <h1>”whatever text here”</h1>.  For my example I will be using <h1>iPad Mini</h1>
  3. Right click your page’s tab and save your changes
  4. Exit SPD
SharePoint Site:
The next few steps will involve navigating back to our SP site, checking in the pages if they are still checked out, publishing them as major versions, and then finalizing the device channel.
  1. Navigate to the URL of your SP site
  2. Select the Gear Icon
    1. Select Site Settings
  3. Under Web Designer Galleries
    1. Select Master Pages and page layouts
  4. Find your html and master page that we created in the previous steps
  5. Right click your .html page or .master and select publish a major version


Finalizing the Device Channel:
The next few steps will actually implement the Device Channel and will enable you to see what your site will look like for users accessing the site from the device you have specified.
  1. Select the Gear Icon
    1. Select Site Settings
  2. Select Device Channels under Look and Feel
  3. Add a new item to Device Channels
    1. Fill out all of the fields in the form, I would explain them but there is a description under each field in SP so I will be skipping this step.  The trickiest bit is the Device Inclusion Rules which is really just looking for your user agent string which we did in the first step.
    2. Paste your User Agent String into the Device Inclusion Rules
    3. Select Activate


Activating the Device Channel:
  1. Select the Gear Icon
    1. Select Site Settings
  2. Select Master Page under Look & Feel
    1. You should now see an option for the Site Master Page you just set up
    2. Set the dropdown to the master page you would like to use for this device
    1. Select OK 
Testing the Channel:
There are two ways to check to see if the device channel was set up correctly, you could either use a test device that you selected (always a good excuse to get a new piece of hardware!) or the less fun way of adding ?&devicechannel=”alias name”.  A working example would be for my site would be “start of URL/sites/danspubtest?&devicechannel=iPadMini

Check It Out!
Congrats!!!!!  If you have followed this tutorial, you should have just viewed your site with the heading that we added earlier specific to that device!J


Cheers!
Dan

Tuesday, July 8, 2014

Form / Data Validation Using jQuery & Javascript

Hello Readers,

It has been a while since my last post and I apologize for the delay!  Today I wanted to talk about how to use jQuery and JavaScript to validate field values in SP forms.  This example will be extremely simple, but hopefully it will help cover the basics, as well as spark some ideas on how you might want to validate entries on your forms.  You will need to add this script to the new & display form.aspx pages with either with a content editor or script editor web part.

If you are just getting started with JavaScript and jQuery I would highly recommend reading through Mark  Rackley’s  A Dummies Guide to SharePoint and jQuery-Getting & Setting SharePoint Form Fields which is a fantastic blog series as well as Marc Anderson’s  Blog which is loaded with great content.  Both of their sites run through all of the selectors i.e. when to use select, input, etc. so I will not be covering that in this post.

For my example today I have a simple custom list with the following fields:
            Title: (single line of text) (input field)
            Candidate Hired: (combo box dropdown N/A, No, Yes) (select field)
            Candidate Start Date: (date & time control)

I want to an alert to pop up letting the user know that they accidentally left the Start Date blank when Candidate Hired = “Yes” & the Candidate Start Date was left blank.  If we were going to rely on this script for validation we would want to put in other conditions to handle scenarios such as having a start date without selecting yes, but for the sake of simplicity we will keep it very basic.

To Do This We Will Need:
·         A reference to the jQuery library
o   We can reference the library either with a CDN (content delivery network) or by downloading the library and storing it somewhere on our SharePoint site and linking to it there.
o   If you download the library I would recommend saving the file with a title of jQuery and adding an additional field to the library with the version number.  This is a good practice since if you have multiple scripts linked to the jQuery library, they won’t break when a new version is uploaded and the file name changes.
·         This Script
<script type="text/javascript" src="LINK TO jQuery Location"></script>
 <script type="text/javascript" language="javascript">
 function PreSaveAction() {
drop = $("select[title='Candidate Hired']").val();
date = $("input[title='Candidate Start Date']").val();
    if (drop ==="Yes" && date===""){
        alert("You Shall Not Pass, Fix The Date!");
        return false;
    }   
        return true;
}
 </script>

How Does The Script Work?
Essentially what this script does is to check to make sure that the Candidate Start Date is not left blank if the user indicated they were hired before they can save the form.  We are obtaining the values based on the form’s display names **Not Internal Names!!** and then checking those values before the form can be saved.  If the form matches our criteria of Hired = yes & Start Date = “”, then our script will pull a Galdalf when the user tries to submit the item with a “YOU SHALL NOT PASS” until the form has been fixed.  

In order to repurpose the script you could swap out the display names and use it as is or you could use it as a template to start writing your own validation scripts.  Although some validation can be done via the column validation and list validation in SharePoint, I always run into scenarios where a simple script enhances the user’s experience as well as ensures the inputted data is correct.  An example of this would be to use JavaScript to create an input mask for form fields or to ensure that an email address field actually contains @ & .com.

Well again this script is super basic, but I hope that this sparks some thoughts on where your forms could be enhanced and how you can use jQuery and JavaScript to get it done!


Best Regards,
Dan