Jtouch25 – a mobile & touch friendly template for Joomla 2.5
How To Install Jtouch25
Document version: 3.1 Release: 2012 October 28 Author: @nguyen, @catacomber of JtouchMobile.com © 2012 JtouchMobile.com www.jtouchmobile.com
Table of Contents 1 ABOUT THIS DOCUMENT
4.1 INSTALL JTOUCH PACKAGE 4.2 JTOUCH MOBILE CONTROLLER PLUGIN SETTINGS 4.3 JTOUCH25 TEMPLATE SETTINGS
3 4 6
5 UPGRADE – UNINSTALL
5.1 UPGRADE 5.2 UNINSTALL
6 MODULE POSITIONS & HOW TO SETUP
6.1 6.2 6.3 6.4 6.5 6.6 6.7 6.8 6.9
18 19 19 21 22 23 24 24 24
CHANGE HEADER BANNER/LOGO MODULES IN TAB: BEST USE FOR VIRTUEMART 2 MODULES ADD A MENU TO MENU SCREEN PAGE ADD A “SWITCH TO MOBILE” LINK/BUTTON CREATE A NAVIGATOR MENU WITH ICON ARTICLE IMAGE SLIDE SHOW MODULE, SWIPE MODE TINY BUT COOL ARTICLE LISTING MODULE ADVANCED -‐ CONTENT OVERFLOW ADVANCED -‐ CUSTOMIZE DESKTOP SWITCHER
6.10 CREATE A “CLICK TO CALL” BUTTON 6.11 MAKE A TOUCH STYLE MENU
7 CUSTOMIZE THEME
7.1 CUSTOMIZE JQUERYMOBILE THEME 7.2 CUSTOMIZE JOOMLA LAYOUT
8 KNOW ABOUT LIMITS
8.1 MOBILE SCREEN AND COMPATIBLE ISSUES 8.2 JQUERY & JQUERYMOBILE
9 DO IT YOURSELF
10 BUSINESS WITH US
1 About this document
This document describes basic steps to setup a template for Joomla 2.5 – Jtouch25. It also provides some tips to help you use some key features of Jtouch25.
Jtouch25 is a Joomla 2.5+ template, designed with “mobile first” in mind. It is not a desktop template, but designed for mobile. Jtouch helps your website look nice and accessible on the small screen of smart phones and tablets. Key features: • Tabless design: HTML5 + CSS3 • Displays content really nicely in smart phone and tablet environments • Mobilizes not only Joomla pages, but also your Virtuemart web-‐shop and Kunena forum • Built based on jQueryMobile • Open source Jtouch25 is a product of JtouchMobile.com. For more information or support, please visit our official website: http://www.jtouchmobile.com Or follow us on Twitter: https://twitter.com/MobileMeWs For business, contact us at: Nguyen (firstname.lastname@example.org) 2
Your website is running on Joomla 2.5.6+ If you are using VirtueMart or Kunena, make sure that they are the latest versions. Our working versions: Joomla 2.5.7, jQueryMobile 1.2 final, VirtueMart 2.0.12, Kunena 2.0.2 Jtouch25 version used to write this document: 2.5.20-‐beta1
Download the latest release of the Jtouch25 template by clicking here. Unzip the downloaded package, read the HowTo document – yes, you are already doing this. We just need to do 2 main steps to install Jtouch25, do not forget one of them: 1. Install Jtouch package 2. Do the plugin settings 3. Do the template settings
4.1 Install Jtouch package Sine Jtouch 2.5.20, we just need to install only one package for the whole mobile system. Log in to your Joomla backend à Extensions à Extension Manager à Browse to file pak_jtouch25.zip à then click to “Upload & Install” button to install the package.
If everything goes fine, you can see the welcome message:
Do not skip the welcome message; there has links to 2 steps you need to be done to complete the installation.
4.2 Jtouch Mobile Controller plugin settings We want to keep our current desktop template, and only when users access our website by using a mobile device like Apple iPhone or Nokia Lumina, will Jtouch25 be used. How can we do it? Now follow the first link from the installation welcome message page, or from backend Menu à Extensions à Plugin and search for keyword “Jtouch” to open the plugin setting page.
Enable the plugin and select Public for Access first. Then take a look to the right side, where we can do some settings for the plugin:
[Tab Mobile Detect] First, we should enable the switcher function. If you do not set it, our site will never display the mobile version. You can select No for temporary turn off the mobile display for your website. If you have another template for your mobile version than Jtouch25, you can also select it in the dropdown box “Switch to Template”. If not, just let “jtouch25” as default. Do you want to apply the mobile template for tablets (iPad, Kindle Fire, etc.) or not. If yes, please set it in “Includes tablets” options. Mobile Home Page: If you want to display a different page as home page for mobile access, you can select the menu item from the dropdown box. When you set it, every time user access to your index page from their mobiles, the system will redirect to this new page, instead of using them same default page as desktop version. [Tab For Jtouch25]
4.3 Jtouch25 Template settings Click to the second link from the welcome message above to visit your Template Manager page. From there, you can click to the Jtouch25 name to open its setting page. Notes: you also can open the settings page any time by access to Menu Extensions à Template Manager
There are some options you can change for the template:
[Tab Look and Feel]
Page Theme: Select a built-‐in theme for your website. We have 5 defined color sets named from A to E.
Notes: See more color sets by clicking here. F or G are used in case you’ve designed a custom theme and named it as “F” or “G”. You can find more info or design your own theme by reading this section: “Customize jQueryMobile theme” Header Theme: Select color sets for the main header bar. Header Button: Select the layout of your header buttons: Text and Image, Only Text, or Only Image.
Footer Theme: select theme for footer bar Show Back Button: Always display a “back” button on the header bar. You can select to display the button with text and image, or just text, or turn it off. Fixed Header: The header bar on top of the page. Select “Yes” to stick it always on top of the screen, even if you scroll down the page.
Page Transition: Effect (slide, fade…) when you click on the “Menu” or “Back” icon. Note: Some devices do not support fixed header, flip or turn effects. Keep the default settings if you want those features to work on most devices. Main Banner: This is the URL to the picture you want to show as your website logo or main banner. A [300 x 70] px banner with logo + slogan is a good size for most mobile screens The URL can be a relative link, or full path link, for example: images/mybanner.png or http://www.jtouchmobile.com/images/mybanner.png Switch to Desktop button: enable the switching button or not. If you have select TOP or BOTTOM, the button will be shown on Menu screen page. User can click there to switch from mobile view to desktop view.
Desktop Template ID: You can enable a “Switch to Desktop” button on the Menu screen by specifying the ID of your desktop template here. To find the ID, just open the template manager page (Extensions à Template Manager). Those IDs are in the right hand column of the list. Desktop page: If you have enabled the switching, then you can select which desktop page will be redirect to after the switching: current page – which user is viewing mobile his mobile – or redirect to a specific page from drop-‐down list
From the picture above, we put the switching button to top of the Menu screen, and if user clicks to this button, he will be redirect to the “VirtueMart” page
And at any time, you can click on the button mobile site in a popup window.
to preview your
Important! Jtouch25 can “remember” your last viewing mode (i.e.: desktop or mobile). If you do a preview of the mobile site on a desktop browser, the next time access to the page, you will see the MOBILE version, instead of DESKTOP. To let Jtouch switch back to the desktop view, always remember click to the TOP bar of the preview window if you want to close preview mode. You also can clear cookies of your web browser to come back to your desktop version.
[Tab iOS Devices]
Add to Home Screen: displays a dialog box which asks your visitor to add your website icon to their iOS home screen. This dialog is displayed the first time the visitor visits your website or if your website is not added to their home screen yet.
You can change the default logo (Jtouch logo) by your website logo be follow the next setting “Icons Folder”. Icons Folder: This is a folder placed in the Jtouch25 template (/templates/jtouch25), (you can see it if you look at your website via ftp). It contains icon files, which are used to display your favicon, your web app icon (like the dialog above) on iOS devices. Please check this folder to find out how many icons should be created and the size of each of them. For example, “57” indicates a pixel size of 57.
“icons” folder You can create your own icons in these sizes and copy them via ftp to this folder in your site. Then the name of the folder that would go in the “Icons Folder” slot under “IOS Devices” tab would be “icons”.
But if you want to make it so you don’t need to replace your icons each time there is an update of Jtouch25, create a new folder there via ftp and place your personalized icons in that new folder using the same sizes as above of your icon. You could name the folder, for example, myicons. Then “myicons” would go in the “Icons Folder” slot, not “icons”. [Tab Advanced Parameters]
So remember every time you turn the Debug Mode to OFF, please click to the Clear Cache button on top of “Advanced Parameters” tab. It will open the caching page, from there you can select “jtouch25” folder, delete it to let the system re-‐create new cached files.
Show powered by: Displays a link to JtouchMobile.com. You can turn it off, but please keep it on to help us spread the Jtouch template to the world. Module Mapping: Enter a position alias to map your desktop modules to mobile. For example: if you want to display modules placed on the 'left' position of your desktop template to the 'jtouch-‐user1' position of Jtouch25, enter 'left' to the 'jtouch-‐user1' input box. [Tab Google Settings]
Use ReCaptcha: If you are using ReCaptcha for login/registration forms, please enable this option and also (re) input the public key you got from Google Recaptcha. Jtouch25 does not use a ReCaptcha plugin – that’s why you should enter the key here. Use Google Analytics: You can add your GA codes (account and domain) to enable tracking by using Google Analytics service. Enable Google AdSense: As GA setup, use this option to enable Google AdSense display on all pages of your website. You can select top, bottom or both positions. Please note that this option is used in case you are using Jtouch25 as your template for mobile access. On desktop, you can find a ton of Google AdSense modules in the Joomla Extensions list. 14
For VirtueMart 2 (2.0.11 or higher) Responsive Layout: Select YES if your current template of VirtueMart 2 does not display well on mobile screen. Then download our extra template for VM, follow it instruction on how to install and mobilize your shopping cart. Notes: The VM mobilizing feature is only available for our GOLD Donator. Check and make sure that you have these folder in /templates/jtouch25/html folder:
After do all those settings, click to the Save or Save & Close button to apply it for Jtouch25 template. That’s all for the Jtouch25 template setup. Next, we continue our work by configure the Jtouch Mobile Controller plugin.
5 Upgrade – Uninstall 5.1 Upgrade Which Joomla 2.5, you can do the upgrade just like install new extension. Jtouch25 is designed to keep your previous works on template settings or override. But we’re always asking you do a full backup first, before you do any new installation or upgrade. AkeebarBackup (http://akeebabackup.com) is a recommended tool for backup a Joomla! website. Recommend: If you are using Jtouch 2.5.12, to upgrade to Jtouch 2.5.20, we recommend you uninstall Jtouch first, and then reinstall it as a new setup.
From Joomla admin menu > Extensions > Extension Manager > click to tab “Manage”: Search for keyword “jtouch25”, select those 2 extensions and then click to “Uninstall” icon to complete the removal.
6 Module positions & how to setup We have about 8 positions where you can place modules. Some people asked us why they have different names than usual: “jtouch-‐top”, “jtouch-‐menu”, “jtouch-‐rhtools”… instead of “top”, “right”…? à Well, we can change them to the usual but they are different because we want you to know that not all of your modules, which are designed for desktop, can work well on mobile. You need to test and make sure that every module placed to the 16
Jtouch template will work. You can change Jtouch naming by editing options of “Module Mapping” in Jtouch template settings. __________________ I can’t find those positions; say “jtouch-‐top”, “jtouch-‐user1”, from the “Select position” list? à We do not need to press the “select position” button, just put the name of the position in the input box
Here are the eight positions graphically: (View larger size by opens the file jtouch25.template.positions.jpg) Top: Main:
6.1 Change header banner/logo -‐ Design a 300x70px banner with logo + slogan, upload it to your Joomla hosting, set its path to the “Main Banner “ option in the Jtouch25 template setting to have a top banner for your mobile site, like this:
6.2 Modules in tab: best use for Virtuemart 2 modules -‐ Assign VM Cart, VM Category and Login modules to jtouch-‐tools position to have a nice cart page:
6.3 Add a menu to Menu screen page -‐ If your desktop main menu is too complicated, and has more pages than can work well in mobile à then you need to create a new menu with less menu items à then put that menu module to jtouch-‐menu position. When clicking to the “Menu” button on header bar, you will have a touch friendly menu page, like this:
How do I do this? You need to use Menu Manager to make a new menu for your mobile view (with menu items you want to display on mobile) and make a new menu module for your mobile menu and assign that module to the jtouch-‐menu position and to your mobile menu. For the new menu: Go to Menu Manager and create a new menu. Call it something like Mobile Menu. Then add new menu items for the items on your main desktop menu that you want to show up in your mobile view. For example, create a menu item “Home”, give it Menu item type “Menu Item Alias”, call it “Home”. Make sure you have created a module for your mobile view in Module Manager. See below. When your new mobile menu is set up to show the menu items you want to display on mobile, go to the right hand side of the menu where it says “Module Assigned for this Menu Item”. Use the drop down menu and choose the name of the Module you assigned to your Mobile View for Jtouch. See below. For the new module: From Module Manager à Add New à Module à on Module setting, input "jtouch-‐ menu" to the "Position" option. Where it says "Select Menu" choose the name of the special menu you made in Menu Manager for what you wanted to show on mobile. For Module Assignment, choose "on all pages" and checkmark all the items that are in your menu. 20
6.4 Add a “Switch to Mobile” link/button In case you want to add a link on your desktop menu to switch back to mobile: "Switch to Mobile Version", just create a web link with a url like this: http://www.your-‐domain.com/index.php?jtpl=X -‐ If you are using Joomla 1.5, then X is the name of Jtouch template: http://www.your-‐domain.com/index.php?jtpl=jtouch -‐ If your Joomla is 2.5, then X is the ID of our Jtouch25 template. You can see its ID in the list of the Template Manager. For example: http://www.JtouchMobile.com/index.php?jtpl=118
6.5 Create a navigator menu with icon -‐ Create a menu module; add “-‐nav” to its Menu class suffix option, put it to “jtouch-‐nav” position; Module Menu settings:
On the Advanced Options tab:
Then you will have a cool navigator menu like this:
-‐ The icon is just appearing if you have select image for its menu item. Do it when create or edit a menu item -‐ Do not put more than 3 items on a horizontal bar -‐ Create a custom html module, put it to the “jtouch-‐footer” position to have some copyright info for your mobile site, like this:
6.6 Article image slide show module, swipe mode -‐ To have a swipe slide show for articles, create a newsflash module, from the “Advanced options” tab à select “jtouch-‐slideshow” for “Alternative layout”:
Make sure that you have at least one picture in the short description section of each article.
Swipe to left or right to see each slide’s content.
6.7 Tiny but cool article listing module
To display a list of articles with a small picture on the left, you can put an “article module” to jtouch-‐user1 or jtouch-‐user2, and, on the “Advanced options” tab of the module settings, remember to select “jtouch-‐list” for the “Alternative layout” option:
Alternative layout is jtouch-‐list
Here it is
6.9 Advanced -‐ Customize Desktop Switcher
If you have a different home page for mobile and desktop, then you should not input ID to "Desktop Template ID" option. You need to create an html static link, and put it to the "jtouch-‐menu" position. Here is the content for the static module:
<a href="index.php?jtpl=YOUR_DESKTOP_TPL_ID" dataicon="gear" data-role="button" target="_self" datamini="true">Switch to Desktop version</a> “YOUR_DESKTOP_TPL_ID” is the ID of the template you are using for desktop. It will help you come back to the “index.php” page of desktop, whatever the url/page you have for your mobile version.
6.10 Create a “Click to Call” button If you want to put “click to call links” for your mobile browser, you can find help here: http://www.mobilexweb.com/blog/click-‐to-‐call-‐links-‐mobile-‐browsers
6.11 Make a Touch Style Menu
And it’s easy to add a “touch” style to your content page: It is just html tags with some special attributes added. For example, if you’d like to have a list view like our menu
Just create an ul-‐li as normally <ul> <li><a href="acura.html">Acura</a></li> <li><a href="audi.html">Audi</a></li> <li><a href="bmw.html">BMW</a></li> </ul> And then add some attributes to <ul> tag: <ul data-role="listview" data-theme="a">
Or do want to have a button without any code? Here is the code: <a href="index.html" data-role="button">Link button</a> Easy? Yes, because Jtouch uses jQueryMobile as its core engine.
7 Customize theme
Jtouch25 has good css override functionality so that you can add your own css code without worrying that a future upgrade of the template may remove that code. There are 2 types of css customization: jQueryMobile theme and your Joomla layout. If you are not a web developer, we do not recommend you following these steps. Please contact a developer for help
7.1 Customize jQueryMobile theme Jtouch25 uses the jQueryMobile platform to create the template. With jQueryMobile, you can create a new theme in just a few minutes. First, you should understand how jQuery builds a new theme: http://jquerymobile.com/demos/1.2.0/docs/api/themes.html The great thing is, we do not need to code, then build, a css file, we have a visual editor where you just need to click – click then click to download the theme. Here are the steps: Visit http://jquerymobile.com/themeroller, Click on the “Version” and select 1.2.0
Remove current swatches by clicking on “Delete” of each swatch panel. We just need to design one theme.
Click the “Inspector” button to turn it on:
Now click the element and change its options to have a new layout:
In this sample, the name of the new theme – swatch – is “A” When you think the new theme is ok, click on the “Download” button
à enter “jtouch-‐custom” for the “Theme Name” and then click “Download Zip” to download the theme to your end. Unzip the downloaded file:
Copy the file “jtouchcustom.min.css” to ““/template/jtouch25/css” folder of your Joomla installation, then rename the file to “jtouch-‐custom.css”
Now come back to the Jtouch25 template setting, make sure that you have selected “A” for both page theme and header theme:
Remember? We have designed the new theme with swatch-‐name is “A”. On tab “Advanced Parameters”, make sure that the option “Debug” is selected to ON:
If you do a full customize swatches, from A to E, then on option “JQM CSS” you can set to to reduce duplicate css and file size. Save those settings and go back to your mobile site and see our new theme applied:
New theme If everything is fine, you can set the “Debug” option to OFF and remember to click to the “Clear Cache” button.
7.2 Customize Joomla layout
The jQueryMobile theme applies to the whole layout, but in case you want to change the css for a specific element, we have another file to put the new css code to: /templates/jtouch25/css/-‐customize/mytheme.css
-‐ Rename the “-‐customize” folder to “customize” then open the file “mythem.css” in a plain text/css editor, and put your css code to:
Red color for <h3> tag, italic style -‐ Save it, go back to your site and see how it looks:
You can see it in /templates/jtouch25/html folder. Some users report that the Jtouch25 template works well with sh404SEF and uddeIM extensions.
8.2 jQuery & jQueryMobile
Our template is building based on jQuery 1.82 & jQueryMobile 1.2.0; It is always upgraded to the latest version of those 2 scripts. If you have jQuery scripts included by another extension, you can turn off the version called by Jtouch25 template. To do it, please open the Jtouch template setting page à tab Advanced Parameters à option “Use default jQuery” set to NO.
9 Do it yourself
Jtouch25 is a free and open source project, released under the GPL 3 license. You can download, create your own customization, and redistribute it without permission from the author, but we ask that you keep the license and author’s name notes in Jtouch25’s source code. Here are some resources that may be useful to you: • Learn about jQueryMobile: http://jquerymobile.com • Design your own theme: http://jquerymobile.com/themeroller If you need a hand, feel free to post it on our forum: http://www.JtouchMobile.com/forum
10 Business with us
For any business discussion, please contact us via email@example.com. (Please do not send support question, you can post or search for answers from our forum).