ExamplePoint

How to make a code free CEWP solution for the end user!  Read On.

End user: "HELP!!! All these solutions using the Content Editor Web Part, look like they will address my issues, but I know NOTHING about code.  I do not understand how I am to change something called variables to make it work on my site. I am not sure I can implement this, but I wish I could."

How many times have we been told this or have not since the end user may get overwhelmed and moves on. I bet that your CEWP solutions have not been implemented more times then you care to know because of this issue.

I listened to one of Mark Millers presentations at www.endusersharepoint.com where he had a panel discussing the needs of information workers.  One of the topics was about how even the great CEWP solutions were still a lot of work for the information worker to easily install and thus information works leave and do not implement the solution.

I have had many email conversations with information workers wanting to implement a solution of mine, but were hung up on where exactly should the changes take place.  When they say they have tried everything I ask them to send me the code and then I can see if they have added the info correctly.  Only those who are determined to make the solution work will go though all these steps.  Many will just walk away because it is too hard to find the right place in the code to make the changes. 

So I got to thinking about this problem and then it dawned on me that Microsoft has provided in the CEWP a way to add code directly, Source Editor, and a way to visually edit content, Rich Text Editor (RTE).  We have the tools right there to make an interface using the RTE, but how do we take information added in the RTE and use it in the code?  This is where jQuery comes in and helps us pull the data entered in the RTE by the user. Now that is exciting. 

In summary we have the ingredients to create a better way for information workers to implement our solutions in a no code manner, YEAH!

Overview

What is CEWP Solution Interface?  Who is this geared for?  It is all  about providing CEWP solution developers an easier way to deploy solution that require customizations.  This series of articles is geared for the solution developer with the intention to help the end user or  information worker to have an easier time install CEWP solutions.

So what problem are we trying to solve?  Simply ease of use.  Microsoft started this with the introduction SharePoint, which made it some much easier for the end user to create a collaborative site without having to go to IT. Now we need to do the same for the CEWP solutions that we create.

Your CEWP solution uses JavaScript or jQuery to solve many needs, but many times for the solution to work in the end user SharePoint environment the end user needs to go into the code of your solution and change variables. This solution is an attempt to solve the problem for the both the creator of the solution and the end user installing it.

So, let's create a way that the end user does not have to go into the code to make changes. The rest of this article will outline the high level view of how this solution will work.  We will create an interface that can capture the required variables from the end user to be used in your solution using JaveScript and jQuery for the solutions.  If this interest you please read on.

What we need:

·          CEWP - check 

·          Source Editor - check

·          Rich Text Editor (RTE) - check 

·          JavaScript - check

·          jQuery - check (I will show how we can have this dynamic being local or externally hosted.)

So let's transform this from The Old Way where the information worker has to look through code like this to find the right place to make changes.   Code changes should really just be made by the creator, not the implementer.

Let's transform to a new way that looks and feels more like an options panel.  As you can see in the The New Way the information worker does not have to look at any code.  They have a nice form that has instruction on what to do.  This should make it much easier to implement your CEWP solution.

We also can have the option to communicate when there are errors or missing information.  The more we can communicate to the end user the better the experience and the more likely that an end user can solve problems without getting frustrated and needing to go back to the developer.

Below you see images where we can display errors when they occur.  The wonderful part is that we can show errors even when they are not in edit page mode.  The example below shows the error in the standard page view.

In addition to communicating errors we can communicate information about the solution.  Now we can identify what solution it is, what version it is and provide the user a URL to find and read about the latest info on the solution.  This information should only be shown when we are in edit mode and we can do that too. Again, we can communicate more information about the solution and how the end user can access details about the solution.

Next Steps

In the next series of articles I will outline how we wrap your CEWP solution with the above interface and transform how users interact with your solution.   We will start off with the basics in the next articles and focus on just having the interface for the end user to add the variables needed.  We then will progress in to Solution Info panel, error checking and how we implement jQuery.

Hope you find this helpful.  Please send me any comments.

Introduction

Now let's get to the meat of this solution.  How do we implement this?  This article will show how to implement the basic CEWP Solution Interface.  The next articles will start to add the bells and whistles.  If you have not read the first article in this series please read the first article first and then come back here. First Article can be found here:  SharePoint CEWP Solution Interface – Introduction

