The Complete Guide to Social Engine 4 Module Development Part 5: Menus

To help our users find their way around we need menus. Most of the group of links you find in SE4 pages are menus wrapped within a widget. To be able to create our own menus or add menu items to existing menus we need to take a look at two tables engine4_core_menus and engine4_core_menuitems.

The contents of engine4_core_menus are the editable menus. That is, menus listed under this table can me manipulated by the admin user in /admin/menus. The name field is the prefix used in the name of the menuitems in engine4_core_menuitems. This is how you will refer to menu when you retrieve it for use in your code. The type field determines if this menu is a custom one created by an admin using the “Add Menu” function in /admin/menus. The title field is the title of the menu as displayed in the menu editor. This is not visible to end users. The order field determines the order the menu is displayed in the drop down in the menu editor. Note inserting the details of your menu in engine4_core_menus only allows admin users to manipulate your menu.

The more interesting table is engine4_core_menuitems. All the menu items in SE4 standard or otherwise goes here.

The name field is the name of the menu item. This is how you will refer to the menu that contains the menu item. For example in our car module we want to have a main navigation menu for cars which will appear beneath the SE4s default header menu. This menu will have 3 items: “Browse”, “My Cars”, “Create New Car”. To do this we need to create 3 menu items car_main_browse, car_main_manage and car_main_create. If we want the admins to be able to manipulate this menu all we need to do is to insert a row to engine4_core_menus named car_main.

The module field determines which module the menu item is enclosed in. Disabling/enabling the enclosing module disable/enable the display of the menu item.

The label field determines the text in the generated link. HTML tags are allowed here.

The params field is in JSON format and determines the attributes of the generated link. This set’s the parameters for the router that will generate the value of the href tag of the link. Routing is discussed in Part 3 of this tutorial. Field/value pairs that is not part of the routing parameters will become attributes of the generated link. Adding “target:_blank” for example will make the link open in a new tab/window. Adding the “uri” parameter and leaving out other routing parameters (route, controller, etc.). Will make the link point to the specified uri. You may use the “javascript:” scheme to make the link execute arbitrary javascript code when clicked.

The menu field determines which menu the menu item belongs to while the submenu field determines which submenu it belongs within the menu. Note that css/javascript must be provided for the submenu to look and behave properly.

The enabled field determines if the menu is displayed or not. The custom field determines if the menu item is created via the menu editor in the admin panel. This also determines if the item can be deleted from the menu. The order field determines the order of the item as it appears on the menu.

With what we discussed so far we need the following sql statements in the my.sql file of our Car module for our main menu:

Now we can discuss the plugin field. The field comes in two formats: <ClassName> and <ClassName>::<Method>. Using the latter we can control whether the menu item is displayed or not my making the method return true or false depending on the situation. For example:

Will make the browse link to display/hide depending on whether the currenly log in user has authorization to view cars (discussed in part 4 or this tutorial).

Specifying only the the class name of the plugin allows for more flexibility. This will allow you not only to hide/show the menu item but also set the href, icon, style and other attributes of the generated link. A great example of this is the Messages_Plugin_Menus which has a method to add the number of unread messages on the menu item label.

Now that we have our menu we need to display it. This is the easy part to retrieve the menu from a controller:

And in the view script:
As discussed earlier most of the menus that appear in the front end of SE4 are wrapped in widgets. In our case we might want to put our menu in a widget which the user can move around in the layout editor. To enable that we would need to create widgets and pages. Which will be the subject of part 6.

Originally published in https://social-engine-tutorials.blogsplot.com.