View · Index

XoWiki: Customizing the menubar

XoWiki's default menubar is defined in packages/xowiki/tcl/menu-procs.tcl. The method ::xowiki::MenuBar config=default creates the menus; config_menu=New supplies the standard creation links. Entries use names such as New.Page: the first component identifies the menu.

Recommended workflow: Edit Folder

The following steps are the recommended workflow for XoWiki version 6.0.0d10 or newer.

When the menubar is enabled, open the menu bearing the wiki instance's name and choose Edit Folder. Set the folder's extra_menu_entries field and save. This is the same workflow for the root folder and subfolders; no additional package parameter needs to be configured.

The action edits the current folder's FormPage, using its existing edit permissions. At the top level it explicitly targets the root folder, even when the wiki displays en:index. This Page → Edit continues to edit the displayed page. Folder settings apply to the menubar rendered for that folder; repeat the configuration for other folders as needed.

For example, add this specification to extra_menu_entries:

{entry -name New.MyPage -label {My Page} -form en:my-page.form}

The form must exist or be available as a prototype. XoWiki uses make_form_link to resolve it and create a link with the current folder, language and return URL, using the usual permission checks. Other targets include a direct URL or a legacy page class:

{entry -name Package.Help -label Help -link /xowiki/help}
{entry -name New.PlainPage -label {Plain Page} -object_type ::xowiki::PlainPage}

A stable entry name updates an existing entry rather than duplicating it. An explicit -label supplies the text; otherwise XoWiki looks for a message key such as xowiki.menu-New-MyPage or xowf.menu-New-MyPage.

Where the default New entries come from

The list is built by ::xowiki::MenuBar config_menu=New in tcl/menu-procs.tcl, not stored separately in each folder. The standard entries are Page, File, Folder and New Form, plus Symbolic Link when configured. XoWiki 6.0.0d10 extends this list with Markdown Page immediately after Page when richtext-markdown is installed. It therefore appears automatically in each default menubar.

The Markdown entry uses en:markdown.form, whose body constraint is _text:richtext,editor=markdown. This explicitly selects Markdown independently of the preferred richtext editor.

Replacing a menu

To replace the contents of the New menu, clear it first and then list the desired entries:

{clear_menu -menu New}
{entry -name New.Page -label Page -form en:page.form}
{entry -name New.File -label File -object_type ::xowiki::File}

XoWiki creates the default menus first and then applies the current folder's extra_menu_entries. These values are Tcl lists of specifications, not Tcl scripts; do not place executable conditionals in them. Clearing the New menu replaces the defaults, including the automatic Markdown entry. Include an entry for en:markdown.form explicitly if a replacement menu should retain it.

Conditional entries in Tcl

A package-dependent default entry belongs in the menu-building method. For example, the development version of XoWiki adds Markdown Page after Page only when richtext-markdown is installed:

if {[apm_package_installed_p richtext-markdown]} {
    set link [::$package_id make_form_link \
                  -form en:markdown.form \
                  -parent_id ${:parent_id} \
                  -return_url $return_url]
    :add_menu_item -name New.MarkdownPage -item [list url $link]
}

The prototype resources/prototypes/markdown.form.page uses the field constraint _text:richtext,editor=markdown. The explicit editor setting makes this choice independent of PreferredRichtextEditor. Content is stored as HTML by the richtext editor. The prototype is imported through the normal form-resolution mechanism when needed.

After updating the Tcl source, reload it through the package manager or restart the server. Import the updated XoWiki message catalogs for translated labels. A customized New menu that clears the defaults must explicitly include the desired Markdown entry.

previous November 2026
Sun Mon Tue Wed Thu Fri Sat
1 2 3 4 5 6 7
8 9 10 11 12 13 14
15 16 17 18 19 20 21
22 23 24 25 26 27 28
29 30 1 2 3 4 5

Popular tags

17 , 5.10 , 5.10.0 , 5.10.1 , 5.9.0 , 5.9.1 , ad_form , ADP , ajax , aolserver , asynchronous , Azure , bgdelivery , bootstrap , bugtracker , CentOS , COMET , compatibility , conference , CSP , CSRF , cvs , debian , docker , docker-compose , emacs , engineering-standards , exec , fedora , FreeBSD
No registered users in community xowiki
in last 30 minutes
Contributors

OpenACS.org