Building the Hello World SmartForm

This document contains the step-by-step instructions to build the simple Hello World K2 smartform. If required, please refer to the application design topic for an overview of the SmartForm to understand what the form does.

In Step 1, you will prepare the K2 category system with folders to store your SmartForm's components. Creating folders is not required, but it is recommended because using a logical folder structure will help to keep the SmartForms environment organized. In Step 2, you are introduced to SmartForms by building a simple view that contains some formatting and controls, and executes basic rules. In Step 3, you will build a form to contain your view and in Step 4, you will test your new SmartForm.

If you are using a virtual environment provided by K2, you may log into your environment using the following credentials:
User Name: Denallix\Administrator
Password: K2pass!

The first step in your application is to create the categories that will house your form and view. You can think of categories as folders that contain things like forms, views, SmartObjects and workflows. While it is not necessary to group elements into folders like you do here, it does help to keep the similar elements organized and grouped, especially for larger applications that may contain several SmartObjects, views, forms and workflows.

Step 1 Tasks

  1. Launch K2 Designer, then create a new category under All Items called
    K2 Learning
  2. Create a new category under K2 Learning called
    Hello World
  3. Create two new categories under Hello World called
    Forms
    Views
  1. Launch K2 Designer (Start > All Programs > K2 blackpearl > K2 Designer)
    (If the link is not listed in your start menu, contact your K2 administrator to obtain the designer URL.)
  2. In this step you will create the main category for your application. Right-click All Items and select New Category. Name the new category
    K2 Learning
    3. If you work through additional tutorials, you can create those application categories all under the K2 Learning category to keep them organized. If you are sharing this environment with others, you can add your name to the category name to distinguish it from other user's tutorials.

  3. Create a new category under K2 Learning and name it
    Hello World
  4. Create two new categories under Hello World and name them
    Forms
    Views

    5. Your category folders should look like the image below.

STEP 1 REVIEW

In this preliminary step, you created categories, or folders, for the elements of your Hello World application. Categories are not required, but they do help you keep things neat and tidy, especially as you build larger applications that contain multiple forms, views, SmartObjects and workflows. In K2 terms, application refers to the all of the elements that make up a single project.

You will begin your form and view construction by building your Hello World view. This view will contain a label, a text box and a button control. The button control will be configured with a rule to show a message after it has been clicked. Remember that views are logical groups of content. One form might contain several views. Views by themselves cannot be accessed by users; they must be contained within a form for your users to access and submit them.

