Toolbar Customization"

From Documentation
m (correct highlight (via JWB))
 
(6 intermediate revisions by the same user not shown)
Line 12: Line 12:
 
'''Steps to implement logic for a toolbar button'''
 
'''Steps to implement logic for a toolbar button'''
 
# Create a class to implement <javadoc directory="zss">org.zkoss.zss.ui.UserActionHandler</javadoc>.
 
# Create a class to implement <javadoc directory="zss">org.zkoss.zss.ui.UserActionHandler</javadoc>.
#: There are some methods you have to implement - <tt>isEnabled()</tt> and <tt>process()</tt>. The <tt>isEnabled()</tt> which returns the enabled state of the handler is invoked by <tt>UserActionManager</tt> when Spreadsheet needs to refresh toolbar button's 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 <tt>process()</tt> is the method you should write your own logic to handle the user action.
+
#: There are some methods you have to implement - <code>isEnabled()</code> and <code>process()</code>. The <code>isEnabled()</code> which returns the enabled state of the handler is invoked by <code>UserActionManager</code> when Spreadsheet needs to refresh toolbar button's 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 <code>process()</code> is the method you should write your own logic to handle the user action.
 
# Register our custom handlers via <javadoc directory="zss">org.zkoss.zss.ui.UserActionManager</javadoc>.
 
# Register our custom handlers via <javadoc directory="zss">org.zkoss.zss.ui.UserActionManager</javadoc>.
#: After creating a <tt>UserActionHandler</tt>, you must hook it before it can be executed. We provide 2 ways to register a handler. <tt>UserActionManager.registerHandler()</tt> will append the passed handler while <tt>UserActionManager.setHandler()</tt> will remove other existing handlers and add the passed one.
+
#: After creating a <code>UserActionHandler</code>, you must hook it before it can be executed. We provide 2 ways to register a handler. <code>UserActionManager.registerHandler()</code> will append the passed handler while <code>UserActionManager.setHandler()</code> will remove other existing handlers and add the passed one.
  
  
Line 20: Line 20:
  
 
== New Book ==
 
== New Book ==
"New Book" button will make Spreadsheet load a blank Excel file. We create <tt>NewBookHandler</tt> to implement this function, the source code are as follows:
+
"New Book" button will make Spreadsheet load a blank Excel file. We create <code>NewBookHandler</code> to implement this function, the source code are as follows:
  
<source lang='java' high='1, 4,13,15,19'>
+
<source lang='java' highlight='1, 4,13,15,19'>
 
public class NewBookHandler implements UserActionHandler {
 
public class NewBookHandler implements UserActionHandler {
  
Line 45: Line 45:
 
}
 
}
 
</source>
 
</source>
* Line 1: A custom handler should implement <tt>UserActionHandler</tt> interface.
+
* Line 1: A custom handler should implement <code>UserActionHandler</code> interface.
 
* Line 4: Return enabled state of this handlers.
 
* Line 4: Return enabled state of this handlers.
 
