JTouch 2.5 Mobile Joomla Template User Guide

1

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 2

2 INTRODUCTION 2

3 REQUIREMENTS 3

4 INSTALL 3 4.1 INSTALL JTOUCH PACKAGE 3 4.2 JTOUCH MOBILE CONTROLLER PLUGIN SETTINGS 4 4.3 JTOUCH25 TEMPLATE SETTINGS 6

5 UPGRADE – UNINSTALL 16 5.1 UPGRADE 16 5.2 UNINSTALL 16

6 MODULE POSITIONS & HOW TO SETUP 16 6.1 CHANGE HEADER BANNER/LOGO 18 6.2 MODULES IN TAB: BEST USE FOR VIRTUEMART 2 MODULES 19 6.3 ADD A MENU TO MENU SCREEN PAGE 19 6.4 ADD A “SWITCH TO MOBILE” LINK/BUTTON 21 6.5 CREATE A NAVIGATOR MENU WITH ICON 22 6.6 ARTICLE IMAGE SLIDE SHOW MODULE, SWIPE MODE 23 6.7 TINY BUT COOL ARTICLE LISTING MODULE 24 6.8 ADVANCED -‐ CONTENT OVERFLOW 24 6.9 ADVANCED -‐ CUSTOMIZE DESKTOP SWITCHER 24

2

6.10 CREATE A “CLICK TO CALL” BUTTON 25 6.11 MAKE A TOUCH STYLE MENU 25

7 CUSTOMIZE THEME 26 7.1 CUSTOMIZE JQUERYMOBILE THEME 26 7.2 CUSTOMIZE JOOMLA LAYOUT 31

8 KNOW ABOUT LIMITS 32 8.1 MOBILE SCREEN AND COMPATIBLE ISSUES 32 8.2 JQUERY & JQUERYMOBILE 33

9 DO IT YOURSELF 33

10 BUSINESS WITH US 33

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.

2 Introduction 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 ([email protected])

3

3 Requirements 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

4 Install 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:

4

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:

5

[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]

6

Only Jtouch Scripts: Only load css and javascript resources that are provided by the Jtouch25 template, and remove all other scripts. Important: Only select No if you’re an expert in jQueryMobile or the “Yes” selection does not work with your extensions. Remove Mootools: If the “Only Jtouch Scripts” option is set to “No”, then you may want to include your resource to the HTML output; does it include Mootools and other Joomla core javascript (Mootools, caption, tooltip)? Select “Yes” is recommended in this situation. But sometimes we can select “No” if your mobile website requires Mootools script.

Since Jtouch 2.5.10, we add a “.noConflict()” option to all Jtouch core scripts. Now Jtouch can work with Mootools.

Save your settings and open the site in a mobile device to see the difference between the desktop and mobile environment.

Q: My mobile site looks like the desktop view even though I’ve cleared the browser cache? à Make sure you have installed and enabled the Jtouch mobile plugin. Then try to turn off Joomla caching (Menu Site à Global Configuration à System à Caching Setting). Some users report that their mobile website can’t work well with caching on.

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:

7

[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.

8

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.

9

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

10

And at any time, you can click on the button to preview your mobile site in a popup window.

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]

11

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”.

12

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]

Turn off Pages: You may want to turn off the display of components from your home page or other pages. Just enter the ID(s) of the Menu Item that belongs to the component that you want to turn off (unload), separated by commas, for example: 1,3,20 Debug: Turn on this option to use un-‐compressed javascript and css files. Useful for a developer, but may cause slowness in loading time. Not recommended for a live site.

Important! Since version 2.5.20, we have been added a “caching” feature to the Jtouch25 template. All main css and javascript files will be merged compressed and then save to folder “jtouch25” of the Joomla cache folder (/cache/jtouch25)

13

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.

If you do not clear it, the template will keep running with old css/js files, and may lost your new added code.

Use Default jQuery: Using the jQuery javascript provided by Jtouch template or not. Only select “No” if you have your own jQuery inserted to the site. Make sure that the version of jQuery is 1.7.1 or higher. JQM CSS: Select which type of css you would like to use for your mobile website: full version (FULL) or just structure (STRUCTURE ONLY).

Important! Only use structure CSS when you have a fully customized theme, from swatch A to E. Please read the section “Customize Theme” for more info.

14

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.

15

Script Type: Select your preferred type of Google AdSense script: using PHP code or Native (javascript) code. These both have the same function of displaying Google AdSense on all of your mobile pages. Some users report that the PHP option works well on their sites, while others say that they prefer NATIVE. [Tab Other Extensions]

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.

16

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.

5.2 Uninstall 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

17

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

18

Here are the eight positions graphically: (View larger size by opens the file jtouch25.template.positions.jpg) Top:

Bottom:

Main:

Some suggestions:

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:

19

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:

20

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.

21

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

22

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:

Notes:

23

-‐ 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.

24

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.8 Advanced -‐ Content Overflow To set a horizontal scroll, if the page is a little larger than the viewing area, you can use a little piece of javascript:

<div style="width:100%; overflow:scroll;"> <div style="width:800px;">Put your js code here</div> </div>

Replace 800 by the size you need. (But I'm not sure if all mobile devices support the overflow property.)

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:

25

<a href="index.php?jtpl=YOUR_DESKTOP_TPL_ID" data-icon="gear" data-role="button" target="_self" data-mini="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">

26

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.

27

Click the “Inspector” button to turn it on:

Now click the element and change its options to have a new layout:

28

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:

29

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:

30

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.

31

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:

32

Red color for <h3> tag, italic style -‐ Save it, go back to your site and see how it looks:

Before After

8 Know about limits

8.1 Mobile screen and compatible issues Jtouch25 requires jQuery/jQueryMobile library, which may not be compatible with one of your installed extensions. Jtouch25 uses the latest technology of WWW: HTML5 + CSS3 which works on most major + up-‐to-‐date browsers. It won’t work on old browsers like IE7, Firefox 3… or low CPU devices. Check and make sure that your browsers also support javascript. On mobile devices, if your installed extensions are not on the list of those supported in Jtouch25, you may not have a good layout. It’s because most of them are designed for desktop, not for mobile screens. Here is a list of extensions officially supported by Jtouch25:

1. com_content: section, front-‐page, category, and article layouts 2. com_contact: category & contact layouts 3. com_search: form and results layouts 4. com_user: all layouts 5. mod_login 6. mod_search: search form 7. mod_articles_news: add slide-‐show mode 8. com_virtuemart: VirtueMart 2 (Sorry, there is no support for VM 1) 9. com_kunena: Kunena 1.7 and 2.0, download its layout from a separate package.

You can find more info here: http://www.JtouchMobile.com/downloads/jtouch-‐ex/jtouch-‐ex-‐kunena-‐template

33

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 protected]. (Please do not send support question, you can post or search for answers from our forum).

JTouch 2.5 Mobile Joomla Template User Guide

Documents

Transcript of JTouch 2.5 Mobile Joomla Template User Guide