Permlink Replies: 148 - Pages: 10 [ 1 2 3 4 5 | Next ] - Last Post: 25-Dec-2014 19:48 Last Post By: davidekholm Threads: [ Previous | Next ]
davidekholm

Posts: 3,545
Registered: 18-Oct-2002
Context Sensitive Help in jAlbum 12.3
Posted: 06-Nov-2014 18:04
  Click to reply to this thread Reply
Hi all,

jAlbum 12.3 is soon to be released. Download the Windows beta or Mac beta here.

Some highlights:
  • Context sensitive help - works for skins too!
  • Supports scripting in any language supported by the Java Virtual Machine. Currently bundled with JavaScript, but it's also possible to script in Jython, Scala, Groovy and a host of other languages. (Just drop the relevant script language .jar file in jAlbum's "lib" or "ext" folder to install support). Want to use JavaScript instead of BeanShell? Just name your onload file onload.js or name your init file init.js.
  • Improved crop filter
  • You can now copy and paste titles and keywords to multiple images as well as captions
  • Experimental JavaFX skin UI support

In this post I'm focusing on the new context sensitive help cause we're now addressing the #1 thing jAlbum has been criticized for over the years - lack of proper documentation. jAlbum 12.3 now has a ? button in the corner of each window and dialogue. Pressing it or pressing F1 will bring up the correct help page in our wiki.

If help documentation is missing for a specific part of the user interface, for instance a skin, then the ? button goes away.

People with admin rights can edit and improve these wiki based help pages, and skin developers can write new help pages for their skins. If a skin developer already has its own help web site, it's naturally fine to link to that one instead.

To add support for context sensitive help to our skin, just add code like this to each settings panel
 advancedPanel.putClientProperty("helpPage", "http://jalbum.net/help/skin/MySkin/Advanced");


As soon as you've made this addition, the help button will lit up as soon as the corresponding settings panel is visible. Your skin is still compatible with older versions of jAlbum.

Eager to try it out? Download the Windows beta or Mac beta here. Once installed, check out the "onload.bsh" file of the Minimal skin for how to add context help support to your skin.

Compatibility note:
jAlbum 12.3 throws "ScriptingException" if there are scripting errors. Earlier versions of jAlbum only threw ElementException for these kinds of errors. Please ensure that your skin runs fine on jAlbum even after this change.

Please note that the documentation isn't in any releasable stage right now. I'll be working the following days with improving it. Now we at least have a proper structure for it and I'm sure it will be read now that it's just one click away. I appreciate your comments on this and naturally also getting your help in improving this wiki based documentation.
RobM

Posts: 3,049
Registered: 4-Aug-2006
Re: Context Sensitive Help in jAlbum 12.3
Posted: 06-Nov-2014 18:45   in response to: davidekholm in response to: davidekholm
  Click to reply to this thread Reply
Downloaded the Mac version and will give it a go tonight. When you say soon to be released, how long do you mean? It would help to know how long we have to give it a try and to try to modify a few skins.
RobM

Posts: 3,049
Registered: 4-Aug-2006
Re: Context Sensitive Help in jAlbum 12.3
Posted: 06-Nov-2014 22:03   in response to: RobM in response to: RobM
  Click to reply to this thread Reply
To add the help icon in a simple skin the code is added after the control panel has been defined or just before the closing brace prior to installing the components e.g.
settingsPanel.putClientProperty("helpPage", "http://mySite.me/help/skins/ThisSkin/Settings");
};
// Install components into jAlbum
window.setSkinUI(ui);
But how do you add the code for a skin that has control panels arranged in multiple tabs?

Edited by: RobM on 06-Nov-2014 21:03

Edited by: davidekholm on 06-Nov-2014 22:11 (fixed syntax error using double "helpPage" arguments)
davidekholm

Posts: 3,545
Registered: 18-Oct-2002
Re: Context Sensitive Help in jAlbum 12.3
Posted: 06-Nov-2014 22:09   in response to: RobM in response to: RobM
  Click to reply to this thread Reply
