I have been asked several times on how to create custom K2 smartforms control recently and I will like to document down the basics in a few posts.

Prerequisites

So prior to starting the development, we need the following things to be in place:

1. K2 blackpearl + K2 smartforms setup. You need the full setup, not just the client components as you will need to deploy and test the control. Good thing here is that the K2 developer licence is free, so long you have a valid server licence.
2. Microsoft Visual Studio. This could be VS 2010, 2012 or 2013. You will need the VS component installed along with the K2 blackpearl setup. Please also make sure that the VS version you are using is supported by the version of K2 blackpearl you are using. Check the compatibility matrix at http://help.k2.com/blackpearl/support-matrix#VisualStudio.

Other required components like .NET Framework etc would have been installed along with your K2 blackpearl and K2 smartforms setup, so I won’t be covering them here.

How to create custom K2 smartforms control – Part 1

In this post, I will only touch on creating and deploying a new custom K2 smartforms control. The in-depth details will be covered in subsequent posts.

1. Download and Install the Visual Studio extension

1. Download the Visual Studio Templates for K2 blackpearl extensions from K2 community site. For obvious reasons, please select based on the Visual Studio version you will be using.
2. Double click on the downloaded extension.

   

3. When the VSIX Installer dialog appears, click on Install.

   

4. Once the extension is installer is completed, you will see the following screen. Click Close.

   

    

2. Create custom K2 smartforms control project

1. Start your Visual Studio and create a new project.
2. In the New Projects dialog’s left panel, you will see a tree menu. Select the node Installed > Templates > K2 > K2 Extensions.
3. In the content area, you will see the Custom SmartForm Control Project. Select it and click OK.

   

4. When the project gets created, a browser window will pop up. The page will give you basic information about this control and how to go about developing and deploying it. You can close this browser now.
5. In the Visual Studio’s Solution Explorer, you will see the default project setup.

   

6. Notice that in the References, we have SourceCode.Form.Client, SourceCode.Forms.Controls.Web.SDK and SouceCode.Forms.Controls.Web.Shared assemblies. These assemblies are required for the custom K2 smartforms control development. If ever they are missing or has missing references, you can re-add them from the K2 smartforms runtime folders – “C:\Program Files (x86)\K2 blackpearl\K2 smartforms Runtime\bin”.
7. If all your assemblies are required to use a specific strong named key, replace the CustomControlSigningKey.snk or update the project’s properties as required.

3. Add a K2 smartforms control to the project

1. To add a new control, right click on the project name in the Solution Explorer, select Add follow by New Item.

   

2. In the Add New Item dialog, select SmartForms Ajax control item from the K2 Extensions menu. Click Add.

   

   A little details about each of the template:

   SmartForms Basic Server Control Item: This is a template to create a ASP.NET print only control. It does not have any client side jQuery functions.

   SmartForms Basic Client Control Item: This is a template to create a control that has jQuery client side functions.

   SmartForms Ajax Control Item: As the name suggests, this template creates a control that allows client side query to the server.

   Anyway, these are just templates and the important thing is how to customise it to your needs.

3. After the item has been added, you will see a new folder in your project’s Solution Explorer.

   

   A quick high level description of what these files are for:

   _Control.cs file: This is the main body of your control. It defines the CSS, javascripts, ajax handler and prints the look and feel of your custom control.

   _Definition.xml: This is the control configuration information that will define the name, events, methods, properties and will be saved into the K2 DB’s From.ControlType table.

   _Handler.cs: This file is only required if you need ajax calls. It is your standard ajax handler class.

   _Script.js: This is your control’s jQuery class. Once the control has been load on the browser, this is where all the events and methods execution will occur.

4. I won’t be covering the details of development in this post, so let’s just deploy the control and see the default codes in action.

4. Deploy your custom K2 smartforms control

1. Firstly, compile your project in Visual Studio using the Debug configuration.
2. Open a Command Prompt and navigate to your bin\debug folder of your project.

   

3. In the directory, you will find 2 .bat files namely, RegisterCustomContro.bat and DeRegisterCustomControl.bat. As the names suggest, the RegisterCustomControl.bat will copy the DLL to the Designer (C:\Program Files (x86)\K2 blackpearl\K2 smartforms Designer\bin) and Runtime (C:\Program Files (x86)\K2 blackpearl\K2 smartforms Runtime\bin) site’s bin folder and add the control’s config into K2 DB. The DeRegisterCustomControl.bat will remove the control from K2 DB only.
4. So now, go ahead and execute RegisterCustomControl.bat.

   

   

5. And you are done!

5. Test your custom K2 smartforms control!

1. Open your K2 Designer site, create a new View and find the control on your Controls panel.

   

2. Add your custom K2 smartforms control to your view.

   

3. Click on Finish and run the view.

   

4. As the display says so, click on it to see it in action!

   

Conclusion

So in the above post, we have learned how to get the template, install, create a new project, add a new control, deploy and test the control. As you can see, the control template comes in different flavors (SmartForms Basic Server Control Item, SmartForms Basic Client Control Item and SmartForms Ajax Control Item) and they have sample codes ready to run immediately. You should try creating all 3 templates and look at how the internal works. For now, I’ll be concluding here and go in-depth to talk about the various customisation in the next post.

Have fun!

• Author
• Recent Posts

Ji Kai

Director / Principal Consultant at Alrighty Labs Pte. Ltd.

Ji Kai is the Director and Principal Consultant of Alrighty Labs Pte. Ltd. He has over 10 years of experience in solution designing, consulting and management of software development projects in both private and public sectors. His primary responsibility is to take lead in customer engagements and use his expertise in K2 technologies to assist customers to design successful business process applications. In addition, he has proven past records of leading the successful delivery of complex business process applications on K2 and Microsoft technologies.

Linkedin

Latest posts by Ji Kai (see all)

• Multiple records inserted with RuntimeListViewRowCount option - 30 May 2017
• Friendly Error Message on K2 smartforms - 04 May 2017
• Add company logo and change K2 login form descriptions - 02 Aug 2016