So, a recap, we are putting a solution together that will make is easier for the end user to implement your CEWP solution.  We are creating an options panel so the end user does not need search your code to change specific variables.  So what do we need is as follows:

·          CEWP - check 

·          Source Editor - check

·          Rich Text Editor (RTE) - check 

·          JavaScript - check

·          jQuery - check (I will show how we can have this dynamic being local or externally hosted.)

We also need a solution for this example.  I am going to use Christophe's solution for viewing a list from another site.  His example is a classic with regards to asking the end user to make modifications to the code to make it work.  In his code the end user has to add the URL to the variable to make it work.  We coders can see where to make changes but the end user will go disey looking for the right place to make changes.

Solution Code:

Great we have the tools to put this solution in place.  Now we need to put the code in place for this work.  Before we do that lets outline the different sections that we will have in this code.

Solution Sections

This solution will be rolled out in several articles to show the additional features that can be added on as needed.  There are a few components that you will need to implement this solution and this article will go over the basics.

So, let's go over the major components to implement this solution.

Here are all the components for the solution.  We will not go over all of them only the ones highlighted in BLUE.

·          Interface: A way to for the end user to input the require variables to make it work in their environment.

·          Solution Info: This will allow you to display info about your solution like Title, Details, Site Name, Site URL, Author, and Version. (This will be done in a future article.)

·          jQuery Loading: Since jQuery is a part of the solution a way to ensure jQuery is present with this solution.

·          Variables: A way to capture the data captured through the interface and apply it to your code.

·          Error Checking: Now that we have a interface for end users to enter the variables it would be good to check for errors and communicate errors when found. (This will be done in a future article.)

·          Solution Code: Last is your solution code and tying it into the solution.

·          Solution Tracking: This is a way to track how many times your solution is being used by others. (This will be done in a future article.)

Now let's begin.

Interface

The interface is the forward facing view that will transfer this to a no code solution for the end user.  The interface was designed to be simple and easy for an end user to provide the needed information to make the solution work in their environment.

Essentially these are variables that tell the script/solution how to function.  To the end user these are just values that need to be entered into something like a form, which most end users will relate to.

The Interface is a table where we identify the “option”, provide a place to enter the “value” and outline any “help” or parameters to guide the end user.  With the interface you can now provide the end user more details about was is needed in a more concise way then ever before. So CEWP Solution Interface variable collection is broken out into three sections and they are as follows:

·          Option: This field identifies the name for the option.

·          Value: This field is where the end user will enter the value/variable.  This field will also be a different color then the other fields to clearly indicate where information should be entered.

·          Help: This field will outline details as to what is needed in the option, how to provide the information and/or what impact this will have on the solution.

Here is a sample view of how the interface can look.

The CEWP Interface window is divided up into three main areas.  The three areas provide an overview, a place to get the variables needed for your solution and the last to display the solution.  The third part cannont be hidden and so we must set an area aside to display and communicate to the end user not to make changes.  Just something we have to work with when using the RTE.

The three sections:

1.       Overview:  Provide a place to give a general overview of the solution and what is needed in the options view.

2.       Options: Provide a place to gather the options and communicate any help.

3.       Solution View: Have a separate area where the solution html code will show.  Cannot hide this so we separate it and communicate for the end user not to change anything.

So let's walk through the code to set this all up.

Overview

The overview section is simply a table.  The Overview row provides a place to help the end user understand what they can do in this configuration and if there are any items that must get completed.

Code:

<table class="table" >

<thead class="thead">

<tr><th class="thTop th" colspan="2">[Name] - Configuration</th></tr>

</thead>

<tbody class="tbody">

<tr><td class="tdOverview">Overview</td><td class="tdOverviewField">[Comments]</td></tr>

</tbody>

</table>

Options

The options area is the heart of this interface, as it is where the end user will input all the critical information to make the solution work in a no code environment.  So there are three rows provided for each option to make it as easy for the end user.  We provide the following rows:

·          Option: This field identifies the name for the option.  Best to provide as descriptive a name as possible.

·          Value: This field is where the end user will enter the value/variable.  This field will also be a different color then the other fields.

·          Help: This field will outline details as to what is needed in the option, how to provide the information and/or what impact this will have on the solution.  This is the place to provide any details that will help the end user put the right information in.