RobM wrote:
Downloaded the Mac version and will give it a go tonight. When you say soon to be released, how long do you mean? It would help to know how long we have to give it a try and to try to modify a few skins.

I estimate another week and it can be released.
davidekholm

Posts: 3,545
Registered: 18-Oct-2002
Re: Context Sensitive Help in jAlbum 12.3
Posted: 06-Nov-2014 22:13   in response to: RobM in response to: RobM
  Click to reply to this thread Reply
RobM wrote:
To add the help icon in a simple skin the code is added after the control panel has been defined or just before the closing brace prior to installing the components e.g.
settingsPanel.putClientProperty("helpPage", "http://mySite.me/help/skins/ThisSkin/Settings");
};
// Install components into jAlbum
window.setSkinUI(ui);
But how do you add the code for a skin that has control panels arranged in multiple tabs?

See the "onload.bsh" file for the Minimal skin. It's no magic to it. Each tab (actually a ControlPanel or JPanel) can have its putClientProperty method called to set the relevant help. You can call putClientProperty at any place in your onload file.
RobM

Posts: 3,049
Registered: 4-Aug-2006
Re: Context Sensitive Help in jAlbum 12.3
Posted: 06-Nov-2014 22:50   in response to: davidekholm in response to: davidekholm
  Click to reply to this thread Reply
When I started making skins I based tabs on an existing skin and the format is not the same as Minimal's (though I would use that in any future skin). The format I have (and can't figure out where/how) is
// Controls that are to be imported into JAlbum as variables
ControlPanel ui = new ControlPanel() {
	//Define variables for later use
	JCheckBox useTemplateHeader = new JCheckBox ("Used to control template stylesheets", true);	
	JTextField excludeNavLink = new JTextField("false",0);
	JTextField excludeSiblingLink = new JTextField("false",0);
 
	// Skin Theme functionality
	// misc items location
	ButtonGroup resourceFolder = new ButtonGroup();
	JRadioButton resourceFolderStandard = new JRadioButton(texts.getString("ui.resourceFolderStandard"), true);
	resourceFolderStandard.setActionCommand("standard");
	JRadioButton resourceFolderCommon = new JRadioButton(texts.getString("ui.resourceFolderCommon"), false);
	resourceFolderCommon.setActionCommand("common");
	resourceFolder.add(resourceFolderStandard);
	resourceFolder.add(resourceFolderCommon);
	JTextField browserTitle = new JTextField(texts.getString("ui.browserTitle"));
...
...
};
then
// Layout controls easily similar to how text is added in a word processor
// Gallery layout
// Tab for Misc settings folder location
ControlPanel miscSettings = new ControlPanel();
miscSettings.add("p", new JLabel(texts.getString("ui.miscSettings1")));
miscSettings.add("br", new JLabel(texts.getString("ui.miscSettings2")));
miscSettings.add("br", new JLabel(texts.getString("ui.miscSettings3")));
miscSettings.add("p", new JLabel(texts.getString("ui.miscSettings4")));
miscSettings.add("br", ui.resourceFolderStandard);
miscSettings.add(ui.resourceFolderCommon);
miscSettings.add("br", ui.customWidget);
miscSettings.add("br", ui.customWidgetRootPath);
miscSettings.add("p", new JLabel(texts.getString("ui.miscSettings5")));
miscSettings.add("hfill", ui.browserTitle);
 
setItemsForComboBox(ui.language, getSupportedLanguages());
miscSettings.add("p", new JLabel(texts.getString("ui.language")));
// set the default language to English
ui.language.setSelectedItem("en");
miscSettings.add("tab", ui.language);
 
miscSettings.add("p", new JLabel(texts.getString("ui.miscSettings6")));
 
miscSettings.add("p", new JLabel(texts.getString("ui.miscSettings7")));
 
