Skip to content

Form Controls & Commands

This Library exposes some useful functionality with regards to a Form Model:

  • Information about the Form itself (whether it is open as a Modal, whether it is dirty or not and more)
  • Useful functions to Commit Files, Show Messages, Close the Form or Redirect to a different URL
  • A FormControls namespace with which you can access some Controls of your Form and act upon them

Commands

The Commands documented in this section can be ran without any namespace or underlying control, in a Form Model:

  • Inside a Controller Action
  • Inside a Logic Item (Conditional Formatting, Calculated Expression, Data Validation)

Important

You can not execute these commands outside a Form Model (i.e. in a Class Operation), as they refer to the opened Form alone.

IsModal()

Description Can be used to check whether the current form is a Modal or not:

  • true means that the current form is running inside a floating div, on top of another Form
  • false means that the current form is a standalone form - the only one shown in your browser at that time

Return Type : bool

Static : Yes

Syntax

/*
    A Calculated Expression that changes the label of a "Close/Exit" button
    depending on the type of Form. If it's a Modal, then the Button will say 
    "Close Form". If it is a standalone Form, the button will say "Exit".
*/
function string CalculatedExpression()
{
    if (IsModal()) { 
        return "Close Form";
    }
    else { 
        return "Exit";
    }
}

RedirectToUrl(string)

Description Instructs the browser to open another page at a given URL, in the current window.

Return Type : void

Static : Yes

Parameters

Name Data Type Description
url string The URL of the page to be redirected to. Can be any page inside your Application, or an external one.

Syntax

function void GoogleButtonPressed()
{
    RedirectToUrl("https://www.google.com");
}   

function void SignIn()
{
    bool success = AppLib.Security.SignInUser(Model.UserNameTextBox, Model.PasswordTextBox, Model.RememberMeCB);

    if !success {
        ShowMessage(LocalResources.SignInFailed, AppLib.MessageType.Error);
        return;
    }

    string returnUrl = WebLib.Request.GetQueryStringParameter("returnUrl");

    //Redirect to the URL the user typed before Signin In
    if (!string.IsNullOrWhiteSpace(returnUrl)) {
        RedirectToUrl(CommonLib.Utilities.ResolveClientURL(returnUrl));
    }
    //Or, redirect (by calling the Render action of the HomePage Controller) to the HomePage
    else {
        FormModels.HomePage.Controller.Render.Execute();
    }
}

ShowMessage(string)

Description This function displays a Modal inside your form (a small div at its center), that shows the given message.

The message displayed has the Success style (see the next function for more information)

Return Type : void

Static : Yes

Parameters

Name Data Type Description
message string The message to be displayed. Can be a clear string or a Localization Resource

Syntax

    ShowMessage("Your E-Mail has been successfully sent. Thank you!");

    ShowMessage(LocalResources.RES_CUSTOM_EMAIL_SUCCESSFULLY_SENT);                    

Attention

If you have multiple ShowMessage() commands, one after the other (just like in the example shown above, that, strictly speaking, is incorrect), you will see only the last message displayed.

The reason behind this is that the messages displayed via ShowMessage() are asynchronous and very fast. Meaning that if you have two ShowMessage() commands, the first message will be displayed too quickly for you to see, leaving you with the second one.

ShowMessage(string, AppLib.MessageType)

Description This function displays a Modal inside your form (a small div at its center), that shows the given message, styled accordingly to the provided AppLib.MessageType type of message.

Return Type : void

Static : Yes

Parameters

Name Data Type Description
message string The message to be displayed. Can be a clear string or a Localization Resource
type AppLib.MessageType The type of Message presented (Info, Success, Error, Warning)

Syntax

Command Example
ShowMessage("This is an Info message", AppLib.MessageType.Info); Show Info Message
ShowMessage("This is a Warning.", AppLib.MessageType.Warning); Show Warning Message
ShowMessage("This is an Error.", AppLib.MessageType.Error); Show Error Message
ShowMessage("This is a Success message.", AppLib.MessageType.Success); Show Success Message

Attention

If you have multiple ShowMessage() commands, one after the other (just like in the example shown above, that, strictly speaking, is incorrect), you will see only the last message displayed.

The reason behind this is that the messages displayed via ShowMessage() are asynchronous and very fast. Meaning that if you have two ShowMessage() commands, the first message will be displayed too quickly for you to see, leaving you with the second one.

ShowMessage(string, AppLib.MessageType, string)

Description Displays a Message following the operation described in ShowMessage(string, AppLib.MessageType) with the following difference: the OK button does not close the Message, but navigates the user to a specified URL.

Return Type : void

Static : Yes

Parameters

Name Data Type Description
message string The message to be displayed. Can be a clear string or a Localization Resource
type AppLib.MessageType The type of Message presented (Info, Success, Error, Warning)
redirectUrl string The page to be redirected to, as soon as the user presses the OK button in the message

Syntax

ShowMessage("Looks like you have no idea what you are doing. Let me take you to the docs...", AppLib.MessageType.Warning, "http://docs.zappdev.com/");

CloseForm()

Description Closes the current Form and navigates the user to his/her last opened Form.

Return Type : void

Static : Yes

Syntax

function void DeleteProduct() {
    if(Model.Product.CanBeDeleted()){
        Model.Product.Delete();
        Model.Title = LocalResources.RES_PAGETITLE_DeleteProduct;
        CloseForm();    
    }
    else{
        ShowMessage("This Product cannot be Deleted, because it appears in at least one unpaid Order ");
    }
}

IsFormDirty()

Description Shows whether the Form has been edited or not:

  • true means that at least one item has been changed in the form's Model
  • false means that the form is as good as new

Attention

You can set whether an Action re-sets the dirty state of your form, via the Reset Dirty State option in a Controller Action.

Thus, if you have a button that resets the Dirty State of your form, the IsFormDirty() will return true, even if it was edited before that button click.

Return Type : bool

Static : Yes

Syntax

/*
    A Calculated Expression that sets the label inside the Form, depending on whether it has unsaved changes (is dirty) or not
*/
function string CalculatedExpression()
{
    if (IsFormDirty()) { 
        return "You have unsaved changes!";
    }
    else { 
        return "";
    }
}                    

CommitAllFiles()

Description Commits (uploads and saves) all pending Files to the Server (regardless of how they where uploaded and using which File Upload Control(s) ).

Return Type : void

Static : Yes

Syntax

/*
    FormControls.NAME_OF_YOUR_FILE_UPLOAD_COMPONENT.CommitFiles();
*/                    

function void SaveUser()
{
    CommitAllFiles(); 
    Model.User.Save();
}                          

Form Controls

In the previous section we saw all functions that can be called in an as-is, global way inside a Form Model. This section will show some functions that can be called against a Form's control.


Methods

Show()

Description Makes the Modal in your Form visible.

Return Type : void

Static : No

Syntax

/*
    FormControls.NAME_OF_YOUR_MODAL.Show();
*/  

function void ConfirmUserDelete(bool confirmed)
{
    if(!confirmed){
        FormControls.ConfirmationModal.Show();
    }

    FormControls.ConfirmationModal.Hide();

    Model.User.Delete();
    CloseForm();
}                    
Hide()

Description Hides (make invisible) the modal in your Form.

Attention

If your Modal is already hidden, an error might occure. So.. maybe check for its state before you attempt to hide it.

Return Type : void

Static : No

Syntax

/*
    FormControls.NAME_OF_YOUR_MODAL.Hide();
*/  

function void ConfirmUserDelete(bool confirmed)
{
    if(!confirmed){
        FormControls.ConfirmationModal.Show();
    }

    //The Modal will be hidden only if confirmed == true, which for me, means that it is in fact visible
    FormControls.ConfirmationModal.Hide();

    Model.User.Delete();
    CloseForm();
}                    

Data Table


Generic Parameters

  • T

Methods

Refresh()

Description Refreshes the Data Table, re-fetching its items based on its assigned DataSource.

Return Type : void

Static : No

Syntax

/*
    FormControls.NAME_OF_YOUR_DATA_TABLE.Refresh();
*/                    

function void RefreshUsers()
{
    FormControls.UsersDataTable.Refresh();
}
GotoLastPage()

Description In cases that your Data Table is paged and has more than 1 pages, this method takes you to the very last page of your Data.

If your Data Table is not paged or has only 1 page, nothing will happen.

Return Type : void

Static : No

Syntax

/*
    FormControls.NAME_OF_YOUR_DATA_TABLE.GotoLastPage();
*/                    

function void ShowLastPage()
{
    FormControls.UsersDataTable.GotoLastPage();
}
GotoPreviousPage()

Description In cases that your Data Table is paged and has more than 1 pages, this method takes you to the previous page of your Data

The GotoPreviousPage() function will do nothing if your data:

  • is not paged
  • or has only 1 page
  • or is already at the first page

Return Type : void

Static : No

Syntax

/*
    FormControls.NAME_OF_YOUR_DATA_TABLE.GotoPreviousPage();
*/                    

function void BackClicked()
{
    FormControls.UsersDataTable.GotoPreviousPage();
}
GotoNextPage()

Description In cases that your Data Table is paged and has more than 1 pages, this method takes you to the next page of your Data

The GotoNextPage() function will do nothing if your data:

  • is not paged
  • or has only 1 page
  • or is already at the last page

Return Type : void

Static : No

Syntax

/*
    FormControls.NAME_OF_YOUR_DATA_TABLE.GotoNextPage();
*/                    

function void NextClicked()
{
    FormControls.UsersDataTable.GotoNextPage();
}
GotoFirstPage()

Description In cases that your Data Table is paged and has more than 1 pages, this method takes you to the First page of your Data

The GotoFirstPage() function will do nothing if your data:

  • is not paged
  • or has only 1 page
  • or is already at the first page

Return Type : void

Static : No

Syntax

/*
    FormControls.NAME_OF_YOUR_DATA_TABLE.GotoFirstPage();
*/                    

function void GoToSecondPage()
{
    FormControls.UsersDataTable.GotoFirstPage();
    FormControls.UsersDataTable.GotoNextPage();
}
GotoPage(int)

Description In cases that your Data Table is paged and has more than 1 page, this method takes you to the specified page.

The GotoPage() function will do nothing if your data:

  • is not paged
  • or has only 1 page
  • or the page you select is smaller than 1

If the page you specify is higher than the total number of pages in your Data Table, the last page will be opened.

Attention

The first page of your Data Table is 1

Return Type : void

Static : No

Parameters

Name Data Type Description
pageNumber int The page to go to

Syntax

/*
    FormControls.NAME_OF_YOUR_DATA_TABLE.GotoPage();
*/    
if(gotoFirst){
    FormControls.UsersDataTable.GotoPage(1);
}

if(gotoLast){
    //Just a large number to make the Table open the last page
    FormControls.UsersDataTable.GotoPage(999999);
}

Data List


Generic Parameters

  • T

Properties

Name Data Type Static Readonly Description
SelectedItem T No No The Item (of type T) that has been selected in the Data List.
ItemsCount int No No Total number of Items in your Data List
SelectedItems Collection[T] No No A Collection items (with a type T) that have been selected in the Data List. Works when the Data List Allows multiple selection

Syntax

