Toolbar Customization

Overview

Some toolbar buttons of out-of-box Spreadsheet are disabled, e.g. "New Book" and "Save Book". Because the implementation of these functions quite depends on your requirement, we leave them unimplemented. Here we will tell you how to hook your own logic for these buttons.

Before implementing them, we should get the ideas behind toolbar buttons. When you click a toolbar button, Spreadsheet will invoke its corresponding "action handler" one by one (might be one or more) to perform the task. Hence, what you have to do is to write your custom action handlers and register them in Spreadsheet.

Implementation

Steps to implement logic for a toolbar button:

1. Create a class to implement UserActionHandler.

   There are some methods you have to implement. The isEnabled() and process(). The isEnabled() which returns the enabled state of the handler is invoked by UserActionManager when Spreadsheet needs to refresh toolbar buttons enabled state (e.g. selecting a sheet). When users click a toolbar button, only those enabled handler will be invoked. If one toolbar button's all handlers are disabled, the toolbar button becomes disabled. The process() is the method you should write your own logic to handle the user action.

2. Register our custom handlers via UserActionManager.

   After creating a UserActionHandler, you must hook it before it can be executed. We provide 2 ways to register a handler. UserActionManager.registerHandler() will append the passed handler, but UserActionManager.setHandler() will remove other existing handlers and add the passed one.

Create User Action Handlers

New Book

The "New Book" button will make Spreadsheet load a blank Excel file. We create NewBookHandler to implement this function, and the source codes are as follows:

public class NewBookHandler implements UserActionHandler {

	@Override
	public boolean isEnabled(Book book, Sheet sheet) {
		return true;
	}

	@Override
	public boolean process(UserActionContext context) {
		Importer importer = Importers.getImporter();
		
		try {
			Book loadedBook = importer.imports(new File(WebApps.getCurrent()
							.getRealPath("/WEB-INF/books/blank.xlsx")), "blank.xlsx");
			context.getSpreadsheet().setBook(loadedBook);
		} catch (IOException e) {
			e.printStackTrace();
		}
		return true;
	}
}

• Line 1: A custom handler should implement UserActionHandler interface.
• Line 4: Return enabled state of this handlers.
• Line 13: Import a blank Excel file with importer, please refer to Load A Book Model.
• Line 15: Change Spreadsheet's book model with newly-loaded book. We can get Spreadsheet, Book, Event, selection (AreaRef), and action from UserActionContext.
• Line 19: In most cases, you should return true for you have handled the action.

Save Book

The "Save Book" button will save a book model as an Excel file with its book name as the file name.

public class SaveBookHandler implements UserActionHandler {
	
	@Override
	public boolean isEnabled(Book book, Sheet sheet) {
		return book!=null;
	}

	@Override
	public boolean process(UserActionContext ctx){
		try{
			Book book = ctx.getBook();
			save(book);
			Clients.showNotification("saved "+book.getBookName(),"info",null,null,2000,true);
			
		}catch(Exception e){
			e.printStackTrace();
		}
		return true;
	}
	//omitted code for brevity...
}

• Line 5: Only when Spreadsheet has loaded a book, this handler is enabled.
• Line 11: We can get Spreadsheet, Book, Event, selection (AreaRef), and action from UserActionContext.
• Line 12: We just save back to original Excel file in our example for simplicity.

Register User Action Handlers

After creating our own handlers, we have to register them for corresponding buttons of a Spreadsheet. In such a manner, when a user clicks a button, Spreadsheet can find our custom handlers through the registration.

The source codes below demonstrate how to register custom user action handler in a controller:

Controller of customHandler.zul

public class CustomHandlerComposer extends SelectorComposer<Component> {
	
	@Wire
	private Spreadsheet ss;

	
	@Override
	public void doAfterCompose(Component comp) throws Exception {
		super.doAfterCompose(comp);
		
		//initialize custom handlers
		UserActionManager actionManager = ss.getUserActionManager();
		actionManager.registerHandler(
				DefaultUserActionManagerCtrl.Category.AUXACTION.getName(),
				AuxAction.NEW_BOOK.getAction(), new NewBookHandler());
		actionManager.registerHandler(
				DefaultUserActionManagerCtrl.Category.AUXACTION.getName(),
				AuxAction.SAVE_BOOK.getAction(), new SaveBookHandler());
	}
}

• Line 12: Get UserActionManager via Spreadsheet.
• Line 13: Use UserActionManager to register our user action handlers.
• Line 14: The first parameter is category. Toolbar button belongs to Category.AUXACTION.
• Line 15: The second parameter is action. Each toolbar button corresponds to one action.

After completing above step, when you run visit customHandler.zul, you can see those buttons we register handlers for are enabled now.