GAM API for menus

Official Content

Use the following API to get, create, and update GAM Menus:

GAMApplication API

Methods for getting menus:

&GAMApplication.GetMenus(&MenuFilter, &Errors) //&Errors is GAMError collection, &MenuFilter is GAMApplicationMenuFilter data type
&GAMApplication.GetMenu(&MenuId, &Errors) 
&GAMApplication.GetSubMenus(&MenuId, &Errors)

Methods for updating menus:

&GAMApplication.AddMenu(&Menu,&Errors)  //&Menu is GAMApplicationMenu
&GAMApplication.UpdateMenu(&Menu,&Errors)
&GAMApplication.DeleteMenu(&Menu,&Errors) 

Methods for updating menu options:

&GAMApplication.AddMenuOption(&MenuId, &MenuOption, &Errors) //&MenuOption is GAMApplicationMenuOption data type
&GAMApplication.UpdateMenuOption(&MenuId, &MenuOption, &Errors) 
&GAMApplication.DeleteMenuOption(&MenuId, &MenuOption, &Errors)

Methods for getting menu options:

&GAMApplication.GetMenuOptions(&MenuId, &MenuOptionFilter, &Errors) //&MenuOptionFilter is GAMApplicationMenuOptionFilter data type  
&GAMApplication.GetMenuOption(&MenuId, &MenuOptionId, &Errors)   
&GAMApplication.GetPermissionResources(&PermissionFilter, &Errors)  Returns all the GAM Application permissions that have an associated resource.

Methods for getting the User Menu:

&GAMApplication.GetUserMenu(&MenuId,&GAMMenuAdditionalParameters, &Errors) //&GAMMenuAdditionalParameters is GAMMenuAdditionalParameters data type Returns the menu given in &MenuId parameter, for the user in the session, according to the user's permissions.
&GAMApplication.GetUserMainMenu(&GAMMenuAdditionalParameters, &Errors)  Returns the main menu of the GAM Application, for the user in the session, according to the user's permissions.
&GAMApplication.GetUserMenuByGUID(&MenuGUID,&GAMMenuAdditionalParameters, &Errors) Returns the menu given in &MenuGUID parameter, for the user in the session, according to the user's permissions.

Note:

In the cases shown above, the &GAMApplication needs to be instantiated using any of the following methods: 

  • &GAMApplication.Load(&GAMApplicationId)
  • &GAMApplication = GAMRepository.GetApplicationByGUID(&GAMApplicationGUID,&Errors) //&Errors is GAMError collection

GAMRepository API

&GAMRepository.GetApplicationMenu(&AppGUID,&MenuGUID, &Errors)

It is also a static method :

GAMRepository.GetApplicationMenu(&AppGUID,&MenuGUID, &Errors)

Examples

I. Creating a menu with dynamic properties

The dynamic properties of a menu can be used for defining the class and icons to be used for each menu option.

&GAMApplication.Load(1)
&GUID.FromString('d0bfd659-7912-4fb8-9751-4a27546fb400')
&ApplicationMenu.GUID            = &GUID
&ApplicationMenu.Name           = !"Security"
&ApplicationMenu.Description   = !"Security"
&isOK = &GAMApplication.AddMenu(&ApplicationMenu, &Errors)
If &isOK
    Commit
    &MenuId = &ApplicationMenu.Id
    //Define Menu option
    &ApplicationMenuOption = new()
    &GUID.FromString('dcdee429-45ae-4bd6-bf71-16e4cc90f724')
    &Name = !"Users"
    &Dsc    = !"Users"
    &Type  = GAMMenuOptionType.Simple
    &MenusId = 0
    //Define a dynamic property for the menu option   
    &GAMProperty           = new()
    &GAMProperty.Id        = !"IconClassUsers"
    &GAMProperty.Value     = !"IconClassUsers"
    &ApplicationMenuOption.Properties.Add(&GAMProperty)
       
    &GAMApplicationPermission = &GAMApplication.GetPermissionByName(!"gamexamplewwusers_Execute",&Errors)
    &RelResId = &GAMApplicationPermission.GUID
    &Resource = !"gamexamplewwusers"
    Do 'Load_ApplicationMenuOption'  
    &isOK = &GAMApplication.AddMenuOption(&MenuId, &ApplicationMenuOption, &Errors)

