Inject a Style Sheet for a Specific K2 SmartForm

Introduction

 

There are a few different ways to impart style into K2 SmartForms. Perhaps the most straightforward way is by using the controls in Designer. Apart from the selection of a style sheet, these controls allow for limited manipulation of style elements on objects placed within a SmartForm. For greater style control, one must consult the style sheets that comprise the themes.

There is, however, another way: One can create a style sheet and implement it directly on a specific SmartForm. The method is hackish and not entirely comfortable architecturally, but it can be done.

This document will walk you through the method used for this “style sheet injection,” and how to deploy the style sheets to other servers.

 

SmartForms Themes

 

K2 uses themes to impart style on its SmartForms. Each form independently applies style to the Designer runtime and to the Runtime runtime, meaning a given style sheet must appear in both of these directories:


{drive letter}:\Program Files (X86)\K2 blackpearl\K2 SmartForms Designer\Styles\Themes\
{drive letter}:\Program Files (X86)\K2 blackpearl\K2 SmartForms Runtime\Styles\Themes\

In each directory, one will find a .css file and a subdirectory with the same name as the style sheet. The subdirectory contains resources like image files and so on to support the theme.

I am using that subdirectory to house the forms-specific style sheets, partly because I believe it has a better chance of not being overwritten by software updates and patches to the K2 blackpearl and K2 SmartForms platform.

 

SmartForms Style Sheets

 

It is possible to inject a style sheet into a K2 SmartForm by planting the .css file on the K2 server, then by creating an HTML literal control to inject the style into the form.

What You’ll Need:

  • Access to the K2 server using an account with access to the file system and permission to create, copy, paste, and rename files.
  • Permission to Remote Desktop onto the K2 server
  • Access to the K2 SmartForms Designer in the desired environment and knowledge of K2 SmartForms
  • The Style sheet, in the form of a .css file, that you want to inject, including it’s file name
  • Knowledge of HTML… or at least cutting and pasting.
  • The name of the Theme used by the project
  • The name of the SmartForm the new style will be injected into

 

Eight Easy Steps to Place the .CSS File on the K2 Server

 

  1. Get the CSS file onto the K2 server.


    PRO TIP: Assuming the CSS file is meant for a specific SmartForm, you might consider renaming the file using the name of the form it’s going to be used for. This should make file maintenance much easier for other technicians.

    If you do not have a means to get the .css file directly onto the K2 server (that is, the server that hosts K2 blackpearl), then you may need to copy the contents of the .css file and paste it into a new file on the K2 server over RDP:

    1. Open the .css file on your local machine. Note the name of the file because you’ll need it later.
    2. Copy the entire contents of the file to the clipboard. Using Ctrl+A, Ctrl+C is a good way to do this.
    3. Log into the K2 server over RDP
    4. Once logged in, open Notepad or some other editor
    5. Paste the content from the original file from the clipboard.
    6. Save the new file using the name from 1a.
  2.  

  3. Log into the K2 server if you haven’t already and open an Explorer window. Navigate to

    {drive letter}:\Program Files (X86)\K2 blackpearl\K2 SmartForms Designer\Styles\Themes\{Theme name}

    Where {drive letter} is the letter of the drive K2 blackpearl is installed on, and {Theme name} is the name of the theme used by the project, or at least the SmartForm.

  4. Create a folder named for the project. We want to make it obvious for other developers and infrastructure technicians that project material is located within.
  5. Create a folder named “Forms” inside the folder you just made. The idea behind the name is that this folder contains style for specific SmartForms.
  6. Drop the CSS file into the Forms folder.

    The final path for the style sheet file should be:

    {drive letter}:\Program Files (X86)\K2 blackpearl\K2 SmartForms Designer\Styles\Themes\{Theme name}\{Project name}\Forms\{File name}.css

  7. Be certain you’ve named everything sensibly. Go back and change anything you’re not comfortable with before finishing.
  8. Take note of the final path. You will need this for the code portion later.
  9. Log off/close your RDP session.

 

What Have You Done?

