Introduction

 

In this document, you will learn about the K2 SmartForms Picture control and how it operates. Finally, you will gain some understanding of how to use it in an advanced scenario involving its .NET Generic Handler, JavaScript and jQuery, and a Data Label control acting as a literal.

The K2 SmartForms Picture Control is comprised of:

• The SmartForms Picture control
• A table in the K2 database
• A .NET Generic Handler

Let’s talk about each of these.

The SmartForms Picture Control

The Picture control will allow you to add, delete, and edit images, as well as select them for placement on a SmartForm or SmartForms View. Many images are provided “out of the box,” but the control offers the ability to add and modify your own images.

Adding a Picture

Adding an image will require of the user:

• An account with permission to access the K2 SmartForms Designer in the desired environment
• A picture to upload
• A name to use to describe the picture
• A description, primarily to aid other developers in understanding what the image is for or how it is used (optional; limited to 100 characters).

Images are not separated by project or by user; they’re all stored in the same location and are available in the Designer for use in all projects for that environment. A good practice might be to use names and/or descriptions that include the project name.

As you can see from the Upload a Picture form (below), the user is asked to provide text for the name and description of the file, and to attach the image to the form.

Editing a Picture

Editing a picture means you can modify the name, description, or replace the image file for a selected record.

There are a couple of occasions where editing an image can provide value.
The first, and simplest, is to add or modify descriptions to help other developers more easily identify how the image is used.

Another such occasion is when an image needs to be replaced with an updated version. For example, you might upload an initial version of an image file during early development of a given project. The stakeholders might suggest changes to the image, prompting the creation of a version 2, meant to replace the original. In this case, you could either add the version 2 as a new record, or edit the old record, replacing the original image with version 2. This method can have some advantages over adding a new record because the ID of the original is retained.

PRO TIP: Any time you upload a new image to replace an old one, reset IIS to clear the cache and ensure the new image gets served in the SmartForms.

The K2 Database Table

The file system on the server hosting K2 blackpearl is not used to house the images uploaded via the Picture control. The SmartForms control uploads each image to the FormsImage table in the K2 database.

As you can see from the screenshot that follows, the database table assigns an ID to the record in addition to containing the image, name and description provided by the user through the Picture control.

In some applications, the ID associated with the image becomes very important because it allows an image to be specified and returned by a generic handler.

The .NET Generic Handler

Used in more advanced applications of the Picture control, K2 ships with a generic handler which can be used to render a picture when the ID from the FormsImage database table is provided as input.

Use Case: Adding a Background Image to an HTML Element

The .NET Generic Handler can be used very effectively to add a background image to a form element, like a table cell.

In plain ol’ HTML, one can easily add a background image to an element through a CSS construct like this (pardon the modified style tags):


*style type="text/css"*
   #myTable td {background: url(‘myImage.png’), fixed repeat right;}
*/style*


The code above declares a style block, identifies it as CSS, and then specifies that all cells of a table with the ID “myTable” should use the background image “myImage.png” placed in a fixed position and allowed to repeat, starting at the right side of the cell.

In K2 SmartForms, we can achieve the same by using JavaScript and jQuery to inject the CSS at design-time. Though this might seem a bit complex, the basic steps are:

• Create a hidden literal someplace on the SmartForm or SmartForms View
• Create a jQuery statement as an expression to be invoked by the literal
• Save and check in the Form/View and run it.

Create the Literal

Drag a Data Label control onto your SmartForm or SmartForms View, and set its properties as follows:

• Ensure the Data Type is set to Text
• Ensure the Visible checkbox is cleared
• Ensure the Enabled checkbox is checked
• Ensure the Literal checkbox is checked

Finally, click the button beside the Expression dropdownlist to create a new expression.

Create the Expression

Give your new expression a name, and add the JavaScript and jQuery code inside the expression details.

PRO TIP: It’s easier to create the code inside a proper editor and paste it into the expression than try to type it all in. As you can see from the image above, the editor window offers only a single line with a defined length as an input field.

The preview pane of the Expression form pictured above contains this code (pardon the modified “script” tags):


*script language="javascript"* jQuery(document).ready(function(){
$("#32af6f55-4da7-4d1a-94d2-9fad2bd5931c").css("background","url('/Designer/Image.ashx?imID=107') fixed repeat right");
$("#79a50abb-9cbd-48ea-b34d-82b2122e3d0a").css("background","url('/Designer/Image.ashx?imID=107') fixed repeat right");
$("#f55dead8-dce3-4a7f-8731-edb411560933").css("background","url('/Designer/Image.ashx?imID=107') fixed repeat right");
});
*/script*



The code contains three statements which assign an image to the background property of each specific element (which happen to be table cells), and specify the placement of each (“fixed repeat right”).

PRO TIP: K2 SmartForms will generate the ID’s of each of the elements as GUIDs. To refer to specific elements, you must use the GUIDs you find when looking at the source code of the rendered SmartForm. These GUIDs will match in the design time and runtime.

In each case, the image is identified by a URL – and the URL points to a .NET Generic Handler control called Image.ashx. The URL includes a key-value pair on the query string which identifies the specific image to be returned by using the ID found in the FormsImage table of the K2 database: specifically, the image with ID 107. Notice this ID value is hard-coded.


url('/Designer/Image.ashx?imID=107')

The code, when exposed through a hidden literal control, will render the background image in each of the table cells.

PRO TIP: If you examine the K2 web in IIS, you’ll notice /Designer is a web application of its own. This actually points to the /K2 blackpearl/K2 Smartforms Designer/ directory of the server.

Here’s another example of using a picture in a hidden literal. In this case, I wanted to display either of two images in a list control column based on a YesNo value. Here is the expression I built, which works in K2 SmartForms 4.7:

Implement the Code

Finally, test your code by following the steps below.

• Click OK on the expression editor form.
• Click OK on the expression selection form.
• Once returned to your SmartForm or SmartForm View, ensure the name of your new expression is selected in the properties of the Data Label control you created.
• Once returned to the View Designer, click Finish to save and close your form.
• Once returned to the form properties, Check in your form from the menu options in the bottom pane.
• Run your form either by selecting the design-time link in the top pane, or by clicking Run in the bottom pane.

You may have to edit your expression to get it working as it should. Getting to it is rather a tedious process, but once it’s working you shouldn’t have to touch it again, BUT — one case in which you might have to edit it is if an updated picture is added to the Picture control instead of editing the original, because adding the updated picture will generate a new ID, meaning the hard-coded value in the URL of your CSS command will need to be updated.