As a developer my primary interest is to make an application that is easy to use and that works perfectly. Somewhere near the bottom of my priorities list is making it look nice. I am not at all saying that I don’t care what it looks like (that would be unprofessional). It’s just something that I think that I’ll do when the fun stuff is done.
When that day comes there are times that I’ll look to purchase a theme. For example, a site like Themeforest has thousands of templates available for purchase. So where do you begin? I will talk about some of my experience procuring a theme for a web blog that I wrote a few years ago.
Shopping is Fun!?
The first part of this task was actually a lot of fun and occasionally frustrating. Other than knowing that I wanted something that was Bootstrapped I wasn’t really sure what I was looking for. My recommendation is that you look for something that does not require a lot of photoshop work (psd files) and that comes with documentation. After all, purchasing a theme is more than just trying to make your app look nice. A good theme will come with scores of UI capabilities that will make your dev work easier.
Template Selection Advice
The first part of this task was actually a lot of fun and occasionally frustrating. Other than knowing that I wanted something that was Bootstrapped I wasn’t really sure what I was looking for. My recommendation is that you look for somethign that does not require a lot of photoshop work (psd files) and that comes with documentation. After all, purchasing a theme is more than just trying to make your app look nice. A good theme will come with scores of UI capabilities that will make your dev work easier.
You get what you pay for. The templates that cost a few bucks (I think I paid $27) came with all kinds of bells and whistles. For example, the theme that I purchased had pages and pages of examples of just about anything that you’d want to do on a site.
Most packages included several different types of looks – magazine, newspaper, admin dashboard, etc. However, usually only the flashy template was the one highlighted on the sites selling the packages. Don’t be afraid to look past the main theme to find a diamond in the rough.
The magazine themes often look really cool but unless you are planning on a graphics-heavy site (e.g. you’re running a site for a magazine) these probably are not for you. I found the admin dashboard themes to be closer to what I was looking for in a dynamic blog.
Got a Whole Lot of Files. Now What?
Congratulations! You’ve spent hours and days sifting through sites to find the template that was yours and for your efforts you were rewarded with a big fat zip file. You unzip the file on your server and…. now what? If you’re not a UI wiz (or if you’re like me and you like to take a systematic approach to development) I highly recommend that you break this project into pieces so as to minimize the likelihood of you getting into a place that you don’t want to be. Trust me, there are a lot of moving parts here.
The first step is actually pretty easy: unzip that puppy directly into your dev client (or whatever your platform requires). Or desktop, if you are working locally. Why? Well, several reasons. You will want to make sure that there aren’t any basic issues with your setup. The site should work exactly as it does on the site from which you purchased it. Trust me, you will want to refer back to it often to get examples of things that you want to incorporate in your site.
You might want to directly reference the css, js and other files that you will need in your new site from these desktop folders. Also, there is the guilty pleasure factor. sometimes it is just fun to click around the local representation of your theme.
Theme Me
So far pretty easy, right? Now it’s about to get real. The biggest problems I had BY FAR were the mixing of the various jQuery files with an XPage/Dojo environment. Once again, take things slowly and check your work every now and then. What do I mean by that? Developer tools (Chrome, Firebug, etc) are your friend. When the page loads looks to see that all files load correctly on the Network tab (tip: disable your cache to enable “p**n” mode). Then stroll over to the console to see if anything died during the loading of the environment. If you find an error I highly recommend nipping in the programmatic rear immediately as it is probably the result of recent monkeying.
Before we create our first XPage we need to set up our environment. As I mentioned earlier one of the stickiest parts of this exercise is the loading of the scores of files that make up modern websites. I higly, highly, highly recommend taking a little time to learn about themes. When I made my first site I decided to take the shortcut (putting the references to all of the files on each XPage) and regretted it later. The IBM wiki does a nice job giving you the basics (along with a lot of stuff you’ll probably never use). All you really need to do is figure out how to phrase css and js files. Here is an example:
application/x-javascript
https://google-code-prettify.googlecode.com/svn/loader/run_prettify.js
text/css
/path/someotherstyle.cssIn my experiences I have found that if I listed the files in my theme in the same order that they are in the html file that life was good. Once you get everything working you can try to move things around to improve performance.
The Grand Transition Begins
The point of breaking all of this into these small tasks is to eliminate all of the numerous things that can go wrong. From my own experience I can tell you that you can spend hours trying to figure out why a small error in your browser console. At this point you have created an environment where you can finally transition all of the fancy UI elements into an XPage. Assuming you followed my advice and created a theme this should be fairly straight-forward task.
Open the web page that you want to convert into an XPage. Preview the source of the page.
Copy everything inside of the body tag, including the body tag itself. Paste it into your XPage.
Potential for Gray Hair Ahead! Please do not take the following advice lightly
I want to emphasize that there are a few things that you might see in the html that won’t sit well with the designer and/or the XPage server.
Head tags aren’t recognized as Domino generates them for you. If you absolutely need to put something in a head tag you can use xp:head or google some of the other methods. Body tags will cause side effects that are not desirable because Domino generates the body tags for you. You can close Domino’s body tag and start your own body if you really want to – the result is a second form being loaded in the browser. In my template I found that I could remove the body tag completely as it wasn’t functional.
All html elements must be closed properly. For example, my template had several instances where it used a standalone -hr- tag. Domino designer forces you to put in and end tag before it will compile.
With that you should be able to save (and build!) your XPage.
Is There a Doctor in the House?
At this point we have gotten past the big, scary UI and we are in the cozy confines of a (hopefully) familiar environment. If you are making a small app that won’t require much more than this page you could leave everything as is. Seeing as this is almost never the case you’ve got some surgery to do. Here are some of the things that you will want to consider:
How are you referencing your content? Will each type of content have its own XPage? Or will you be dynamically loading the content via dynamic content? I chose the latter approach for this website. It is really easy to do and there are some really neat benefits. For example, in this site I’ve chosen to load the content in the center bootstrap column. You’ll notice that the content will load and the rest of the page has remained unchanged. I don’t need to worry about reloading selected tabs or anything like that.
Is this going to be a multi-page application? If so I recommend moving chunks of code into controls. For example, in the right column I have a control for my blogs and another control for my links. To more easily accomplish this goal I recommend commenting the *&#$ out of the code before going into surgery. Once you have START and END of each logical section it is MUCH easier to move things into controls. Once again (I know I am beating a dead horse here) doing things one at a time makes it a lot easier to correct the errors.
Only use XPage elements when absolutely necessary. Leave the original HTML as it was. Yes, this means that it probably won’t display nicely in the Designer but – in my opinion – you’re better off developing almost exclusively in Source and not the Designer UI.
XPage thinks it is doing you a favor by injecting span tags around XPage elements at run time. This isn’t a problem until it is a problem. As I started to put in fields to generate content-driven pages I noticed that my XPage did not look exactly the way it did before I started adding XPage elements. The reason for this is that my html now had span tags around them. One easy way to prevent this from happening is to go into the Source and delete the ID property from the element. Of course, if you do this you won’t be able to reference the element by ID. I strongly recommend using jQuery to reference the elements client-side.
One of the first thing you might notice is how slow your page looks in the designer client. Fortunately there is a simple trick to correcting this issue. If you have carved your page up into controls you have the ability to tell the designer to not try to render a given control. See this page for the specific example (it is very easy).
Play Time
If purchased a full-featured template (and if you’re like me) you probably didn’t spend a whole lot of time looking past the items in the front window of the virtual store. You saw the proverbial candy and said “gimme gimme gimme”. Now that you’ve got your XPage working with your spiffy UI take a few minutes to go back and see what is in your toolbox. There are probably scores of widgets, portlets, fonts, glyphicons, etc, that are available for use in your site. During the writing of this article I twice changed the format of the article. I first tried a left-hand navigation and then realized I didn’t like it. I am not shot in the rear with the accordion-style layout but it will do for now. After all, when one’s purpose in making the site is to constantly improve the site I suppose it isn’t a bad thing to learn a thing or two along the way.