Nice job! So far, you’ve copied a CSS file onto the K2 server. In the next part, you’re going to identify this exact path in the SmartForms code. Everything must match for the style to be injected.

 

13 Short Steps to Create the Literal on the SmartForm

 

Follow these steps to create the means to inject the style sheet into your form.

  1. Open a browser on your local machine and navigate to the K2 SmartForms Designer for the desired environment. Log in using an account with permission to access the project and its forms.
  2. Check out and Edit the SmartForm the CSS will be injected into.
  3. Drag a Data Label from the Controls Pane onto an inconspicuous place on the SmartForm in the Forms Designer.
  4. Set some properties for the new Data Label as follows:
    1. Set the Data Type dropdownlist value to Text
    2. Set the Visible checkbox to checked
    3. Set the Enabled checkbox to checked
    4. Set the Literal checkbox to checked
    5. Click on the ellipses button at the right of the Expression dropdownlist control.

  5. In the Select an Expression form (that popped up when you clicked the ellipses), click Add to create a new expression.
  6. In the Edit Expression form (that popped up when you clicked the Add button), enter a name for the new expression at the top. Consider using something like “Add CSS for {Form Name} (where {Form Name} is the name of the form you’re working in). Because expressions can be used on multiple forms within a project, adding the form name to the expression name helps people to know where that code is used.
  7. The middle region of the Edit Expression form is for creation of the expression itself. The expression will be an HTML Link tag. Copy the code below onto your clipboard:


    <link rel="stylesheet" type="text/css" href="/Designer/Styles/Themes/{Theme name}/{Project name}/Forms/{File name}.css">

  8. Paste the code into an editor (Notepad will work just fine) and adjust the code to replicate the path used for placement of the file on the K2 server. The value {Theme name} should be the name of the theme used by the project, or at least the SmartForm; {Project name} should be the name of the project, and {File name} should be the name of the CSS file.

    This path from /Styles onward must duplicate the path you placed the CSS file in, or the style sheet will not get picked up by the SmartForm.
  9. Once your edits are completed, copy the completed code and paste it into the field in the middle region of the Edit Expression form. Even though only part of the code will appear in the Expression Details pane, the entire expression should appear in the Preview pane at bottom.

    If you need to make any small changes to the pasted code, you may edit it in the textbox in the Expression Details pane, though you may have to scroll a considerable amount to make your edit.

    Once you’re satisfied with the code, click OK in the lower right corner to close the Edit Expression form.
  10. Click OK in the lower right corner to close the Select an Expression form.
  11. The new expression should appear selected in the Properties pane of the Form Designer. Verify that it does, then click Finish in the lower right corner to close the Form Designer form.
  12. Check in the form you’ve just been editing.
  13. Run the form or click on the Design Time URL to load the form into the browser. You should be able to see your style changes once the form loads.

 

Now  What Have You Done?

Congratulations! You’ve just completed all of the steps needed to inject CSS into your SmartForm. Here’s what you actually did: You created HTML code that should appear in the source code of your form at the point where you placed it. This HTML code is a LINK tag that tells the HTML in your browser to render according to the instructions in the style sheet located at the path you specified in the href attribute. As long as the path you provided in the code matches the path where you placed the CSS on the K2 server, the instructions will be read by the SmartForm and applied after the HTML has been loaded into your browser.

 

What If I Need to Edit the Style?

 

You may edit the style sheet by connecting to the K2 server, navigating directly to the file and making edits in Notepad or some other editor. Once you save the file, you should be able to refresh your browser to see the changes you’ve made right away.

This is different behavior than is seen with edits to the theme style sheet, because the theme styles are likely loaded in the Application_Start() event handler. Use of an injected style sheet allows for just-in-time style changes and does not require an IISRESET on the K2 server after each change.

 

Deploy the CSS to Another Server

 

To move the CSS to another server, simply recreate the path you created on the “source” K2 server and drop the CSS file into the last folder. You will not need to reset IIS or make any database changes as long as the theme the SmartForm is using already exists there.

If the theme does not exist, you’ll have to create the theme before the CSS injection will work as expected.

Inject a Style Sheet for a Specific K2 SmartForm