Step 2 Tasks

  1. In K2 Designer, create a new item view and name it
    Hello World
  2. On the Create Layout Table Only configuration screen, set the number of columns to
    2
    and the number of rows to
    2

    Add a label control to the first table cell and change the name to
    Name Label
    then change the text to
    Enter your name:

    Add a text box control to the top row, second table cell and name it
    Name Text Box
    then change the width of the text box control to
    200px
  3. Add a button control to the second row, first table cell and name it
    Submit Button
    then change the text to
    Say Hi!
  4. Adjust the width of the table’s first column so that it better aligns with the Enter your name label.
  5. Add a rule that fires off when the submit button is clicked. Add a condition to require the Name Text Box control. Add an action to show a message after the submit button is clicked. Configure the message as shown below using the Name Text Box control and the Current Date system value in the body.

  6. Run the Hello World view and confirm the message box appears with the name entered in the name text box and current date after the submit button is clicked.
  1. Right-click the Views category and select New View.

  2. When the view home page opens, click Next (only if necessary; you may land automatically on the General settings page). Name the new view
    Hello World
    and confirm Item View is selected for the view type, then click Next. (No changes are necessary for the Data Source property.)

  3. On the layout screen, click Create Layout Table Only.
  4. Set the number of columns to
    2
    and the number of rows to
    2
    then click OK.
  5. Expand the Controls pane, then drag a Label control into the first table cell. Click the label control once to highlight it. In the Properties pane change the Name to
    Name Label
    then change the Text to
    Enter your name:
    6. The name property in the properties pane refers to the control's identity. K2 references controls by their name value. The text entry is what the user sees, it is the control's display value.

  6. Back in the Controls pane, drag a Text Box control into the second table cell. Click to highlight the text box. From the Properties pane, change the Name to
    Name Text Box
    then confirm the Text property is empty. You do not need a text box display value for this exercise.
  7. Change the Width to
    200px

  8. From the Controls pane, drag a Button control into the first table cell on the second row. Click to highlight the button control. In the Properties pane, change the Name to
    Submit Button
    and change the Text to
    Say Hi!

    9. In the next step, you are going to adjust the first column width in your layout table so that it aligns with your label and button control.

  9. Change the width of the table’s first column by dragging the center column line to the left so that it aligns with the Enter your name label.

    10. Now that you’ve created your basic view and have applied some formatting to the name text box width and table column width, you are ready to add a rule to the submit button. You will add a condition to the rule that essentially turns the name text box into a required field, then add an action that shows the user a message after they have clicked the submit button.

    Rules contain events, conditions and actions. An event is when something occurs (such as a button clicked). A condition checks to see if some criteria has been met (such as required form fields) and an action says do something if the event and conditions are met (such as start a workflow or show a message to the user).

    You can add rules to forms, views and controls. To add a rule to a form or view, access the rules screen via the rules button found at the top of your screen in the breadcrumb bar. To add a rule to a control, use the Rules tab found next to the Properties tab for that control.
  10. You want the rule to fire when the submit button has been clicked, so you will apply the rule directly to the submit button. Click the Say Hi! button once to highlight it. Click the control’s Rules tab at the bottom of the Properties pane, then click Add Rule.

    11. The first step is to add the event. Recall that an event is when something happens. In your case, it is when the submit button is clicked.

    In the Rule Designer, notice there are two panes. On the left side are the events, conditions and actions K2 offers out-of-the-box. Navigate to each via the tabs at the bottom of the left-side pane. On the right side is the rule definition pane. This is where you define the conditions and actions for each rule. The rule you are currently working with, When the control is Clicked, is shown at the top of the rule definition pane.

    Notice just below the rule title, K2 has added the base rule. Because you had the submit button highlighted when you added the rule, K2 added the default method (clicked) for you.

    Now that you have added the event (when the submit button is clicked) you will add a condition. Recall that a condition is if some criteria has been met. You add the condition next because if the condition is not met, you don't want the action to fire. In your case, the condition will specify that the Name Text Box must contain a value. If it does not contain a value, then the condition is false and the action should not take place. You will add the action to show the user a message in later steps.

  11. Click the Conditions tab. Scroll down through the available conditions until you reach the Validation heading. Click once on the View passes validation condition to add it to the When the control Clicked rule. Click the (configure) link.

  12. Check the box to require the Name Text Box and click OK.

    13. Now that you’ve configured a condition to require the Name Text Box, the second configuration to your rule is to add an action to show a message. Begin by selecting the Actions tab.

    In the previous step, you scrolled through the conditions until you found the validation condition. As you work with rules, you will become more familiar with the terminology. Use the search box to quickly locate the definition you want to add.

  13. Enter
    message
    in the search box and click the spyglass icon.
  14. Click once on the Show a message action to add it to the rule definition pane. Click the (configure) link.

    15. In this next step, you will configure the message you want to show your user. You will be using properties found in the context browser. In the steps below, you will be dragging the Name Text Box into your message. At runtime, this value will be replaced by the name entered into the form field. You will also add the current date to your message. The Current Date system value will be replaced by the actual current date.

    Context browser properties are dynamic, in that at runtime (the live content that the user will see), the properties are replaced by the actual form field or system values. Context browser properties are displayed as a green block of text, so that you can easily find them in your content. Context browser properties are a powerful and convenient mechanism for customizing your workflow content.
  15. Now you will configure the content of the message shown to the user. See the screenshot below this step for an example of what the message configuration should look like.
    For the Title enter
    Hello World
    The title is what appears in the black bar shown below.

    For the Heading enter
    Hi!
    The heading appears at the top of your message.

    For the Body enter
    Hello [Name Text Box]
    and from the Context Browser, expand the Hello World view, then Controls. Append the Name Text Box control to the end of the line (replacing [Name Text Box] with the context browser property).

    After the Name Text Box, enter two new lines and enter
    Today is:
    then drag the Current Date from the System Values after the Today Is: text. At runtime, the current date will be replaced by the actual date from the server.


  16. Click OK to close the message configuration screen and OK once again to close the rule designer. Click Finish (located just below the Properties pane) to close the view designer.

  17. The last step is to test the view. With the Hello World view highlighted, click Run from the Properties pane.

  18. Enter your name and click Say Hi!. Confirm the confirmation message comes up with your name and today’s date.

    19. At this stage, you are testing your view by running it from within K2 Designer. Testing from with the designer provides a convenient method for testing view functionality. However, you should note that other users cannot access or submit views from with the designer. Users can only access forms and in the next section, you will create a form, then add this view to the form. By doing so, your users will be able to access and submit the form containing your view.

  19. Click the Hello World view title once again in the category browser to close the test run.
STEP 2 REVIEW

In Step 2 you created your Hello World view. You added a label control, a text box control and a button control. You formatted your layout by setting the width of the text box control and by adjusting the column width for the view layout table. You then added a rule that will fire off when the submit button is clicked. You added a condition to require the Name Text Box and an action to show a message if the condition was met.

In Step 2, you created and tested the Hello World view from within K2 Designer. Views must be contained within a form for your users to be able to access and submit them. In Step 3, you will build a form for your Hello World view.

