SPFx Extensions – ListView Command Set
In the last blog of this SharePoint Framework series our Sharepoint Development team talked about the Field Customizer extension. This blog is the last one in this series in which we are going to create, debug and deploy the ListView Command Set extension. SharePoint provides many of the OOTB commands available in the lists and libraries. But there can be some business requirements which requires the custom commands to be developed. The ListView Command Set extensions helps to meet the requirement for provisioning the custom commands for lists or libraries.
The ListView Command Sets can be installed at both site level and tenant level allowing user to select the availability of the commands to specific site or all the sites of a tenant.
Let’s create and deploy a custom ListView Command Set extension.
Table of Content
- Create a ListView Command Set Extension
- Debug the Extension
- Icons for the Commands
- Deploy the Extension
Create a ListView Command Set Extension
- Create and move to a project directory as we did in Field Customizer.
- Once moved into the project directory, run the yeoman command for creating a new SPFx solution.
- yo @microsoft/sharepoint
- Provide the project information as below when prompt.
- Solution Name – This will be the name of the solution of the extension.
- Baseline Target – Select SharePoint Online only (latest).
- Place for files – Select the current folder.
- Press Enter after selecting No (N) for the tenant admin to install extension on each site. Selecting No will remove the ‘SkipDeploymentFeature’ from the “package-solution.json” file which means SharePoint will not prompt to deploy the app to tenant when the app is deployed. If one is willing to install the extension at tenant level then it has to be selected as Yes (Y).
- Type of client-side component – Select Extension.
- Type of client-side extension – Select ListView Command Set.
- Field Customizer name – This will be the name for the command extension.
- Field Customizer description – Provide the appropriate description for the Command Set extension.
- Once all the details have been provided, the needed dependencies will be installed by yeoman. Wait till the yeoman scaffolding is finished. Once the scaffolding is completed, open the solution in Visual Studio Code using below command.
- Observe the solution structure. It is like the Field Customizer extension. There is one element.xml file, one .manifest.json file and one .ts file for the custom code.
- Open and observe the ListViewCommandSetCommandSet.manifest.json file which can be located at src ⇒ extensions ⇒ listViewCommandSet. The manifest file is similar as the Field Customizer, except it contains an additional node named as “Items” with default two commands. These commands are the actual commands which are going to be displayed in the list.
- The ListViewCommandSetCommandSet.ts file contains the code and it is located at src ⇒ extensions ⇒ listViewCommandSet. Open the ListViewCommandSetCommandSet.ts file.
- From the sp-listview-extensibility base package, BaseListViewCommandSet class is imported.
- The code file of ListView Command Set contains 3 main methods.
- onInit(): This method comes on the top of all the three methods. It is called to initialize the extension. A promise is returned to handle the asynchronous calls. The other methods are called once the promise is resolved. Any parameters that needs to be initialize can be added here.
- onListViewUpdated(): This method is executed after onInit(). It handles the rendering of the command sets. If one needs to specify certain condition to render the commands, that sort of logic can be written here. By default, it has the code for hiding the “Command One” until a list item is selected.
- onExecute(): This method is called as soon as the command is clicked. It handles the execution event of the command sets. When the solution is created, there will be a custom code to open a dialogue box on the click of commands.
Debug the Extension
In order to debug the extension, it is required to modify the serve.json file. Before moving forward please refer the debugging of an extension in our previous blog on Field Customizer.
- In serve.json file, refer to “Default” node in serveConfigurations. It contains below properties.
- pageUrl – In this field, provide the “AllItems.aspx” page URL of the target List.
- location – This field refers to the position of the Command Sets. We can choose the commands to reside in Command Bar, Context Menu or in both. By default, the Command Bar will be specified. One can change it according to the requirement.
- Now as per the above instruction, modify the serve.json file. The below image shows the updated file.
- Navigate to the list which is specified in serve.json for debugging. Insert some entries into it.
- It is necessary to install a developer certificate before starting the debug process. If it is already installed, then run the gulp-serve command in the console and allow the debug scripts in the browser. To know more about installing developer certificate and allowing the debug scripts, refer debugging steps from our previous Field Customizer
- Once the scripts are loaded successfully, it is noticed that one additional command named as “Command Two” will be visible at the command bar.
- Click on the command and it will open a dialogue with a message “This command is always visible”. Click Ok to close it.
- Now, select any of the list item. Notice that “Command One” is also visible at the command bar. This is because of the default code in the ListViewCommandSetCommandSet.ts file which renders this command conditionally when at least one item is selected in the list.
- Click on this command and it will also open a dialogue box with a message “One item is selected in the list”.
- It is noticed that both the command has some empty space at the beginning. That is because the CDN has not been provided for the icons. We will discuss the different approaches to set icons for the commands later in this blog.
- This was the basic example of ListView Command Set. Let’s modify the code to perform some additional task.
- Let’s create two commands to copy the student information from Students list to two different list i.e. Section A and Section B.
- The end-user will make the entries into Students list with information such as First Name, Last Name and Section.
- The admin can copy this raw information to classified list created for specific sections.
- Let’s modify the commands from manifest.json file.
- The below image shows the code of onListViewUpdated() We have specified the condition to make the commands available only for below conditions.
- When only single item is selected from the list.
- When the name of the list is Students.
- On the execution of command, we get the student information from the event.selectedRows and those values are passed to a method which pushes the information to specific list. Refer the below images for this operation.
Note: We have used the sp-pnp-js for inserting the details into the lists. So, to make use of the above code, it is required to install the npm package for sp-pnp-js. For more information, refer the below URL.
- The Student list contains two entries. If any of the item is selected, both the commands which were specified in manifest.json file will be visible on the command bar.
- Click on Copy to Section A command, it will copy the student information to list named “Section A”. Once the information is copied, it shows an alert dialog box with a success message.
- The values are reflected in the Section A list. As we have concatenated the Student’s First Name and Last Name, so the list shows the complete student name.
- The same output will be generated with command Copy to Section B with student information being copied to list named “Section B”.
Icons for the Commands
- The ListView Command set is the only type of extension in SharePoint Framewrk so far which provides to have custom icons. It allows users to select the custom icons for the commands so they can be distinguishable from the other OOTB commands.
- SPFX allows to define the icons in two ways as mentioned below:
- External icon image
- Base-64 encoded image
- External icon image – In order to use an external icon image, one needs to specify the external URL of that image in the manifest.json file under the specified command’s IconImageUrl property. Refer the below image in which the URL of images stored in Site Assets library is provided.
- Base-64 encoded image – Use of a base-64 encoded image is similar as the external image URL. Instead of the external URL just convert the image into base-64 code and paste that code in IconImageURL property of the command. Refer the below image in which the base-64 encoded image is provided.
There are multiple tools available online to convert the images to base-64 code.
Note: The command set uses base-64 code in an <img> tag. So, the format for the base-64 code must be as per the below.
e.g. data:image/png;base64, iVBORw0KGgoAAAANSUhEUgACAY…
Deploy the Extension
- The ListView Command Set extension can be deployed at site collection level and tenant level. If it is deployed at tenant level, then all the site collection in that tenant will have this command sets in lists or libraries based on type specified in element.xml file. Since, we have configured the project solution not to be deployed at the tenant level so let’s deploy the Command Set extension to site collection level.
- Open the elements.xml file located at sharepoint ⇒ assets ⇒ elements.xml in the solution folder. The below image shows the default content of element.xml. It contains several fields.
- Title – It is the title of the command set.
- RegistrationId – It is used to specify the type of list. In the below image, it is 100 which stands for Custom List. Multiple Custom Actions can be added in order to show the command sets for multiple types of list.
- RegistrationType – It specifies the type of app to which the command sets should be displayed. “List” is specified in the below image to show the command sets in Lists.
- Location – It is used to select where to display the command sets. By default, it is displayed at the command bar. Below are the values which can be used to specify the location of the command sets
- ListViewCommandSet.CommandBar – To register the command sets at Toolbar of the list.
- ListViewCommandSet.ContextMenu – To register the command sets at the context menu of the list.
- ListViewCommandSet – To register the command sets at both Toolbar and Context menu.
- The below image shows the updated element.xml file. Here, we have used two custom actions to make the commands available for both custom lists and libraries.
- Now prepare a solution package (.sppkg) file and deploy it in Apps library of App Catalog. Once the app is installed, add it into the site. Refer the deployment steps in our previous Field Customizer blog of this series for detailed steps for preparing and deploying the (.sppkg) app.
- Once the app is added into the site, navigate to any of the existing list or create a new list. The command sets will be visible at the command bar without any debug query parameters.
The ListView Command Set extension helps to build custom commands with ease. It provides the level of customization from selecting the Icons to selecting the location for the commands. The custom icons help to have the commands a unique look and feel. One can make the most out of this extension as per their requirements.