miscSettings.add(ui.getFontButton);
miscSettings.add(ui.fontListing);
miscSettings.add("br", new JLabel(texts.getString("ui.miscSettings8")));
miscSettings.add(ui.genericFont);
 
miscSettings.add("br",ui.myFont);
ui.myFont.setBackground(Color.lightGray);
ui.myFont.setDisabledTextColor(Color.black);
miscSettings.add(ui.myFontStyle);
ui.myFontStyle.setBackground(Color.lightGray);
ui.myFontStyle.setDisabledTextColor(Color.black);
miscSettings.add(ui.myFontSize);
ui.myFontSize.setBackground(Color.lightGray);
ui.myFontSize.setDisabledTextColor(Color.black);
miscSettings.add("br left",ui.sp);
 	ui.getFontButton.addActionListener(new  java.awt.event.ActionListener() {
    	public void actionPerformed(java.awt.event.ActionEvent evt) {
 
   		if (ui.fontListing.isSelected()) {
    	    	String[] webSafeFonts={"Arial","Arial Black","Book Antiqua","Charcoal","Comic Sans MS","Courier",
        	    "Courier New","Gadget","Geneva","Georgia","Helvetica","Impact","Lucida Console","Lucida Grande","Lucida Sans Unicode","Monaco",
            "MS Sans Serif","Palatino","Palatino Linotype","Tahoma","Times","Times New Roman","Trebuchet MS","Verdana"};
    	        FontSelector fs=new FontSelector(webSafeFonts,0,0,0);
			fs.setVisible(true);
			if(fs.okPressed){
		    	ui.ta.setFont(fs.getSelectedFont());
		        ui.myFont.setText(fs.getFontName());
		        ui.myFontStyle.setText(fs.getFontStyle());
		        ui.myFontSize.setText(fs.getFontSize()+"pt");
    			    ui.myFont.setFont(fs.getFontName,0,12);
	    	  }
          		}
        else {
	    	FontSelector fs=new FontSelector(0,0,0);
			fs.setVisible(true);
       			if(fs.okPressed){
		   		ui.ta.setFont(fs.getSelectedFont());
		        ui.myFont.setText(fs.getFontName());
		        ui.myFontStyle.setText(fs.getFontStyle());
		        ui.myFontSize.setText(fs.getFontSize()+"pt");
    			ui.myFont.setFont(fs.getFontName,0,12);
	    	 }
		}
 
    	}
});
 
miscSettings.add("br", new JLabel(texts.getString("ui.miscSettings9")));
miscSettings.add("br",ui.openSimpleXBF);
 
ui.openSimpleXBF.addActionListener(new java.awt.event.ActionListener() {
 
 	public void actionPerformed(java.awt.event.ActionEvent evt) {
 		File f=new File(skinDirectory + "/res/images/","sxbf.jpg");
     	if (f.exists()){
        	SimpleXBF sxbf=new SimpleXBF(f.getAbsolutePath());
            sxbf.setVisible(true);
            }
     	else{
    	    SimpleXBF sxbf=new SimpleXBF();
            sxbf.setVisible(true);
    	}
 
 		}
});
ui.add("p hfill", miscSettings);
Then after defining more control panels I have
// Finally install components into JAlbum
tabs = new JTabbedPane();
tabs.setName("NotablesTabs");
tabs.add(miscSettings, texts.getString("ui.miscSettings"));
tabs.add(headerSettings, texts.getString("ui.headerSettings"));
tabs.add(footerSettings, texts.getString("ui.footerSettings"));
//tabs.add(gallerySettings, texts.getString("ui.gallerySettings"));
tabs.add(thumbnailNav, texts.getString("ui.thumbnailNav"));
tabs.add(thumbnailLayout, texts.getString("ui.thumbnailLayout"));
tabs.add(thumbnailOptions, texts.getString("ui.thumbnailOptions"));
tabs.add(slideSettings, texts.getString("ui.slideSettings"));
tabs.add(slideshowPanel, "slideshow");	// Slide show: Adds the slide show 'Tab' to the existing tabs
tabs.add(aboutPanel, texts.getString("ui.aboutPanel"));
 