To make this solution work properly and have as little conflict with other solution introduced on the same page there is one thing that will have to happen.  The option(n) id found in the code below will have to be appended. Why you ask, because if two solutions using this interface were to be put on the same page id="option1" would be present twice and the wrong variable will be used in one of the solutions and cause a problem.  So each solutions developer will need to option(n) with something unique.  I have provided a random key generator that can be used to make option(n) unique for your solution. 

Here is an example:  option1-tOcWUW. You would then apply -tOcWUW to all option(n) found in the  code.  They can be found in the interface table and where we define the variables.

Unique ID Generator: Click to get unique code to add to options.

Code Before:

<tr><td class="tdOption">Option</td><td class="tdOptionField ">[Name]</td></tr>

<tr><td class="tdValue">Value</td><td id="option1-" class="tdValueField"></td></tr>

<tr><td class="tdHelp">Help</td><td class="tdHelpField">[Comments]</td></tr>

<tr><td class="tdOption">Option</td><td class="tdOptionField ">[Name]</td></tr>

<tr><td class="tdValue">Value</td><td id="option2-" class="tdValueField"></td></tr>

<tr><td class="tdHelp">Help</td><td class="tdHelpField">[Comments]</td></tr>

Code After applying the unique identifier:

<tr><td class="tdOption">Option</td><td class="tdOptionField ">[Name]</td></tr>

<tr><td class="tdValue">Value</td><td id="option1-tOcWUW" class="tdValueField"></td></tr>

<tr><td class="tdHelp">Help</td><td class="tdHelpField">[Comments]</td></tr>

<tr><td class="tdOption">Option</td><td class="tdOptionField ">[Name]</td></tr>

<tr><td class="tdValue">Value</td><td id="option2-tOcWUW" class="tdValueField"></td></tr>

<tr><td class="tdHelp">Help</td><td class="tdHelpField">[Comments]</td></tr>

The CEWP Solution Interface can have as many options as you would like to add.  The template I provide comes with 10 options, but can be expanded as needed.

jQuery Option

jQuery is used throughout this solution and so it is critical that the jQuery is loaded.  Some end users must define where jQuery is inhouse and so we give the option for the end user to define that.  To start off with, jQuery is being pulled from Google and you will see further below in the section called jQuery Load how we address an issue if the end user deletes the reference to jQuery.  I have tried to make this as bullet proof as possible.

Code:

<tr><td class="tdOption">Option</td><td class="tdOptionField">jQuery File</td></tr>

<tr><td class="tdValue">Value</td><td id="jQueryJS" class="tdValueField">http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js</td></tr>

<tr><td class="tdHelp">Help</td><td class="tdHelpField">Only change this option if you want to use a local copy of the jQuery file.</td></tr>

Closing

When editing with RTE the end user will see all HTML in a WYSIWYG environment.  So that means that if your solution has HTML output, it will be viewed in the RTE.  Best practice is to show all of this at the end of the interface, this way we can communicate to the end user not to make any changes to the information below this line. We add this last row to the table to complete the interface part.

code:

<tr><td class="tdBBorder line" colspan="2">---- Change only the gray boxes on this page. ----</td></tr>

Branding and Style

To make this work well, it was important that we make this visually appealing and clear to the end user how this interface should be used.  We used CSS to accomplish this which will allow you to easily customize the look and feel if you like.

<style>

/* This CSS section covers the Configuration table. */

#configBox                         { display:none; }

.table                             { margin: 1em; border-collapse: collapse; width:95%; }

