Microsoft Dynamic AX 2009 : Developing Web User Interface Components (part 4) - AxToolbar, AxPopup

AxToolbar

The AxToolbar control provides an intuitive and consistent way to organize and display functions that the user performs frequently on your application’s Web pages. Typically, toolbars are displayed at the top of the page or grid control. AxToolbar extends the Windows SharePoint Services toolbar controls. AxToolbarMenu, used within AxToolbar, is derived from Microsoft.SharePoint.WebControls.Menu. The AxToolbar control is used to render a toolbar button with a drop-down menu that is rendered when the menu is clicked via a callback. In other words, AxToolbarMenu lets you modify the menu item properties before the menu items are rendered.

AxToolbarButton, used within the AxToolbar control, is derived from SPLinkButton. It is used to render top-level buttons.

Depending on your application, you can use either the AxToolbar ASP.NET control or the Dynamics Toolbar Web part to display the toolbar menu items on top of the list, overview, or task page. Generally, you use the Dynamics Toolbar Web part to control the display of toolbar menu items. But if you have a task page that contains master/detail information, such as a Purchase Requisition header and line items, you should use the AxToolbar ASP.NET control inside your Web User Control above the detail AxGridview control to allow the user to add and manage the line items.

You can use AxToolbar bound to AxDataSource or as an unbound control. When the controls are bound, the menu item context is automatically based on the current item selected on the grid view. When the controls are unbound, you have to write code to manage the toolbar context.

You can point the toolbar to Web Menus in the AOT through the WebMenuName property. The AOT Web Menus allow you to define multilevel menu structure with the SubMenu, MenuItem, and MenuItem reference nodes. Each top-level submenu in a Web menu is rendered by the AxToolbar control using AxToolbarMenu as a drop-down menu. Each top-level menu item is rendered using AxToolbarButton as a link button. If you have a submenu within a submenu, the second and further levels are displayed as flyout menus.

SetMenuItemProperties, ActionMenuItemClicking, and ActionMenuItemClicked are AxToolbar control-specific events. You use SetMenuItemProperties to change the behavior of drop-down menus, such as showing or hiding menu items based on the currently selected record, setting or removing context, and so on. An example of changing the menu item context in the SetMenuItemProperties event is shown in the following code.

void Webpart_SetMenuItemProperties(object sender, SetMenuItemPropertiesEventArgs e)
    {
        // Do not pass the currently selected customer record context, since this menu
is for creating new (query string should be empty)
     if (e.MenuItem.MenuItemAOTName == "EPCustTableCreate")
              ((AxUrlMenuItem)e.MenuItem).MenuItemContext = null;
    }

					  

If you have user interface logic defined in a Web User Control and want to call this function instead of the one defined in the AOT when a toolbar item is clicked, you use ActionMenuItemClicking and ActionMenuItemClicked. For example, you can prevent the menu item from executing the action defined in the AOT by using the ActionMenuItemClicking event and defining your own action in C# using the ActionMenuItemClicked event in the Web User Control, as shown here.

void webpart_ActionMenuItemClicking(object sender, ActionMenuItemClickingEventArgs e)
    {
        if (e.MenuItem.MenuItemAOTName.ToLower() == "EPCustTableDelete")
        {
            e.RunMenuItem = false;
        }
    }
    void webpart_ActionMenuItemClicked(object sender, ActionMenuItemEventArgs e)
    {
   if (e.MenuItem.MenuItemAOTName.ToLower() == "EPCustTableDelete")
        {
                int selectedIndex = this.AxGridView1.SelectedIndex;
                if (selectedIndex != -1)
                {
                    this.AxGridView1.DeleteRow(selectedIndex);
                }
        }
    }

					  

AxPopup

AxPopup controls are used to open a page in a pop-up browser window, to close a popup page, and to pass data from the pop-up page back to the parent page and trigger an OnPopupClosed server event on the parent. This functionality is encapsulated in two controls: AxPopupParentControl to use on the parent page and AxPopupChildControl to use on the pop-up page. Both controls derive from AxPopupBaseControl. These controls are AJAX compatible, so you can create them conditionally as part of a partial update. AxPopupParentControl allows a page, typically a Web part page, to open in a pop-up window. You can open a pop-up window from a client-side script by using the GetOpenPopupEventReference method. The returned string is a JavaScript statement that can be assigned, for example, to a button’s onclick attribute or to a toolbar menu item. The following code shows how a developer can open a pop-up window using client-side scripting by modifying the OnClick event.

  protected void SetPopupWindowToMenuItem(SetMenuItemPropertiesEventArgs e)
  {
      AxUrlMenuItem menuItem = new AxUrlMenuItem("EPCustTableCreate");
     //Calling the JavaScript function to set the properties of opening Web page on
clicking the menuitems.
        e.MenuItem.ClientOnClickScript = this.AxPopupParentControl1.GetOpenPopupEventR
eference(menuItem);
    }

					  

You can also open a pop-up window from a server method by calling the OpenPopup method. Because pop-up blockers can block server-initiated pop-up windows, use OpenPopup only when absolutely necessary, for example, when only the server code can decide whether a pop-up window needs to be opened.

When placed on a pop-up page, AxPopupChildControl allows the page to close. You can close the pop-up page from a client-side script by using the GetClosePopupEventReference method, as shown in the following example.

this.BtnOk.Attributes.Add("onclick",
this.popupChild.GetClosePopupEventReference(true, true) + "; return false;");

					  

You can close a pop-up window from the server event by using the ClosePopup method. Use the server method when additional processing is needed upon closing, such as performing an action or calculating values to be passed back to the parent page. There are two parameters to the ClosePopup and OpenPopup methods:

• The boolean setFieldValues parameter indicates whether data needs to be passed back to the parent page.

• The boolean updateParent parameter indicates whether the parent page needs to post back after the pop-up page is closed. If the value is true, AxPopupChildControl makes a call (via a client-side script) to the parent page to post back, with the AxPopupParentControl being the target. AxPopupParentControl then fires the PopupClosed server event, on which the parent page application code can get the values passed from the pop-up page and perform an action or simply update its state.

Data can be passed from the pop-up page back to the parent page using AxPopupField objects. You expose these objects via the Fields property of the AxPopupBaseControl, from which both AxPopupParentControl and AxPopupChildControl are derived.

AxPopupParentControl and AxPopupChildControl have fields with the same names. When the pop-up page closes, the value of each field of AxPopupChildControl is assigned (via a client-side script) to the corresponding field in AxPopupParentControl.

AxPopupField can optionally be associated with another control, such as TextBox or any other control, by assigning its TargetId property to the ID property of the target control. This is useful, for example, when the pop-up page has a TextBox control. To pass the user input to the parent page upon closing the pop-up page—and to do it entirely on the client to avoid a round-trip—you need to associate a field with the TextBox control. When AxPopupField isn’t explicitly associated with a target control, it gets implicitly associated with a HiddenField control automatically created by AxPopupParentControl or AxPopupChildControl.

You can then set the value of the field on the server via the SetFieldValue method. Typically, you call SetFieldValue on AxPopupChildControl, and you can call it at any point of user interaction with the pop-up page, including the initial rendering or the closing of the page. The value of the field can be retrieved via the GetFieldValue method. Typically, it is called on AxPopupParentControl during the processing of the PopupClosed event. You can clear the values of nonassociated fields by calling the ClearFieldValues method.

You can also set or retrieve values of AxPopupFields on the client by manipulating the target control value. You can retrieve target control, whether explicitly or implicitly associated, by using the TargetControl property.