ui.add("vtop hfill vfill", tabs);
window.setSkinUI(ui);
jGromit

Posts: 7,269
Registered: 31-Jan-2006
Re: Context Sensitive Help in jAlbum 12.3
Posted: 06-Nov-2014 23:00   in response to: davidekholm in response to: davidekholm
  Click to reply to this thread Reply
Attachment TestGUI.java (3.2 KB)
davidekholm wrote:
It's no magic to it.

Maybe not, but I can't get it to work in a fairly simple test skin with a compiled UI. Source file attached. I get no compiler errors, but I get no "help" link, either.
RobM

Posts: 3,049
Registered: 4-Aug-2006
Re: Context Sensitive Help in jAlbum 12.3
Posted: 06-Nov-2014 23:06   in response to: jGromit in response to: jGromit
  Click to reply to this thread Reply
I can get it to work with Polyglot, which is structured like Minimal, but Notables is much older and built along the lines of: Define all control elements, define all control panels, define tab setting then add control panels to tabs. It might be easier to rebuild the onload.bsh file!
jGromit

Posts: 7,269
Registered: 31-Jan-2006
Re: Context Sensitive Help in jAlbum 12.3
Posted: 06-Nov-2014 23:16   in response to: RobM in response to: RobM
  Click to reply to this thread Reply
RobM wrote:
I can get it to work with Polyglot, which is structured like Minimal, but Notables is much older and built along the lines of: Define all control elements, define all control panels, define tab setting then add control panels to tabs. It might be easier to rebuild the onload.bsh file!