.th                                         { padding: .3em; border: 1px #000 solid; border-bottom: 3px #000 solid; vertical-align:top; }

.tdOverview                       { padding: .3em; border: 1px #000 solid; border-bottom: 1px #000 solid; vertical-align:top; width: 50px; }

.tdOverviewField { padding: .3em; border: 1px #000 solid; border-bottom: 1px #000 solid; vertical-align:top; }

.tdOption                          { padding: .3em; border: 1px #000 solid; border-bottom: 1px #000 solid; border-top: 3px #000 solid; vertical-align:top; width: 50px; }

.tdOptionField            { padding: .3em; border: 1px #000 solid; border-bottom: 1px #000 solid; border-top: 3px #000 solid; vertical-align:top; font-weight: bold; }

.tdValue                           { padding: .3em; border: 1px #000 solid; border-bottom: 1px #000 solid; vertical-align:top; width: 50px; }

.tdValueField             { padding: .3em; border: 1px #000 solid; border-bottom: 1px #000 solid; vertical-align:top; background: #DCDCDC; vertical-align:top; }

.tdHelp                   { padding: .3em; border: 1px #000 solid; border-bottom: 3px #000 solid; vertical-align:top; width: 50px; }

.tdHelpField              { padding: .3em; border: 1px #000 solid; border-bottom: 3px #000 solid; vertical-align:top; }

.thTop                             { font-size: 1.5em; }

.thead                             { background: #6699CC; }

.tbody                             { background: #CAE5FF; }

/* This CSS section covers the Do Not change area. */

.line                              { text-align: center; font-weight: bold; }

#errors             { padding: .3em; background-color : #F5D0A9 ; display : none ; margin : 10px ; width:500px;  }

/* This CSS section covers the Solution Info table. */

.tableInfo                         { margin: 1em; border-collapse: collapse; width:500px; }

.thInfo                   { padding: .1em; border: 1px #E6E6E6 solid; border-bottom: 3px #E6E6E6 solid; border-top: 3px #E6E6E6 solid; vertical-align:top; }

.tdInfo                   { padding: .1em; border: 1px #E6E6E6 solid; border-bottom: 1px #E6E6E6 solid; vertical-align:top; }

.tdInfoOption             { padding: .1em; border: 1px #E6E6E6 solid; border-bottom: 1px #E6E6E6 solid; background-color: #E6E6E6; vertical-align:top; text-align:center; }

.tdInfoOptionHeader       { padding: .1em; border: 1px #E6E6E6 solid; border-bottom: 1px #E6E6E6 solid; background-color: #BDBDBD; vertical-align:top; text-align:center; font-weight:bold;}

.tdInfoLabel              { text-align:right; font-weight:bold; width: 100px; padding : .3em; border: 1px #E6E6E6 solid; border-bottom: 1px #E6E6E6 solid; vertical-align:top; }

</style>

Variables

One of the main purposes of this solution was to make it easy for variables to input without having the end user having to go through the code to find the right place to add this.  As you can see from the interface we provide the end user code free experience and provide a place to capture these variables.  Now that we have them we need to make them available to your solution.

With jQuery this becomes a much easier process.  We are able to declare variables and then pull the information from the interface where the end user put the info.  To make this work properly and be a solution that can be used in multiple environments and with other solutions we need to make the identifiers in the interface unique.  We talked about this above in the interface and again it will be applied here too. 

In the interface we identified each option differently with a simple option1, option2, option3 ... etc.  This works fine in a stand alone environment, but we want this solution to not conflict with others so we need to make option1, option2, option3 unique and so we will add a 6 digit unique code to make this work.  You should have your unique code and can add here as well.

You wil also being adding the unique code to the variable name as well.  For example we start off with opt1, opt2, opt3.  We will now have them as opt1- tOcWUW, opt2- tOcWUW, and opt3- tOcWUW.

Below is the code where we declare the variables and incorporate what the end user inputed in the interface.

// This script section identifies the variables and the solution script

// Variables are commented out till needed.

// When deploying delete the unused variables.

//                                 *******IMPORTANT********

//               The 5 digit alphanumeric combination you chose above needs be applied here

//               Append to each #option1.

//               End result should look like this:

//               $('option1-4r5t6y')

//               $('option2-4r5t6y')

var opt1 = $('#option1-').text();

//var opt2 = $('#option2-').text();

//var opt3 = $('#option3-').text();

//var opt4 = $('#option4-').text();

//var opt5 = $('#option5-').text();

//var opt6 = $('#option6-').text();

//var opt7 = $('#option7-').text();

//var opt8 = $('#option8-').text();

//var opt9 = $('#option9-').text();

//var opt10 = $('#option10-').text();

So let's now declare those variables.  Using jQuery we are going to simply look for the unique id and get the text that was entered into the cell with that id.

Code before unique identifier added:

var opt1 = $('#option1-').text();

Code after unique identifier added:

var opt1tOcWUW = $('#option1-tOcWUW').text();

Now that the variable has been declared you can then use the variable in your code, but before we add your code we will talk about the loading of jQuery next.

jQuery Load

Since jQuery is required for the solution to work and we wanted the end user to have the ability to change the location of where to find the jQuery file we needed to make this a robust loading process.  We also have to evaluate if jQuery has already been loaded, as we do not want to have a conflict of it running multiple copies and different copies running at the same time will cause problems.

The solution that was built fills all of these requirements.  We pull the jQuery file location from the interface.  This will then allow the end user to go into the interface and change it to a local location if needed.  But we also had to address if the end user deleted the location in the interface that jQuery still would be loaded to run this solution.  And then lastly we needed to only load jQuery if it had not been load previously.  You will see from the code below we accomplish all of these goals.

So here is the behavior:

·          Load jQuery from Google - Default

·          End user can change location though interface

·          If no file is listed then default to Google

·          Check to see if jQuery is already loaded.

Code:

<script type=text/javascript>

     var jQPath = document.getElementById('jQueryJS').innerHTML.replace(/(<([^>]+)>)/ig,"");

if(typeof jQuery=='undefined' && jQPath != ''){

     document.write('<script src="',jQPath,'" type="text/javascript"><\/script>');

} if(typeof jQuery=='undefined'){

     document.write('<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js" type="text/javascript"><\/script>');

}

</script>

Solution Code

At this point we are ready to add your solution to this interface.  The change you will need to make is to change your variable declaration.  You will now be associateing or using opt1 with the unique identifier.  

Enter your solution code at the end of the interface where it says "Below add your JavaScript or jQuery solution  referencing the above variables".

Next I will take you though putting this all together.

Master Template

Before I show you a complete solution here is the master template for the CEWP Solution Interface.  Use this template with all of your solutions to have the interface outlined in this article.  There are addition items that in the master file that we have not gone over, but will go over in the next few articles.

CEWP Solution Interface Master Template: http://www.bitsofsharepoint.com/ExamplePoint/CodeExamples/CEWPSolutionInterface.txt

Create Solution

Let's create a solution using this new interface to make it easier for the end user to enter the information needed to  make it work.  I am going to use one of Christophe's solution from PathToSharePoint.com for the example.  I will use  his "Display a List in another Site" solution that can be found here:  http://pathtosharepoint.wordpress.com/2009/03/23/display-a-list-in-another-site-contd/

As you can see from his script that he needs the end user to look and find the variable to change to point to the right  list so that it can be viewed.  Many of our solutions are very similar to this, where we need the end user to go into the  code to make changes so that it will work for them.  Take a look at the code below and you can see it is not easy for  the end user to find and make the changes.

Christophe's code:

<!-- Load and display list - jQuery version -->

<!-- Questions and comments: Christophe@PathToSharePoint.com -->

<DIV id="ListPlaceholder"><IMG src="/_layouts/images/GEARS_AN.GIF"></DIV>

<script type="text/javascript">

// Paste the URL of the source list below:

var SelectedView = "http://domain.com/SiteCollection1/SourceSite/SourceList/MyView.aspx";

$("#ListPlaceholder").load(SelectedView+" #WebPartWPQ1 .ms-listviewtable",function() {

$("#ListPlaceholder *").removeAttr("id").removeAttr("onclick").removeAttr("onfocus").removeAttr("onmouseover");

$("#ListPlaceholder a").each(function() {

if ($(this).attr("href").indexOf("?") > 0) {$(this).attr("href", $(this).attr("href")+"\&Source="+location.href);}

else {$(this).attr("href", $(this).attr("href")+"?Source="+location.href);}

});

});

</script>

Now lets go though the steps needed to wrap his solution with the interface to make this easier for the end user.

·          Interface changes 

·          Complete the overview section: 

1.        Update the [Name] for Configuration

2.        Add [Comments] to the Overview 

·          Options Section 

1.        Identify the number of options

2.         (in this example there is only one option)

3.        Update Option [Name] - What is the name of the option they need to input information.

4.        Update Help [Comments] - here you provide the details instructions for the end user. 

·          Generate unique identifier 

1.        Each option has to have a unique id. 

1.        Example: option1-tOcWUW, option2--tOcWUW, option3-tOcWUW

2.        Add to interface and variables

3.        Add the solution code

4.        Change the variables in the solution.

You can download the Web Part here: http://www.bitsofsharepoint.com/ExamplePoint/CodeExamples/List_from_any_Site_Example_BitsOfSharePoint.dwp

Or

Find the complete solution here: