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);`
`ShowMessage("This is a Warning.", AppLib.MessageType.Warning);`
`ShowMessage("This is an Error.", AppLib.MessageType.Error);`
`ShowMessage("This is a Success message.", AppLib.MessageType.Success);`

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

Form Controls & Commands¶

Commands¶

IsModal()¶

RedirectToUrl(string)¶

ShowMessage(string)¶

ShowMessage(string, AppLib.MessageType)¶

ShowMessage(string, AppLib.MessageType, string)¶

CloseForm()¶

IsFormDirty()¶

CommitAllFiles()¶

Form Controls¶

Modal¶

Methods¶

Show()¶

Hide()¶

Data Table¶

Generic Parameters¶

Methods¶

Refresh()¶

GotoLastPage()¶

GotoPreviousPage()¶

GotoNextPage()¶

GotoFirstPage()¶

GotoPage(int)¶

Data List¶

Generic Parameters¶

Properties¶

Methods¶

Refresh()¶

UpdateSize()¶

ClearSelectedItems()¶

Pick List¶

Generic Parameters¶

Properties¶

Chart¶

Generic Parameters¶

Properties¶

Methods¶

Refresh()¶

DropDown¶

Generic Parameters¶

Properties¶

Methods¶

Refresh()¶

Map¶

Generic Parameters¶

Properties¶

Methods¶

Refresh()¶

DisplayDirections(string, string)¶

FitToContent()¶

Calendar¶

Generic Parameters¶

Properties¶

Methods¶

Refresh()¶

File Upload¶

Methods¶

CommitFiles()¶

GetUploadedFilePath()¶

Radio Button¶

Generic Parameters¶

Properties¶