function void CheckActions()
{
    Collection[int] actionIDs;

    // Here, the UserActionList consists of items with T = Domain.ApplicationUserAction
    //Multiple actions have been selected from this list
    foreach Domain.ApplicationUserAction action in FormControls.UserActionList.SelectedItems{
        actionIDs.Add(action.Id);

        //Here, the UsersList consists of items with T = Domain.ApplicationUser
        //One user has been selected from this list
        if(action.UserName == FormControls.UsersList.SelectedItem){
            DebugLib.Logger.WriteInfoLine("The user you selected ("+FormControls.UsersList.SelectedItem.UserName+") can run the ["+action.Action+"] action!");
        }
    }
}

Methods

Refresh()

Description Refreshes the Data List, re-fetching its items based on its assigned Data Source or Model

Return Type : void

Static : No

Syntax

/*
    FormControls.NAME_OF_YOUR_DATA_LIST.Refresh();
*/                    

function void RefreshActions()
{
    FormControls.UserActionList.Refresh();
}                    
UpdateSize()

Description Updates the size of the Data List. You can use it after you add/remove items from the List, so as to inform your Models that the size of your Data has changed.

Hint

If all you need is to know the size of your Data, use the UpdateSize() method, instead of the Refresh() one. This is minimize the transferred data, when all you need is a mere number of records.

Return Type : void

Static : No

Syntax

/*
    FormControls.NAME_OF_YOUR_DATA_LIST.UpdateSize();
*/ 
function void DeleteApplicationUserAction(int actionId)
{
    Domain.ApplicationUserAction action = Domain.ApplicationUserAction.GetByKey(actionId);
    Domain.ApplicationUserAction.GetAll().Remove(action);
    FormControls.UserActionList.UpdateSize();
}                    
ClearSelectedItems()

Description De-selects the selected Items (if any), that might have been selected in the Data List.

Return Type : void

Static : No

Syntax

/*
    FormControls.NAME_OF_YOUR_DATA_LIST.ClearSelectedItems();
*/   
function void ClearForm()
{
    if(FormControls.UserActionList.SelectedItems.Length > 0){
        FormControls.UserActionList.ClearSelectedItems();
    }
}                    

Pick List


Generic Parameters

  • T

Properties

Name Data Type Static Readonly Description
SelectedItem T No No The Item (of type T) that has been selected in the Pick List.
SelectedItems Collection[T] No No A Collection items (with a type T) that have been selected in the Pick List. Works when the Pick List Allows multiple selection

Syntax

// Here, the Pick List is named PerformersPickList and allows the user to select 
//multiple Performers for the music Product
function void OnSelectedPerformersChanged()
{
    Model.Product.Performers.Clear();
    foreach Domain.Performer selectedPerformer in FormControls.PerformersPickList.SelectedItems{
        Model.Product.Performers.Add(selectedPerformer);
    }
}       

// Here, the Pick List is named PerformersPickList and allows the user to select 
//one Performer for the music Product
function void OnSelectedPerformerChanged()
{
    Model.Product.Performer = FormControls.PerformersPickList.SelectedItem;
}     

Chart


Generic Parameters

  • T

Properties