endif
Sub 'Load_ApplicationMenuOption'
    &ApplicationMenuOption.GUID                            = &GUID
    &ApplicationMenuOption.Name                            = &Name
    &ApplicationMenuOption.Description                     = &Dsc
    &ApplicationMenuOption.Type                            = &Type
    &ApplicationMenuOption.SubMenuId                       = &MenusId
    &ApplicationMenuOption.PermissionResourceGUID          = &RelResId
    &ApplicationMenuOption.Resource                        = &Resource
    &ApplicationMenuOption.ResourceParameters              = &ResourceParameters
EndSub

II. The following code is for getting the menu options of a given menu:

//&AppMenuOption is GAMApplicationMenuOption data type
//&Application is GAMApplication
//&Filter is GAMApplicationMenuOptionFilter
//&Errors is GAMError collection

&Application.Load(&ApplicationId)
For &AppMenuOption in &Application.GetMenuOptions(&MenuId, &Filter, &Errors)
       
        &Id            = &AppMenuOption.Id
        &Name          = &AppMenuOption.Name
        &Dsc           = &AppMenuOption.Description    
        &Type          = &AppMenuOption.Type
        &Order         = &AppMenuOption.Order
       
    EndFor    

III. Using Additional Parameters for loading dynamic properties

In order to load the dynamic properties of a menu option, use the LoadProperties method of GAMMenuAdditionalParameters (which is a parameter of GetUserMenuByGUID method).

    &GUID = 'd0bfd659-7912-4fb8-9751-4a27546fb400'
    &GAMApplication.Load(1)
    
    &GAMMenuAdditionalParameters.LoadProperties    = TRUE
    &GAMMenuAdditionalParameters.Levels = &levels
        
    &GAMMenuOptionList = &GAMApplication.GetUserMenuByGUID(&GUID,&GAMMenuAdditionalParameters,&Errors)
    if &Errors.Count <> 0
        msg(&Errors.Item(1).Code + " " + &Errors.item(1).Message)
    endif

IV. Using absolute or relative URLs for the menu options

The URL returned for each menu option can be absolute or relative depending on the configuration of the "Use absolute URL by environment" property of the GAM Application where the menu is defined.

 

image_20171019135828_1_png

This value can be overridden using the ReturnAbsoluteUrlByEnvironment property of the GAMMenuAdditionalParameters (a parameter of the methods used to get the user menu).

So, the possible values for ReturnAbsoluteUrlByEnvironment property are the following:

Yes The URL will be absolute.
No The URL will be relative.
Default Use the value configured in "Use absolute URL by environment" property of the GAM Application.

Example code:

&GAMApplication.Load(1)
&GAMMenuAdditionalParameters.ReturnAbsoluteUrlByEnvironment = TRUE
&GAMMenuOptionList = &GAMApplication.GetUserMenuByGUID(&GUID,&GAMMenuAdditionalParameters,&Errors)

V. Loading options without permissions

In some cases, it may be useful to get the full menu regardless of the user's permissions.

The following properties belong to the GAMMenuAdditionalParameters object, a parameter of the methods used to get the user menu.

IgnoreUserPermissions: GAMBoolean

If TRUE, ignores the user permissions to get the menu. The permissions are not checked, and the menu options are all Authorized.

If FALSE, the permissions are considered to load the menu. This is the default value.

ReturnOptionsWithoutPermission: GAMBoolean

If TRUE, returns the menu options even though the user has no permissions. In that case, the menu option will be "Not Authorized" and will be assigned to the link specified in the URLOptionsWithoutPermissions property.

If FALSE, the menu option is not loaded if the user doesn't have the permission associated with that menu option. This is the default value.

URLOptionsWithoutPermissions : GAMURL Link which is going to be assigned to the menu option that the user has no permission to access. This property is considered only when ReturnOptionsWithoutPermission = TRUE. The URL has to be absolute.


Example code:

&GAMApplication.Load(1)
&GAMMenuAdditionalParameters.ReturnOptionsWithoutPermission = TRUE
&GAMMenuAdditionalParameters.URLOptionsWithoutPermissions   = &link
&GAMMenuOptionList = &GAMApplication.GetUserMenuByGUID(&GUID,&GAMMenuAdditionalParameters,&Errors)

Note:

The API is documented in the GAM Examples distributed with GeneXus. They are consolidated during the GAM Activation Process. In particular, the objects below may be helpful to get an idea of how this API is used.

  • GAMExampleAppMenuEntry
  • GAMExampleAppMenuOptionEntry
  • GAMExampleWWAppMenus
  • GAMExampleWWAppMenuOptions



Was this page helpful?
What Is This?
Your feedback about this content is important. Let us know what you think.