SPJS-Lookup

Last updated: October 15, 2019.

What does it do?

This DFFS plugin is used to convert a single line of text field into a single choice dropdown select. The options for this select is the result of a query you build in the function call in the Custom JS tab in DFFS.

You can use it to query any list within the same site collection. You have an option to add new values to the “lookup list” on the fly, or to enter a value free hand.

This solution is compatible with SP2007, SP 2010, SP2013 and SP2016.

Example configuration

All configurations are placed in the Custom JS in DFFS backend. Here is an example, but please check the description of each option below.

spjs.lookup.init({
    "fieldToConvertToDropdown": [
        "Title"
    ],
    "listName": "ProjectList",
    "listBaseUrl": "/ProjectSite",
    "optTextFieldInternalName": "Title",
    "pipeDelimitedOptions": "false",
    "optValFieldInternalName": "ID",
    "orderBy": {
        "fin": "Title",
        "ascending": true
    },
    "clearInvalidSelections": true,
    "filterObj": {
        "on": false,
        "folder": "",
        "CAML": null,
        "fin": "",
        "isLookup": false,
        "operator": "",
        "filterVal": ""
    },
    "dropDownDefaultvalue": "",
    "allowBlank":true,
    "parseFunction": "",
    "addYouOwnValue": {
        "on": false,
        "linkText": "Write your own value"
    },
    "addToExternalList": {
        "on": false,
        "customFunction": null,
        "linkText": "Add new item",
        "saveNewItemText": "Save new item"
    },
    "debug": false,
    "customSort": ""
});

 fieldToConvertToDropdown

Type: array of strings

This is an array or FieldInternalNames of the fields in the current list that you want to convert to a dropdown. Specify multiple fields like this to have multiple fields show the same options based on one single query:

["FirstField","SecondField"]

listName

Type: string

This is the display name or the list GUID of the list you read the options from.

listBaseUrl

Type: string

This is the base URL of the list you read the options from. If the list is on the root site of your domain, the value will be an empty string like this

""

If it is on a managed path, it will be something like this:

"/sites/ProjectSite"

optTextFieldInternalName

Type: string

This is the FieldInternalName of the field that represents the options you want to show in the dropdown select.

pipeDelimitedOptions

Type: boolean

New in v1.1.10

Use if you have a lookup source list where the options are supplied as a pipe delimited list of  options you set this to true.

optValFieldInternalName

Type: string

This is the value attribute used for the options. The default value is the item ID, but if you for some reason want to use another value you can specify the FieldInternalName here.

orderBy [alias: sortFieldName]

Type: string or object

In previous versions this was this is the FieldInternalName of the field you want to sort the options by. Most likely the same as “optTextFieldInternalName”.

If you want to control the sort direction you can use an object like this:

{
    "fin": "Title",
    "ascending": true,
    "numeric": false,
}

fin is the FieldInternalName, and ascending is either true or false. The numeric option is new in v1.1.18 and lets you sort numerical and note alphabetical on number fields like ID or another number column.

filterObj

Type: object

This section is used to filter the datasource.

on

Type: boolean

true or false to tell if the options should be filtered. If false, all options will be shown.

folder

Type: string

Here you can provide a relative URL to a folder like this:

/Sites/MySite/Lists/MyList/MyFolder/MySubFolder

CAML

Type: string

Here you can provide the full CAML query to filter by. If this is left as null, the other options below will take effect.

fin

Type: string

The FieldInternal name you want to filter on.

isLookup

Type: boolean

true or false. If you filter by a text value, use false. If you filter by an ID in a lookup field, set it as true.

operator

Type: string

Use anu valid CAML operator like “Eq”, “Neq”, “BeginsWith” or “Contains”.

filterVal

Type: string

This is the value you want to filter by.

dropDownDefaultvalue

Type: string or object

This is the default value in the dropdown when it has not been selected.

If you have a MUI environment you can supply the value like this:

{
    "default": "Fall back for any language not specifically added",
    "1044": "Norwegian label"
    "1031": "German label"
 }

allowBlank

Type: boolean

New in v1.1.12

Set this to true to allow setting the field back to blank. This will include the dropDownDefaultvalue option at the top of the list of options.

parseFunction

Type: string

If you need to manipulate the values that populate the dropdown you can write your own function. Use the name of the function in quotes. The value will be passed as an argument to the function, and you must return the new string value from the custom function.

addYouOwnValue

Type: object

on

Type: boolean

This controls whether or not to show a link to “kill” the dropdown and show the underlaying text field.

linkText

Type: string or object

This is text on the add you own value-link.

If you have a MUI environment you can supply the value like this:

{
    "default": "Fall back for any language not specifically added",
    "1044": "Norwegian label"
    "1031": "German label"
 }

addToExternalList

Type: object

on

Type: boolean

This controls whether or not to show a link to add an item to the list you are pulling the options from.

customFunction

Type: string

If you want to override the built “addToExternalList” function, add your custom function name here like this: “myAddListItemFunc”.

The function itself must be present in the page, and it will get the full “argObj” passed to it as a parameter.

linkText

Type: string or object

The text on the that initiates the “addToExternalList” function.

If you have a MUI environment you can supply the value like this:

{
    "default": "Fall back for any language not specifically added",
    "1044": "Norwegian label"
    "1031": "German label"
 }

saveNewItemText

Type: string or object

The text on the “save” link.

If you have a MUI environment you can supply the value like this:

{
    "default": "Fall back for any language not specifically added",
    "1044": "Norwegian label"
    "1031": "German label"
 }

debug

Type: boolean

If true, the underlaying text field will not be hidden, and you will see a yellow information panel in the field revealing the query, how many items was pulled back and the configuration object.

customSort

Type: function

New in v1.1.14

If you like to override the default alphabetical sort order you can supply your own function in this parameter. This sort function example sorts values that contains numbered options from 1-10. The default alphabetical sort order would sort like this: 1, 10, 2, 3 etc., but now it will show 1, 2, 3 and so on:

spjs.lookup.init({
"fieldToConvertToDropdown": [
"Title"
], 
...
...
"customSort":function (a, b) {
var aa = a.text, bb = b.text;
if(aa.split(".")[0] < 10){
aa = "0"+ aa;
}
if(bb.split(".")[0] < 10){
bb = "0"+ bb;
}
if (aa < bb) {
return -1;
}
if (aa > bb) {
return 1;
}
return 0;
}
});

Setting a value in a field with this solution activated

To set the value of a field when using this solution, use code like this:

spjs.lookup.setValue("FieldInternalName_of_your_field","The value you want to set");