* Line 13: Import a blank Excel file with importer, please refer to [[ZK_Spreadsheet_Essentials/Working_with_Spreadsheet/Spreadsheet_Data_Model#Load_A_Book_Model| Load A Book Model]].
 
* Line 13: Import a blank Excel file with importer, please refer to [[ZK_Spreadsheet_Essentials/Working_with_Spreadsheet/Spreadsheet_Data_Model#Load_A_Book_Model| Load A Book Model]].
 
* Line 15: Change Spreadsheet's book model with newly-loaded book. We can get <javadoc directory="zss">org.zkoss.zss.ui.Spreadsheet</javadoc>, <javadoc directory="zss">org.zkoss.zss.api.model.Book</javadoc>, <javadoc >org.zkoss.zk.ui.event.Event</javadoc>, selection (<javadoc directory="zss">org.zkoss.zss.api.AreaRef</javadoc>), and action from <javadoc directory="zss">org.zkoss.zss.ui.UserActionContext</javadoc>.
 
* Line 15: Change Spreadsheet's book model with newly-loaded book. We can get <javadoc directory="zss">org.zkoss.zss.ui.Spreadsheet</javadoc>, <javadoc directory="zss">org.zkoss.zss.api.model.Book</javadoc>, <javadoc >org.zkoss.zk.ui.event.Event</javadoc>, selection (<javadoc directory="zss">org.zkoss.zss.api.AreaRef</javadoc>), and action from <javadoc directory="zss">org.zkoss.zss.ui.UserActionContext</javadoc>.
* Line 19: In most cases, you should return <tt>true</tt> if you have handled the action.
+
* Line 19: In most cases, you should return <code>true</code> if you have handled the action.
  
 
== Save Book ==
 
== Save Book ==
 
"Save Book" button will save a book model as an Excel file with its book name as the file name.
 
"Save Book" button will save a book model as an Excel file with its book name as the file name.
  
<source lang='java' high='5, 11, 12'>
+
<source lang='java' highlight='5, 11, 12'>
 
public class SaveBookHandler implements UserActionHandler {
 
public class SaveBookHandler implements UserActionHandler {
 
 
Line 79: Line 79:
 
* Line 5: Only when Spreadsheet has loaded a book, this handler is enabled.
 
* Line 5: Only when Spreadsheet has loaded a book, this handler is enabled.
 
* Line 11: We can get <javadoc directory="zss">org.zkoss.zss.ui.Spreadsheet</javadoc>, <javadoc directory="zss">org.zkoss.zss.api.model.Book</javadoc>, <javadoc >org.zkoss.zk.ui.event.Event</javadoc>, selection (<javadoc directory="zss">org.zkoss.zss.api.AreaRef</javadoc>), and action from <javadoc directory="zss">org.zkoss.zss.ui.UserActionContext</javadoc>.
 
* Line 11: We can get <javadoc directory="zss">org.zkoss.zss.ui.Spreadsheet</javadoc>, <javadoc directory="zss">org.zkoss.zss.api.model.Book</javadoc>, <javadoc >org.zkoss.zk.ui.event.Event</javadoc>, selection (<javadoc directory="zss">org.zkoss.zss.api.AreaRef</javadoc>), and action from <javadoc directory="zss">org.zkoss.zss.ui.UserActionContext</javadoc>.
* Line 12: We just save back to original Excel file in our example for simplicity.
+
* Line 12: We just save back to original Excel file in our example for simplicity. Regarding how to implement the saving, you can refer to [[ZK_Spreadsheet_Essentials/Working with Spreadsheet/Handling Data Model/Export to Excel | Export to Excel]].
 
 
  
 
= Register User Action Handlers =
 
= Register User Action Handlers =
Line 88: Line 87:
  
 
'''Controller of customHandler.zul'''
 
'''Controller of customHandler.zul'''
<source lang='java' high='12, 13, 14,15'>
+
<source lang='java' highlight='12, 13, 14,15'>
 
public class CustomHandlerComposer extends SelectorComposer<Component> {
 
public class CustomHandlerComposer extends SelectorComposer<Component> {
 
 
Line 110: Line 109:
 
}
 
}
 
</source>
 
</source>
*Line 12: Get <tt>UserActionManager</tt> via Spreadsheet.
+
*Line 12: Get <code>UserActionManager</code> via Spreadsheet.
*Line 13: Use <tt>UserActionManager</tt> to register our user action handlers.
+
*Line 13: Use <code>UserActionManager</code> to register our user action handlers.
*Line 14: The first parameter is '''category name'''. Toolbar button belongs to <tt>org.zkoss.zss.ui.impl.Category.AUXACTION</tt>.
+
*Line 14: The first parameter is '''category name'''. Toolbar button belongs to <javadoc directory="zss" method="AUXACTION" > org.zkoss.zss.ui.impl.DefaultUserActionManagerCtrl.Category</javadoc>.
 
*Line 15: The second parameter is '''action name'''. Each toolbar button corresponds to one action which is defined in <javadoc directory="zss">org.zkoss.zss.ui.AuxAction</javadoc>.
 
*Line 15: The second parameter is '''action name'''. Each toolbar button corresponds to one action which is defined in <javadoc directory="zss">org.zkoss.zss.ui.AuxAction</javadoc>.
  
  
After completing above step, run <tt>customHandler.zul</tt> and you can see those buttons we registered handlers for are now enabled.
+
After completing above step, run <code>customHandler.zul</code> and you can see those buttons we registered handlers for are now enabled.
  
 
[[File:zss-essentials-customHandler.png | center]]
 
[[File:zss-essentials-customHandler.png | center]]
Line 122: Line 121:
  
  
 +
= Append or Override with Your Handler =
 +
There are 2 ways to hook up your user action handlers:
 +
* <javadoc directory="zss" method="registerHandler(java.lang.String, java.lang.String, org.zkoss.zss.ui.UserActionHandler)">org.zkoss.zss.ui.impl.DefaultUserActionManagerCtrl</javadoc>
 +
*: This method appends your handler after existing handlers, and those handlers are invoked in order. It's used to add customized post-processing for a toolbar button.
 +
 +
* <javadoc  directory="zss" method="setHandler(java.lang.String, java.lang.String, org.zkoss.zss.ui.UserActionHandler)">org.zkoss.zss.ui.impl.DefaultUserActionManagerCtrl</javadoc>
 +
*: This method replaces existing handlers with yours, and only your handler is left and invoked. It can be used to override existing toolbar button's function.
 +
 +
 +
= Hide Toolbar Button=
 +
You can hide some toolbar buttons by JavaScript like:
  
 +
[https://github.com/zkoss/zssessentials/blob/master/src/main/webapp/advanced/customToolbar.zul customToolbar.zul]
 +
<source lang='xml'>
 +
    <script defer="true"><![CDATA[
 +
var hiddenButtons = ['.zstbtn-newBook', '.zstbtn-saveBook', '.zstbtn-exportPDF', '.zstbtn-sortAndFilter'
 +
, '.zschktbtn-protectSheet', '.zstbtn-insertPicture', '.zstbtn-insertChart'];
 +
 +
jq.each(hiddenButtons, function(index, selector){
 +
jq(selector).hide();
 +
});
 +
    ]]></script>
 +
</source>
  
 
{{ZKSpreadsheetEssentialsPageFooter}}
 
{{ZKSpreadsheetEssentialsPageFooter}}

Latest revision as of 12:51, 19 January 2022




Overview

Three toolbar buttons in out-of-box Spreadsheet are disabled by default: "New Book", "Save Book", and "Export to PDF" for they are not implemented yet. That's because the implementation of these functions quite depends on your requirement so 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.

Steps to implement logic for a toolbar button

  1. Create a class to implement UserActionHandler.
    There are some methods you have to implement - isEnabled() and process(). The isEnabled() which returns the enabled state of the handler is invoked by UserActionManager when Spreadsheet needs to refresh toolbar button's 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 while UserActionManager.setHandler() will remove other existing handlers and add the passed one.


Create User Action Handlers

New Book

"New Book" button will make Spreadsheet load a blank Excel file. We create NewBookHandler to implement this function, the source code 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 if you have handled the action.

Save Book

"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. Regarding how to implement the saving, you can refer to Export to Excel.

Register User Action Handlers

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

The source code below demonstrates 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 name. Toolbar button belongs to DefaultUserActionManagerCtrl.Category.AUXACTION.
  • Line 15: The second parameter is action name. Each toolbar button corresponds to one action which is defined in AuxAction.


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

Zss-essentials-customHandler.png


Append or Override with Your Handler

There are 2 ways to hook up your user action handlers:


Hide Toolbar Button

You can hide some toolbar buttons by JavaScript like:

customToolbar.zul

    <script defer="true"><![CDATA[
var hiddenButtons = ['.zstbtn-newBook', '.zstbtn-saveBook', '.zstbtn-exportPDF', '.zstbtn-sortAndFilter'
	, '.zschktbtn-protectSheet', '.zstbtn-insertPicture', '.zstbtn-insertChart'];

jq.each(hiddenButtons, function(index, selector){
	jq(selector).hide();
});
    ]]></script>


All source code listed in this book is at Github.


Last Update : 2022/01/19

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.