Step 3 Tasks

  1. Generate a form from the Hello World view and name it
    Hello World Form
  2. Change the view title to
    Hello World View
    and the form’s width to
    60%
  1. Right-click the Hello World view title from the category browser and select Generate Forms.
    (You can design your form manually, however, generating a form from a view automatically adds the associated view to the design canvas, saving you a step.)

  2. Change the Form Name to
    Hello World Form
    then click the ellipses to the right of the Category field and select the Forms category from the category browser. Click OK and OK again.
    3. Because you generated the form directly from the view, K2 automatically placed the form in the views category. You can easily move elements around into the categories that make sense to keep things organized, if needed.

  3. From the category browser, highlight the new Hello World Form and click Edit.

  4. Double-click the (Enter View Title) title bar and change it to
    Hello World View

    5. Your simple form (with only one view) probably doesn't need a view title, but when you start building more complex forms with multiple views, giving the views meaningful titles can help your user navigate your form elements.

    SmartForms are browser-based forms. If you open this form in a browser right now, it will stretch the width of the browser. Because this is a small form, you will adjust the form’s width so that it is easier to use.

  5. Click anywhere within the form canvas, but not within the view area. In the Properties pane, change the form’s Width to
    60%
    then click Finish to save your form and exit. The finish button is located just below the Properties pane.

    6. Your final task for Step 3 is to check in the form. Checking in views and forms publishes them to the K2 server, making them available for use by your users. If you need to make a change to either your form or view, you must first check them out, make your edits, then check them back in again to expose the changes to your users. You can check in views and forms individually, or just check in the form, which will include any associated views.

  6. Right-click the Hello World Form and select Check In. (If you get a message about checking in associated views, click OK to continue.)
STEP 3 REVIEW

In Step 3 you generated a form from the Hello World view. You formatted the form by changing the default title bar of the added view and by setting the form width. Your form is now ready to be exposed to your users, which you will test in the next step.

In Step 4, you will test your form using an internal link and an external link. The internal link opens and processes the form from within K2 Designer. The external link opens and processes the form from the K2 Runtime server. To link to a form from a web page, use the Runtime URL.

Step 4 Tasks

  1. First test the form using the Run link found in the Properties pane near the lower half of the central pane.
  2. Next, test the form using the Runtime URL link found in the Properties pane near the upper half of the central pane.

    3. In both cases, confirm the form submitted and the Name Text Box and today’s date values where displayed in the confirmation message.

  1. From the category browser, highlight the Hello World Form and click the Run link found near the bottom of the central pane. In this step, you are testing the form from within K2 Designer. This is the same step you took to test your view from within K2 Designer. Once again, this form cannot be accessed or submitted by your users using this run method. The advantage to testing your form from within K2 Designer is convenience to you, as the designer. It is a quick-test to make sure the format and functionality is what you want, before moving on to the browser-based form.

    2. Enter a name into the Name Text Box and submit the form. Confirm the confirmation message has the name entered along with today’s date.

  2. Click on the Hello World Form title once again in the category browser. This closes the test form and returns you to the Properties pane. Notice the Design Time URL and the Runtime URL links that appear in the Properties pane (in the upper half of the central pane). Click on Runtime URL.
    Note: you may need to click the Show properties arrow to show the form URLs.
    3. The Runtime URL is the external link to your live form. This is the URL to use for linking to the SmartForm from other sources, for example, a web page. Provide the Runtime URL link to your users for access to the SmartForm.

  3. The form now opens in a browser. Enter a name into the Name Text Box and submit the form. Confirm the confirmation message has the name entered along with today’s date. Close the confirmation message and close the browser.
STEP 4 REVIEW

In Step 4 you tested the Hello World form both internally and externally. You used the Run link to test the form and observed how it opened and processed from within K2 Designer itself. You then used the Runtime URL link to open and submit your form from an external browser. What's key here is that forms and views must be checked in before your users can access them and users can only access forms from a Runtime URL link. If you need to make a change to the form or view, you must check it out, make your changes, then check it back in. This publishes the form or view to the K2 server. Users cannot see any changes until the forms and views are checked back in.

Congratulations on building your very first SmartForm! You should now understand the basics behind views, forms, controls and rules and how these are used to assemble SmartForms. In other tutorials, you will expand on the data, forms, workflows and reports components to better understand how they are used together to implement K2 applications.

Challenge steps will test your knowledge by providing high-level guidance but no step-by-step breakdown. In this challenge step, you will create a rule so that the Name Text Box is automatically populated with the current user's name when the form is opened.

Challenge 1 Tasks

  1. Check out and edit the Hello World Form.
  2. Edit the When the Form is Initializing rule.

  3. Add a Transfer data action and then configure it to populate the Name Text Box with the current user's Display Name.

  4. Check in the form, then run the form and confirm that the username is automatically entered when the form is opened.
  5. Ask another user to open the form, then confirm that the display name is changed for that user.
    If you are using a K2-provided virtual machine for this tutorial, you can launch another user's browser with the User Shortcuts on the toolbar.