Introduction
Empress is built on a foundation of robust and versatile objects, one of the most fundamental being the frappe.ui.Page object. This object is at the heart of every screen rendered within the Desk. In this guide, we’ll dive into the technical depths of the frappe.ui.Page object, exploring the essential methods for creating, modifying, and managing your Empress pages.
Creating a Page with frappe.ui.make_app_page
Your journey with the frappe.ui.Page object begins with the frappe.ui.make_app_page method. This method creates a new Page and attaches it to a specified parent.
let page = frappe.ui.make_app_page({
title: 'My Page',
parent: wrapper, // HTML DOM Element or jQuery object
single_column: true // create a page without sidebar
});
The make_app_page function accepts an object with the following properties:
title: The title of your page.parent: The parent element to which your page is attached. This can be an HTML DOM Element or a jQuery object.single_column: A Boolean value indicating whether the page should be created without a sidebar.
The resulting page appears as follows:
New Page
Leveraging Page Methods
The frappe.ui.Page object provides a wealth of methods for manipulating and interacting with your pages. Let’s explore some of the most common ones.
Setting Title and Subtitle with page.set_title and page.set_title_sub
The set_title method allows you to set the page title along with the document title. The document title is displayed in the browser tab.
page.set_title('My Page');
Page Title
The set_title_sub method sets the secondary title of the page, which appears on the right side of the page header.
page.set_title_sub('Subtitle');
Page Subtitle
Managing Page Indicators with page.set_indicator and page.clear_indicator
The set_indicator method sets the indicator label and color. This can be useful for providing visual cues about the status of the page or its content.
page.set_indicator('Pending', 'orange');
Page Indicator
You can clear the indicator label and color with the clear_indicator method.
page.clear_indicator();
Controlling Page Actions with page.set_primary_action, page.clear_primary_action, page.set_secondary_action, and page.clear_secondary_action
The frappe.ui.Page object provides methods for managing primary and secondary actions on your page. These actions can be anything from creating a new item, refreshing the page, or any other functionality you wish to provide.
let $btn = page.set_primary_action('New', () => create_new(), 'octicon octicon-plus');
Page Primary Action
You can clear the primary action button and handler using the clear_primary_action method.
page.clear_primary_action();
Similarly, you can set and clear secondary actions using the set_secondary_action and clear_secondary_action methods.
let $btn = page.set_secondary_action('Refresh', () => refresh(), 'octicon octicon-sync');
Page Secondary Action
page.clear_secondary_action();
Adding and Removing Menu Items with page.add_menu_item, page.clear_menu, page.add_action_item, and page.clear_actions_menu
The frappe.ui.Page object provides methods for adding menu items to the Menu dropdown and the Actions dropdown, as well as methods for removing these items.
Add a normal menu item with add_menu_item:
page.add_menu_item('Send Email', () => open_email_dialog());
Page Menu Dropdown
Remove Menu dropdown items with clear_menu:
page.clear_menu();
Add action items in the Actions dropdown with add_action_item:
page.add_action_item('Delete', () => delete_items());
Page Actions Dropdown
Remove Actions dropdown items with clear_actions_menu:
page.clear_actions_menu();
Working with Inner Toolbar Buttons with page.add_inner_button, page.remove_inner_button, and page.clear_inner_toolbar
The frappe.ui.Page object provides methods for managing buttons in the inner toolbar. This includes adding, removing, and clearing buttons.
page.add_inner_button('Update Posts', () => update_posts());
Page Inner Button
page.remove_inner_button('Update Posts');
page.remove_inner_toolbar();
Manipulating Form Controls with page.add_field, page.get_form_values, and page.clear_fields
The frappe.ui.Page object provides methods for working with form controls in the page form toolbar. This includes adding fields, getting form values, and clearing fields.
let field = page.add_field({
label: 'Status',
fieldtype: 'Select',
fieldname: 'status',
options: [
'Open',
'Closed',
'Cancelled'
],
change() {
console.log(field.get_value());
}
});
Page Form Toolbar
let values = page.get_form_values();
// { status: 'Open', priority: 'Low' }
page.clear_fields();
The frappe.ui.Page object is a powerful tool in your Empress development toolkit. By mastering these methods, you can create dynamic, interactive pages that empower your users and enhance your applications.