Friday, 11 July 2014

Select Bootstrap Themes from Drop-down

As mentioned in the previous post, I have just started using the fantastic Bootstrap4XPages plugin project.

During the setup process there was one very minor thing that really annoyed me, so I thought I would see if I could come up with a solution! The solution is a minor change to the Bootstrap4XPages documentation, and a small change to the Extension Library.

Did I mention how fantastic Bootstrap4XPages is? Can I also mention how fantastic the Extension Library is? What follows here reads like a rant, but really I am just trying to give a feel for the user experience of being soooo close to having something work, but it not working. The change to Bootstrap4XPages project can be made easily but for the Extension library I want IBM to consider the proposed solution (or similar variation) for inclusion in the Extension Library and by documenting the user experience it will hopefully give some feeling for the need for this solution.

So what is the annoying thing?


After all the setup steps (install plugin etc.) you think "Ok now I'll set the theme to bootstrap!"

So you open up your Xsp Properties and expand the drop down box, only to find....



 Now, as a user experience this is confusing, because I know the OneUI v3 theme is coming from a plugin, and I also know that LocalAppTheme (at the bottom of the list) is from the current NSF, so I know this is a dynamic list. It makes me question, Have I installed the plugin properly? So I check my designer plugin details, and verify Bootstrap is installed.



It seems another user had the same experience

So I look at the Readme file in the github project, and I can't see anything about the theme names, so I look in the themes package and  I can see all the theme files.



So I decide I want the latest which must be 'bootstrapv311' so I put that in to my nsf's Xsp Properties






Ok time to see some bootstrappy goodness!


But there is no bootstrap goodness to be found.

A deeper look into the bootstrap source code and into the BootstrapStyleKitFactory and you can see the actual names that need to be put in the theme edit box.







So I will try that out instead:







It must work this time:

And it does work! hooray! Now that I've figured this out,  I will just carry on without telling anyone. NO! That is not what Open source is all about! I am going to DO something about it and share it back with the community!

Simple Change for Bootstrap4Xpages project

A very simple change to the Bootstrap4XPages project, is to simply put a section in the readme which shows the available themes, so I did this on my fork of Bootstrap:



and then created a pull request to see if I can get it into the OpenNTF/Bootstrap4XPages project

I've actually never done a pull request! First time for everything hey? Hopefully it gets through!

Bigger change to Extension Library

So, that was the simple solution, but wouldn't it be better and more foolproof if the available themes showed up to be selected in the Themes drop-down?

Gareth Keenan Investigates

I started invetigating, how did they get the One UI V 3 theme in the list? I know that the theme is supplied from the extension library. So I looked in the latest source code  for the extension library, in particular the Designer Tooling plugins. These are the plugins that contribute to domino designer UI. It turns out that the code for Xsp Properties editor (where you select the theme) is actually contained in the extension library, specifically in the XSPPage.java file in the  com.ibm.xsp.extlib.designer.xspprops plugin.




Looking within the XSPPage.java file, we can see we are getting somewhere, these entries look suspicious:

and on further inspection they are used in the constructor of the Xsp Properties page when creating some 'AppThemeLookup's.

 

These 'AppThemeLookup' objects are what supply the ComboBox with it's label/value entries.
You can see 5 of them, as they correspond to the  6 lookups (atl2 is used twice)





The class for AppThemeLookup is in the com.ibm.xsp.extlib.designer plugin


Looking at the constructor we can get a picture of how it is used.


Basically, it creates an AppThemeLookup which has it's own list of codes and labels. The codes are the theme id e.g. oneuiv2 and the labels are something more readable e.g. OneUI v2.
It then retrieves a themeLookup from the current nsf (DesignerProject) which represents the list of themes that are have been created in the the Resources -> Themes section of the NSF.


So I came up with a way to insert some entries that are contributed from another plugin. 

The way I came up with

One way I know a plugin can contribute to another without knowing too much about each other is an extension point. This extension point will need an interface so I will create one called  ThemeLookupEntryProvider, I also created a simple object to represent the code label pair ThemeLookupEntry

A contributing plugin will simply need to implement the ThemeNameProvider interface which will return a List of ThemeLookupEntries

So then I created the Extension Point itself





 and this basically says "ok there is a new extension point called 'com.ibm.xsp.extlib.designer.themeLookupEntryProvider' and it is going to have some 'themeLookupEntryProvider's on it.

So, the next step is to decide what to do with any ThemeLookupEntryProviders that are contributed to this extension point.
I just wrote a class ThemeLookupEntryContributions that is used statically, and it has a public 'getThemeLookupEntries' function which
will lazy load the ThemeLookupEntries from any ThemeLookupEntryProviders that have registered with the extension point. (I didn't screen shot this one but it is in the github repo see the conclusion)

Finally, I made a change to the AppThemeLookup class, so that it will also check with our ThemeLookupEntryContributions and contribute these to the lookup.


Note: there are some other changes to the size, getLabel, getCode functions, but these screenshots are getting out of hand :)

Contributing to the Extension point

In this example, I will use the bootswatch project I am making, and contribute the bootswatch themes. But the same concept can be done for the Bootstrap4XPages project.

First I will create a class that implements 'ThemeLookupEntryProvider' and have it return a list of the ThemeLookupEntries




Then, I will register this class as an extension in my Bootswatch plugin's plugin.xml


And that should be It!

I will now launch designer from eclipse to test my plugin (Thanks Ralf Petter for the instructions on how to do this, and thanks Nathan Freeman for the XPages SDK!)

Fingers crossed....



Lets choose a theme, how about slate:



lets check the xsp.properties is then saved correctly:
 

Now for the big test! Let's see if it works


Looks like slate to me!

Conclusion

So, it is possible that we can choose Bootstrap Themes from the theme drop-down. But you need to modify the Extension Library to do it

I have published the changes I made in this Github Repository camac/scrOpenNTF-designer

I have posted a feature request on OpenNTF, which will link to this blog entry and the github repository!

If you think this is something that should be in the Extension Library, add you thoughts to my feature Request so that IBM team can see too!

Hope you enjoyed the demonstration!




2 comments:

  1. I got what you mean , thanks for posting .Woh I am happy to this website through google. bootstrap templates

    ReplyDelete
  2. I recently came across your blog and have been reading along. I thought I would leave my first comment. I don't know what to say except that I have enjoyed reading. Nice blog. I will keep visiting this blog very often. free stock photos

    ReplyDelete