Skip to content

Commit

Permalink
Merge pull request #46 from joshmcrty/master
Browse files Browse the repository at this point in the history
Additional Value-added Documentation
  • Loading branch information
joshmcrty authored Aug 31, 2016
2 parents 3322788 + 46cc582 commit 491f2d4
Show file tree
Hide file tree
Showing 15 changed files with 458 additions and 3 deletions.
6 changes: 3 additions & 3 deletions docs/value-added/SPAutocomplete.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,11 +40,11 @@ $().SPServices.SPAutocomplete({

### WebURL

The URL of the Web (site) which contains the sourceList. If not specified, the current site is used. Examples would be: `/`, `/Accounting`, `/Departments/HR`, etc. **Note**: It's always best to use relative URLs.
The URL of the Web (site) which contains the sourceList. If not specified, the current site is used. Examples would be: `"/"`, `"/Accounting"`, `"/Departments/HR"`, etc. **Note**: It's always best to use relative URLs.

### sourceList

The name or GUID of the list which contains the available values. If you choose to use the GUID, it should look like: `{E73FEA09-CF8F-4B30-88C7-6FA996EE1706}`. Note also that if you use the GUID, you do not need to specify the WebURL if the list is in another site.
The name or GUID of the list which contains the available values. If you choose to use the GUID, it should look like: `"{E73FEA09-CF8F-4B30-88C7-6FA996EE1706}"`. Note also that if you use the GUID, you do not need to specify the WebURL if the list is in another site.

### sourceColumn

Expand Down Expand Up @@ -78,7 +78,7 @@ If set to true, the function ignores case, if false it looks for an exact match.

### highlightClass

When a matching value is shown, the matching characters are wrapped in a `<span>`. If highlightClass is specified, that class is applied to the `span`. An example might be:
When a matching value is shown, the matching characters are wrapped in a `<span>`. If highlightClass is specified, that class is applied to the `span`. An example might be:

``` javascript
highlightClass: "ms-bold",
Expand Down
94 changes: 94 additions & 0 deletions docs/value-added/SPComplexToSimpleDropdown.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
## Function

**$().SPServices.SPComplexToSimpleDropdown**

## Certification

[![Certified for SharePoint 2007](/docs/img/sp2007-cert.jpg "Certified for SharePoint 2007")](/docs/glossary/index.md#Certification) [![Certified for SharePoint 2010](/docs/img/sp2010-cert.jpg "Certified for SharePoint 2010")](/docs/glossary/index.md#Certification)

## Functionality

The SPComplexToSimpleDropdown function lets you convert a "complex" dropdown rendered by SharePoint in a form to a "simple" dropdown. It can work in conjunction with SPCascadeDropdowns; call SPComplexToSimpleDropdown **first**.

While this function doesn't use the SharePoint Web Services directly, it can be used with other SPServices functions which do.

SharePoint renders dropdowns differently in Internet Explorer depending on whether they have fewer than 20 options or 20+ options. (In Firefox, Chrome, and other browsers, SharePoint doesn't give us this "benefit".) You can read more about these differences in my blog post [Two Types of SharePoint Forms Dropdowns](http://sympmarc.com/2010/05/19/two-types-of-sharepoint-forms-dropdowns/).

In the example below, Region is a "simple" dropdown. because it has fewer than 20 options. State is a "complex" dropdown because it has 20+ options.

![](/docs/value-added/img/SPComplexToSimpleDropdown1.png)

## How Does It Work?

The SPComplexToSimpleDropdown function works like this:

* When the function is first called, it finds the dropdown control for the specified column name. If the control cannot be found and debug mode is enabled, an error is shown.
* If the dropdown for the specified column is not a complex dropdown, we do nothing. This might be the case if the number of available options has decreased to fewer than 20, for instance.
* The input element for the complex dropdown contains an attribute called `choices` which contains all of the available values and their IDs in one long vertical bar ("|") separated string, e.g., "`(None)|0|Alabama|18|Alaska|114|Alberta|16|Arizona|8|Arkansas|98|...`"
* The function takes that string of values and builds up a simple select (the kind you are most likely familiar with) and prepends it to the table detail cell (TD) which contains the complex dropdown. The new simple select will have its id  set to `"SPComplexToSimpleDropdown_" + opt.columnName` for easy selection later, if needed.
* Next we hide the original dropdown.
* Finally, we attach to the change event for the simple select we have created. When a change occurs, we set the value of the complex dropdown to match the selected option and trigger a click event on the small dropdown image image, thus initiating some of SharePoint's native script to handle the change.  By maintaining the complex dropdown "as is", we can ensure that the proper value is stored in the list when the changes are committed.

Note that if the function fails for whatever reason, you should still be left with a working form.

## Prerequisites

There are no prerequisites for this function.

## Syntax

``` javascript
$().SPServices.SPComplexToSimpleDropdown({
columnName: "",
completefunc: null,
debug: true
});
```

### columnName

The [DisplayName](/docs/glossary/index.md#DisplayName) of the column in the form

### completefunc

If specified, the completefunc will be called each time there is a change to columnName. Potential uses for the completefunc: consistent default formatting overrides, additional lookup customizations, image manipulations, etc. You can pass your completefunc in either of these two ways:

``` javascript
completefunc: function() {
...do something...
},
```

or

``` javascript
completefunc: doSomething, // Where doSomething is the name of your function
```

### debug

Setting `debug: true` indicates that you would like to receive messages if anything obvious is wrong with the function call, like using a column name which doesn't exist. I call this [debug mode](/docs/glossary/index.md#debug-mode-).

## Examples

This is the simplest example for using SPComplexToSimpleDropdown. You simply provide the columnName:

``` javascript
$().SPServices.SPComplexToSimpleDropdown({
columnName: "State"
});
```

and the complex dropdown (as shown in the image above) is converted to a simple dropdown:

![](/docs/value-added/img/SPComplexToSimpleDropdown2.png)

If you'd like to convert all of the complex dropdowns in a form to simple dropdowns, you can use this trick from [DanKline](https://www.codeplex.com/site/users/view/DanKline), which he posted in this discussion thread [https://spservices.codeplex.com/discussions/443485](https://spservices.codeplex.com/discussions/443485)

``` javascript
$('.ms-lookuptypeintextbox').each(function() {
$().SPServices.SPComplexToSimpleDropdown({
   columnName: $(this).attr('title')
});
});
```
137 changes: 137 additions & 0 deletions docs/value-added/SPFilterDropdown.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
## Function

**$().SPServices.SPFilterDropdown**

## Certification

[![Certified for SharePoint 2007](/docs/img/sp2007-cert.jpg "Certified for SharePoint 2007")](/docs/glossary/index.md#Certification) [![Certified for SharePoint 2010](/docs/img/sp2010-cert.jpg "Certified for SharePoint 2010")](/docs/glossary/index.md#Certification)

## Functionality

The SPFilterDropdown function allows you to filter the values available in a Lookup column using CAML against the Lookup column's source list.  This function works with all three types of "dropdown": <20 options (simple select), 20+ options (complex select), and multi-select.

Thanks to Alex Lee ([alexlee797](http://www.codeplex.com/site/users/view/alexlee797)) and Ryan ([rnshaw](http://www.codeplex.com/site/users/view/rnshaw)) for contributing their versions of this function, which I used to build the one available here. You can see their versions in these two discussion threads: [Filter Dropdowns](http://spservices.codeplex.com/discussions/207947) and [SPCascadeDropDowns - CAML query on parent column?](http://spservices.codeplex.com/discussions/235579)

## Prerequisites

* The relationship list contains the relationshipListColumn
* The dropdown for columnName is a lookup into relationshipList's relationshipListColumn OR a list column which is a lookup into another list column ("secondary list").

## Syntax

``` javascript
$().SPServices.SPFilterDropdown({
relationshipWebURL: "",
relationshipList: "",
relationshipListColumn: "",
  relationshipListSortAscending: true, // Added in 2013.01
relationshipListSortColumn: "",
columnName: "",
 listName: $().SPServices.SPListNameFromUrl(),
 promptText: "",
noneText: "(None)",
CAMLQuery: "",
 CAMLQueryOptions: "<QueryOptions></QueryOptions>",
completefunc: null,
debug: false
});
```

### relationshipWebURL

The URL of the Web (site) which contains the relationshipList. If not specified, the current site is used. Examples would be: `"/"`, `"/Accounting"`, `"/Departments/HR"`, etc. **Note**: It's always best to use relative URLs.

### relationshipList

The name or GUID of the list which contains the parent/child relationships. If you choose to use the GUID, it should look like: `"{E73FEA09-CF8F-4B30-88C7-6FA996EE1706}"`. Note also that if you use the GUID, you do not need to specify the relationshipWebURL if the list is in another site.

### relationshipListColumn

The [StaticName](/docs/glossary/index.md#StaticName) of the column in the relationshipList which is used for the lookup column

### relationshipListSortColumn

If specified, sort the options in the dropdown by this column otherwise the options are sorted by relationshipListColumn

### relationshipListSortAscending

Allows sorting either ascending (`true`) or descending (`false`). The default is `true` (ascending).

### columnName

The [DisplayName](/docs/glossary/index.md#DisplayName) of the column in the form

### listName

By default, set to the list name for the current context based on the URL. If your form is outside the context of the list, then you can specify the listName yourself.

### promptText

Text to use as prompt. If included, {0} will be replaced with the value of childColumn. The default value is `""`.

**NOTE**: I discourage the use of this option. Yes, I put it into the function, but if the user doesn't make a choice, they get an ugly error because SharePoint doesn't understand it as an option. I've left in in for backward compatibility.

**Deprecated in v0.7.1.**

### noneText

Text to use for the (None) selection. Provided for non-English language support. The default value is `"(None)"`.

### CAMLQuery

The CAMLQuery option allows you to specify the filter on the relationshipList. The additional filter will be `<And>`ed with the existing CAML which is checking for matching items based on the parentColumn selection. The CAMLQuery should contain a CAML _**fragment**_ such as:

``` javascript
CAMLQuery: "<Eq><FieldRef Name='Status'/><Value Type='Text'>Active</Value></Eq>"
```

### CAMLQueryOptions

This option can be used to specify additional options for retrieval from the sourceList. See the [MSDN documentation for GetListItems](http://msdn.microsoft.com/en-us/library/lists.lists.getlistitems.aspx) for the syntax.

### completefunc

If specified, the completefunc will be called upon completion of the filtering. Uses for the completefunc: consistent default formatting overrides, additional lookup customizations, image manipulations, etc. You can pass your completefunc in either of these two ways:

``` javascript
completefunc: function() {
...do something...
},
```

or

``` javascript
completefunc: doSomething, // Where doSomething is the name of your function
```

### debug

Setting `debug: true` indicates that you would like to receive messages if anything obvious is wrong with the function call, like using a column name which doesn't exist. I call this [debug mode](/docs/glossary/index.md#debug-mode-).

## Example

In this example, we'll filter the lookup column called "Country" so that we only include those Countries where the Active column is set to 'Yes'. In the screenshot below, you can see that Canada is not currently 'Active'.

![](/docs/value-added/img/SPFilterDropdown1.png)

In the Sales Opportunities list, we have a lookup column called Country, which gets its values from the Title column in the Countries list.

![](/docs/value-added/img/SPFilterDropdown2.png)

If we add the call to SPFilterDropdown below...

``` javascript
$().SPServices.SPFilterDropdown({
relationshipList: "Countries",
relationshipListColumn: "Title",
columnName: "Country",
CAMLQuery: "<Eq><FieldRef Name='Active' /><Value Type='Boolean'>1</Value></Eq>",
completefunc: null,
debug: false
});
```

...then 'Canada' is filtered out of the available values because it is not 'Active'.

![](/docs/value-added/img/SPFilterDropdown3.png)
46 changes: 46 additions & 0 deletions docs/value-added/SPFindMMSPicker.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
## Function

**$().SPServices.SPFindMMSPicker**

## Certification

[![Certified for SharePoint 2010](/docs/img/sp2010-cert.jpg "Certified for SharePoint 2010")](/docs/glossary/index.md#Certification)

## Functionality

The SPFindMMSPicker function helps you find a Managed Metadata Service (MMS) Picker's values.

## Syntax

``` javascript
$().SPServices.SPFindMMSPicker({
MMSDisplayName: ""
});
```

### MMSDisplayName
The [DisplayName](/docs/glossary/index.md#DisplayName) of the People Picker in the form.

## Returns

The function returns an array of terms, with both the guid and the value for each term.

## Example

Assume there is a MMS Picker in the form for a column named **Office** which allows multiple values and that it is set like so:

![](/docs/value-added/img/SPFindMMSPicker1.png)

After the call:

``` javascript
var office = $().SPServices.SPFindMMSPicker({
MMSDisplayName: "Office"
});
```

office will be an object like this:

![](/docs/value-added/img/SPFindMMSPicker2.png)

Note that invalid values will have the guid set to "00000000-0000-0000-0000-000000000000".
76 changes: 76 additions & 0 deletions docs/value-added/SPFindPeoplePicker.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
## Function

**$().SPServices.SPFindPeoplePicker**

## Certification

[![Certified for SharePoint 2007](/docs/img/sp2007-cert.jpg "Certified for SharePoint 2007")](/docs/glossary/index.md#Certification) [![Certified for SharePoint 2010](/docs/img/sp2010-cert.jpg "Certified for SharePoint 2010")](/docs/glossary/index.md#Certification)

## Functionality

The SPFindPeoplePicker function helps you find and set People Picker columns. These little buggers are problem enough as it is, and selecting them and manipulating them with jQuery is something that a lot of people want to do. Add to that the fact that the People Picker is rendered differently in IE than in other browsers, and you have a challenge not unlike simple vs. complex dropdowns.

These are the columns which let us select known users in SharePoint, and they look something like this:

![](/docs/value-added/img/SPFindPeoplePicker1.png)

SPFindPeoplePicker allows you to get or set the values for People Pickers. When you call it with the [DisplayName](/docs/glossary/index.md#DisplayName) of a People Picker, the function returns an object which contains information about the People Picker’s structure and current value.

**_IMPORTANT NOTE:_** In v0.7.2, this function was mistakenly named $().SPFindPeoplePicker. This was inconsistent with the other function namespacing. As of 2013.01, both $().SPServices.SPFindPeoplePicker and $().SPFindPeoplePicker will work.

## Syntax

``` javascript
$().SPServices.SPFindPeoplePicker({
  peoplePickerDisplayName: "",
  valueToSet: "",
  checkNames: true
});
```

### peoplePickerDisplayName
The [DisplayName](/docs/glossary/index.md#DisplayName) of the People Picker in the form. 

### valueToSet
If you'd like to set the value of the People Picker, optionally provide it here. 

### checkNames
If you'd like to "click" on the Check Names icon to resolve the name in the People Picker, set checkNames to `true`. The default value is `true`.

## Returns

The function returns an object containing information and values which tell you about the People Picker you have specified:

### row

This is reference to the table row which contains the People Picker. This can be useful if you want to hide or show the row conditionally based on some user action.

### contents

The full contents of the `div[name='upLevelDiv']` element.

### currentValue

The current value set in the People Picker. If you pass a value into the function, it will be set and returned in this string. If there are multiple people specified, they are returned separated by semi-colons, as in the People Picker display.

### checkNames

This is a reference to the checkNames img tag in the People Picker. It’s used by the function to initiate resolution of a Person or Group value by firing the click event on it. Once you have this reference, you can do the same.

### dictionaryEntries

If the browser is Internet Explorer, then this object will contain the full dictionary entry values for each user or group in the People Picker value. If the browser is not IE, then the function calls [GetUserInfo](/docs/core/api/UserGroup.md) to retrieve similar values to mirror the dictionary entry structure.

## Example

Assuming there is a People Picker in the form for a column named **Sales Rep** that is set to contain the two people Eric Mullerbeck and Marc Anderson:

``` javascript
var salesRep = $().SPFindPeoplePicker({
peoplePickerDisplayName: "Sales Rep"
});
```

`salesRep` will be an object with the following attributes. There are considerable differences between how the People Picker works in different browsers; the example below is from Internet Explorer. In the function I try to "smooth over" those differences.

![](/docs/value-added/img/SPFindPeoplePicker2.png)
Loading

0 comments on commit 491f2d4

Please sign in to comment.