Name Data Type Static Readonly Description
SelectedItem T No No The Item, of type T, that the user clicked last (e.g. if a user clicks on the November in a Montly Chart filled with Domain.Month objects, the SelectedItem will be Domain.Month with value November
SelectedDataSetIndex int No No Zero-based index representing the clicked item (e.g. in a Monthly Chart with Domain.Month, if a Noverber is clicked, then SelectedDataSetIndex will be 10

Methods

Refresh()

Description Refreshes the Chart, re-fetching its items based on its assigned DataSource and redrawing it.

Return Type : void

Static : No

Syntax

/*
    FormControls.NAME_OF_YOUR_CHART.Refresh();
*/                    

function void AddBonusToSalary(float bonus)
{
    Model.Salary.Money = Model.Salary.Money + bonus; 
    Model.Salary.Save(); 
    FormControls.ExpensesChart.Refresh();
}      

Generic Parameters

  • T

Properties

Name Data Type Static Readonly Description
SelectedItem T No No The item that has been selected from the Drop Down. If null, nothing was selected.

Methods

Refresh()

Description Refreshes the values of the Drop Down box, re-fetching them from its assigned Data Source.

Return Type : void

Static : No

Syntax

/*
    FormControls.NAME_OF_YOUR_DROP_DOWN.Refresh();
*/                    

function void RefreshPage()
{
    FormControls.DropdownCategoryDataSet.Refresh();
    FormControls.DropdownSubcategoryDataSet.Refresh();
}                        

Map


Generic Parameters

  • T

Properties

Name Data Type Static Readonly Description
ClickedItem T No No The Item, of type T, that was last clicked on the Map

Methods

Refresh()

Description Refreshes and redraws the Map

Return Type : void

Static : No

Syntax

/*
    FormControls.NAME_OF_YOUR_MAP.Refresh();
*/                    

function void RefreshPage()
{
    FormControls.GreekIslands.Refresh();
}                     
DisplayDirections(string, string)

Description Displays the directions from one places to another

Return Type : void

Static : No

Parameters

Name Data Type Description
from string Address of the starting point
to string Address of the target point

Syntax

/*
    FormControls.NAME_OF_YOUR_MAP.DisplayDirections(from, to);
*/                    

function void GetDirections()
{
    if(string.IsNullOrWhiteSpace(Model.SourceAddress)) {
        Model.SourceAddress = "Andrea Papandreou 19 Athens";
    )
    FormControls.IslandsMap.DisplayDirections(Model.SourceAddress, Model.DestinationAddress);
}                      
FitToContent()

Description Zooms the map in or out, depending on the selected Items, so that everything that a User might need to see is displayed in one canvas

Return Type : void

Static : No

Syntax

/*
    FormControls.NAME_OF_YOUR_MAP.FitToContent(from, to);
*/                    

function void AfterIslandSelected()
{
    if(string.IsNullOrWhiteSpace(Model.SourceAddress)) {
        Model.SourceAddress = "Andrea Papandreou 19 Athens";
    )
    FormControls.IslandsMap.FitToContent();
}                        

Calendar


Generic Parameters

  • T

Properties

Name Data Type Static Readonly Description
SelectedItem T No No The last Item of type T, clicked on the Calendar (e.g. a specific object of a Domain.CompanyEvent type

Methods

Refresh()

Description Refreshes the values of the Calendar, re-fetching them from its assigned Data Source.

Return Type : void

Static : No

Syntax

/*
    FormControls.NAME_OF_YOUR_CALENDAR.Refresh();
*/                    

function void IssueSickLeaveRequest(DateTime from, DateTime to)
{
    Domain.SickLeave sickLeave = Domain.SickLeave.Create();
    sickLeave.From = from;
    sickLeave.To = to; 
    sickLeave.User = Model.User;
    sickLeave.Save();

    FormControls.SickLeavesCalendar.Refresh();
}                      

File Upload


Methods

CommitFiles()

Description Commits (uploads and saves) all pending Files of the specific File Upload Component to the Server.

Return Type : void

Static : No

Syntax

/*
    FormControls.NAME_OF_YOUR_FILE_UPLOAD_COMPONENT.CommitFiles();
*/                    

function void SaveUser()
{
    FormControls.UserPhotos.CommitFiles();
    Model.User.Save();
}                          
GetUploadedFilePath()

Description Returns the full path to the Folder where the Files of the current File Upload Control will be saved.

Return Type : string

Static : No

Syntax

``` java /* FormControls.NAME_OF_YOUR_FILE_UPLOAD_COMPONENT.GetUploadedFilePath(); */

function void SaveUser() { FormControls.UserPhotos.CommitFiles(); ShowMessage("Successfully uploaded all User Photos to: " + FormControls.UserPhotos.GetUploadedFilePath()); }

Radio Button


Generic Parameters

  • T

Properties

Name Data Type Static Readonly Description
SelectedItem T No No Returns the Item (of type T) that was selected by the User