Toolbar Customization

Overview

The toolbar of out-of-box Spreadsheet has 3 buttons disabled: "New Book", "Save Book", and "Export to PDF". 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 3 buttons.

Before implementing them, we should get the ideas behind toolbar buttons. When you click a toolbar button, a UserActionManager will invoke the button's corresponding UserActionHandler one by one (might be one or more) to handle. But how do UserActionManager knows which UserActionHandler correspond to which toolbar button? The answer is: we must register handlers in UserActionManager.

Implementation

Steps to implement logic for a toolbar button:

1. Create a class to implement UserActionHandler.

   There are 2 methods of the interface to be implemented: 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: Return true to tell UserActionManater to keep invoking subsequent handlers or false to stop invoking.

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.

Export to PDF

The "Export to PDF" button will export a book model as an PDF file and open a download dialog on a browser.

public class ExportBookHandler implements UserActionHandler {

	private Exporter exporter= Exporters.getExporter("pdf");
	
	@Override
	public boolean isEnabled(Book book, Sheet sheet) {
		return book!=null;
	}

	@Override
	public boolean process(UserActionContext context) {
		File file;
		try {
			Book book = context.getBook();
			file = saveBookAsTempFile(book);
			String fileName = book.getBookName().substring(0, book.getBookName().indexOf('.'));
			Filedownload.save(new AMedia(fileName, null, "application/pdf", file, true));
		} catch (IOException e) {
			e.printStackTrace();
		}
		return true;
	}
	//omitted code for brevity...
}

• Line 3: We can use exporter to export a book model to a PDF file, please refert to Export to Excel.
• Line 7: Only when Spreadsheet has loaded a book, this handler is enabled.
• Line 14: We can get Spreadsheet, Book, Event, selection (AreaRef), and action from UserActionContext.

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());
		actionManager.registerHandler(
				DefaultUserActionManagerCtrl.Category.AUXACTION.getName(),
				AuxAction.EXPORT_PDF.getAction(), new ExportBookHandler());
	}
}

• 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 3 buttons we register handlers for are enabled now.