What is jQuery UI?
jQuery is a JavaScript library, mostly used for expediting script writing. jQuery UI is a user interface built with jQuery. In the words of jQueryUI.com:
jQuery UI is a curated set of user interface interactions, effects, widgets, and themes built on top of the jQuery JavaScript Library. Whether you're building highly interactive web applications or you just need to add a date picker to a form control, jQuery UI is the perfect choice.
Now you might think "hey, that sounds nice!", and "how do I use it on my website?". You can find instructions on how to use jQuery UI on their website, here.
But, lucky for those of us using mojoPortal, jQuery is already built in — and so is jQuery UI. This post will explain how to use it with mojoPortal.
Creation
The first thing you need before you can integrate a new UI style into mojoPortal, is a new UI style. I highly suggest using the jQuery UI Themeroller, as it is much easier than manually changing the CSS and images for an old UI theme.
Before you start, you might find it helpful to click the "gallery" tab on the left and look through the native themes to see if they have something a little closer to what you want. Once you've found one that you like, click the "edit" button under it in the gallery, and you're ready to begin making changes.
When I do this, I usually go to my mojoPortal site design and use a color-picker to pick out the primary colors from the skin, then add them to my UI theme until it matches the skin pretty well. Hint: The parts of mojoPortal that use the UI tend to use it very heavily, so you'll want to go easy on the bright colors.
Once you have the theme the way you like it, click the "download theme" button. This will bring you to a page that lets you pick what UI features you need. You can disable these as you like, but if you don't care about the file size just leave it all on the defaults and scroll to the bottom of the page, where you can name your theme and then click download again.
Encouragement
The next part can be a little confusing the first time you do it (which is why I wrote instructions), but after you get through it once you'll realize it's actually quite easy. Working for i7MEDIA, I do it on a regular basis and now the whole process only takes me 5 minutes.
I've written detailed instructions below, if you follow them it shouldn't take you too long either. Have fun!
Installation
Once you've gotten your theme downloaded, you'll need to extract the zip file into some folder on your computer. Next, navigate within that folder to the "css" folder, and then to the folder named whatever you named the theme (default is "custom-theme"). Now just follow these instructions:
- Inside of the "custom-theme" folder, there are two css files and a folder.
- Before putting them in your skin, you'll want to rename "jquery-ui-#.#.#.custom.css" to "style-jquery.css", and rename the "images" folder to "jquery-images".
- Copy the renamed images folder and css file into your skin.
- Open the "style.config" file within your skin and add a line that corresponds with the name of the new file.
In example: <file>style-jquery.css</file> — where "style-jquery.css" is the name of the css file you copied from the folder.
- Now there's some slight editing you need to do within the jquery css file. Open it and do a "find-and-replace" (usually ctrl+f or ctrl+h) for the following keys:
- Find: (images/ — Replace with: ('jquery-images/ [1].
- Find: .png) — Replace with: .png') [2].
- Find: (opacity — Replace with: ('opacity.
- Now for the next one, you can't automate the find and replace because the numbers at the end of the "opacity" rule are always different. You'll need to look for any rules like this: filter:Alpha('Opacity=#), and replace them with this: filter:Alpha('Opacity=#') — The only difference being the new apostrophe before the last parenthesis.
- Next, open your "layout.master" file, and search for: <portal:StyleSheetCombiner. Once you've found it, check for the following key inside of it: IncludeJQueryUI="false". If this is set for "false", you'll be okay — if it is "true", change it to "false".
Hopefully, now your new UI theme works. However, if you have a really old version of mojoPortal, or are using a really old skin, you might need to read the next section, too.
Changing mojoPortal's native jQuery version
As of this writing, the latest version of jQuery UI is 1.9.2. The latest version of mojoPortal (2.3.9.4) ships with UI version 1.9.0 — as you can imagine, this could be a problem.
Usually, your particular skin will be configured to use the version of the UI that its theme was built to use when it was created. However, if you try to upload a new UI theme as per the instructions above, but find that it is not displaying properly or certain features of the UI are buggy/broken, you might need to force the mojoPortal installation you have to use a new version of the UI.
To do this, simply follow these instructions:
- Open the layout.master file in your skin.
- Search for the following line: <portal:ScriptLoader.
- Make sure that the ScriptLoader has the following key: AssumejQueryUiIsLoaded="true"
- Once that's done, add the following line somewhere under the ScriptLoader:
<script src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.9.2/jquery-ui.min.js" type="text/javascript"></script> - [3]
- The numbers in that link can be changed from "1.9.2", to whatever is the latest version of jQuery UI. You can find what the latest version is and easily find the google CDN link at the bottom of this page, under "quick access".
You might also find this article helpful: http://www.mojoportal.com/self-hosting-jquery-jquery-ui-files
Help
If you've read this article, followed the instructions, and ripped out your hair trying to figure out why something is still broken… Well, you might need a psychiatrist — but you can also just try asking us for help in the comments section below!
[1] In this case, "jquery-images" is the name of the "images" folder that you renamed before putting it in your skin.
[2] The apostrophes are necessary to stop the StyleSheetCombiner from failing to combine the CSS properly.
[3] If your site has SSL, or if you just prefer not to call the script this way, you can call call it via the web.config.