Be careful about what you wish for. Minimal is using "anonymous inner classes" in Java (don't ask me). It makes the coding simpler. Instead of thepanel.add(something), you can just write add(something). That makes moving things around on your panels waaay easier.

But there's a downside, as I discovered with Matrix. If you have a large UI, using anonymous inner classes in onload.bsh exacts a huge skin-loading speed penalty. With Matrix (and this was many versions ago), the skin loading was taking over 30 seconds. Compiling the UI cured that problem.

In short, for all but the simplest skins it's necessary to compile the UI if you want to use anonymous inner classes.
RobM

Posts: 3,049
Registered: 4-Aug-2006
Re: Context Sensitive Help in jAlbum 12.3
Posted: 07-Nov-2014 00:07   in response to: jGromit in response to: jGromit
  Click to reply to this thread Reply
David wrote
Pressing it or pressing F1 will bring up the correct help page in our wiki.
The menu item 'Help' has F1 assigned to it, but F1 is now context sensitive so the menu should have the F1 shortcut removed.

I'm not sure about the help link bringing up 'the correct help page'. In edit mode a user could be editing an image, a video or a page template; they might want information on any of the available tools. Is the intention to have a page with links to all of the possible actions a user can do?

Can a help icon be added to the slide show screen?
davidekholm

Posts: 3,545
Registered: 18-Oct-2002
Re: Context Sensitive Help in jAlbum 12.3
Posted: 07-Nov-2014 11:01   in response to: RobM in response to: RobM
  Click to reply to this thread Reply
Rob, with code like yours you could add context help support like this:
miscSettings.putClientProperty("helpPage", "http://www.mysite.com/mySkin/Misc");
headerSettings.putClientProperty("helpPage", "http://www.mysite.com/mySkin/Header");
footerSettings.putClientProperty("helpPage", "http://www.mysite.com/mySkin/Footer");
gallerySettings.putClientProperty("helpPage", "http://www.mysite.com/mySkin/Gallery");
...
davidekholm

Posts: 3,545
Registered: 18-Oct-2002
Re: Context Sensitive Help in jAlbum 12.3
Posted: 07-Nov-2014 11:26   in response to: jGromit in response to: jGromit
  Click to reply to this thread Reply
Attachment TestGUI.java (4.2 KB)
jGromit wrote:
davidekholm wrote:
It's no magic to it.

Maybe not, but I can't get it to work in a fairly simple test skin with a compiled UI. Source file attached. I get no compiler errors, but I get no "help" link, either.


I've modified your code so it works now. The reason it didn't work was because the "firstPanel" and "aboutPanel" instances weren't added as member variables of your main UI class (You had declared then inside an { anonymous constructor } so they became local variables instead). They were only added to the UI itself (using the .add method).

Your code style has all skin controls stuffed inside the UI class and not being declared in their relevant panels. With your code style (not adding "firstPanel" and "aboutPanel" as member variables), you had to do it this way, otherwise those variables would never have been found by jAlbum and injected as skin variables. Now that "firstPanel" and "aboutPanel" are also member variables of the UI class, jAlbum can traverse those and encounter any variables declared inside them, so now you can move those UI controls closer to where they are in fact being used, and you will have more modular, easy to maintain code.

If you don't wish to adjust your code style in this manner, you can still enable context help, but then you need to tell the context help system about your UI panels this way instead:
import se.datadosen.util.*;
ContextHelp help = ContextHelp.getInstance();
        help.add(firstPanel, "http://www.yoursite.com/yourSkin");
        help.add(aboutPanel, "http://www.yoursite.com/yourSkin/About");
...
The only downside with this approach is that your skin will now require jAlbum 12.3
davidekholm

Posts: 3,545
Registered: 18-Oct-2002
Re: Context Sensitive Help in jAlbum 12.3
Posted: 07-Nov-2014 11:30   in response to: RobM in response to: RobM
  Click to reply to this thread Reply
RobM wrote:
I can get it to work with Polyglot, which is structured like Minimal, but Notables is much older and built along the lines of: Define all control elements, define all control panels, define tab setting then add control panels to tabs. It might be easier to rebuild the onload.bsh file!

See my answer to jGromit, i.e either restructure your skin, or use this jAlbum 12.3 API instead:
import se.datadosen.util.*;
ContextHelp help = ContextHelp.getInstance();
        help.add(firstPanel, "http://www.yoursite.com/yourSkin");
        help.add(aboutPanel, "http://www.yoursite.com/yourSkin/About");
...
davidekholm

Posts: 3,545
Registered: 18-Oct-2002
Re: Context Sensitive Help in jAlbum 12.3
Posted: 07-Nov-2014 11:38   in response to: jGromit in response to: jGromit
  Click to reply to this thread Reply
jGromit wrote:

In short, for all but the simplest skins it's necessary to compile the UI if you want to use anonymous inner classes.

That's news to me. I've never encountered any speed difference in that regard. Are you able to put together a dummy test case?
davidekholm

Posts: 3,545
Registered: 18-Oct-2002
Re: Context Sensitive Help in jAlbum 12.3
Posted: 07-Nov-2014 11:44   in response to: RobM in response to: RobM
  Click to reply to this thread Reply
RobM wrote:
David wrote
Pressing it or pressing F1 will bring up the correct help page in our wiki.
The menu item 'Help' has F1 assigned to it, but F1 is now context sensitive so the menu should have the F1 shortcut removed.

Perhaps, or perhaps not. I understand your reasoning, but doesn't the F1 shortcut hint help hinting that you can use the F1 key too?

I'm not sure about the help link bringing up 'the correct help page'. In edit mode a user could be editing an image, a video or a page template; they might want information on any of the available tools. Is the intention to have a page with links to all of the possible actions a user can do?

The upcoming Edit documentation page will describe editing in general. If a certain image tool wishes to provide more specific help, it can. It just needs to make the help system aware of its settings panel. Once that settings panel is visible, it has precedence. Likewise, It's possible to provide a special help page when editing videos only

Can a help icon be added to the slide show screen?

Yes it can in theory, but it would make jAlbum quit the full screen mode. I hope that the tool-tips will suffice for that screen though.
Legend
Forum admins
Helpful Answer
Correct Answer

Point your RSS reader here for a feed of the latest messages in all forums