Knowledge Base / Category / JM Theme plugin

JM Theme plugin

This plugin is used for all our premium themes. And probably for all our free future themes too.

Introduction to JM Theme plugin

Some basic information about JM Theme plugin

Premium plugin to help you work with theme layouts.
This plugin was first time introduced with Gaia theme.  It solved some missing functionality in the Theme manager.  During the time some of its functionality was moved to core and some of it was improved.

Important.   Old Gaia and OM themes use version 2.0.  If you want to use with theme new version 2.1, don't forget about the update process

Author note.  This plugin is paid. Sorry, too much time without any feedback was spent on it to give it for free. All my ideas related to this plugin were shared with core developers, some of them are now part of the core, some were declined. Moving to core complicated my own development and I needed to rewrite everything from the beginning.  And then to find a solution to have it worked with older themes.The donation for this plugin is more about supporting the next development, so here are rules
  • if you donated it, you can use it with any themes and how times you want.
  • if you donated it with any our premium theme, you will not pay it again with the next theme. You will get a coupon or better price to save your money. To say that you have this plugin is not enough to get better price, it was never free. I am not stupid. If I don't track you as a donator, I want some confirmation about your donation. 
  • this applies for AppStrap theme too, although old version uses other plugin. But it helped me to get this idea.

Jimako

What was removed in version 2.1:

- navigation builder. It's not needed anymore. With HTML files is easy to test the new version.  

- custom fields not related to layout (use JM Elements for this)

Actual plugin structure looks this way:

Jmtheme Folderstructure

DOWNLOAD

Installation

 After download, you need to upload this plugin via FTP. 

Then you can install it manually via Menu Manager or via the shortcut in the Theme manager. 

You should install this plugin before theme installation (because the theme is packed with default data for this plugin),  but it's not problem anymore. With our themes there is an option to import demo content after installation directly in Theme manager or you can import just data for this plugin via Database/Tools.  In this case, look for XML file inside install folder like install_layouts.xml or demo_layouts.xml. 

How to use it

With our themes, everything is prepared, there is no need for any coding
 If you use this plugin with our theme, you should know:

- there is folder jmtheme inside your theme with option files (filename starts with word "option_")   Those files are already prepared for your theme. You should change them only if you want to extend your theme.

- there can be jmtheme template in templates folder if theme displays images (or other fields) different way. Any HTML output is done by templates or your inserted values, nothing is hardcoded.

If you use this plugin with your own theme, you should know:

- there is folder "default" inside plugin folder with default options. You should move it to your theme to folder jmtheme. Under theme you can modify it, create copy and have more option sets etc.

- jmtheme template uses 2 keys for images: cssinline and bgimage.  Maybe you need your own version for bgimage markup, so copy it standard way to your theme templates folder and customize to your needs.

Layout configuration

After installation (without import demo content) admin screen looks like this:

797a66d0e353

If you click on button Generate All Layouts, default data will be filled. But you can add layout manually, copy existiing... it's standard Admin UI solution. For generating is sitetheme_layouts preference used, not xml file, so anything is wrong, check the value of this preference.

Default values for option settings are:

- for themes with HTML layout: setting: default, header_default.html, footer_default.html

- for themes with PHP layout:  setting: default, header-default.php, footer-default .php(it is for back compatibility with our old themes)

73ea4ac1a34c

Fields:

Field name Description Note
Layout name name of your layout (theme.xml, then in pref) dropdown
Admin menu title Menu name for this layout on the left side, just text field, free change it
Theme name Actual theme name. Normally only layouts for actual frontend theme are displayed. When you switch between themes, you would need to set everything again. So it saves settings for more than one theme. In edit mode, you can edit this field. No dropdown, just text field. You should know what you are doing.
Custom header The selected custom header for this layout. Available headers are in folder headers in your theme.  see info about magic shortcode {---HEADER---} and shortcode {JM_CUSTOMHEADER}
Custom footer The selected custom footer for this layout. Available headers are in folder footers in your theme.  see info about magic shortcode {---FOOTER---} and shortcode {JM_CUSTOMFOOTER}
Setting Selected file with custom fields for this layout. 

Fields editable for each layout depends on your setting file.  For information about how to use those fields, see available shortcodes.

Cf32748caf66

C02eb087b24e

Available shortcodes

All shortcodes are global, so you can use them anywhere in your theme.

 Available shortcodes and how to use them

{DEFAULT_MENUAREA=100} version 1.0 up

it displays menus set for menuarea number 100 for default layout for any other layout. The same content like {MENUAREA=100} or {MENU=100} in default layout. It's very helpful if you have more footers with the same menus. More info.

{JM_CUSTOMHEADER}version 2.1 up it displays the content of header set for actual layout.  Now can be replaced with magic shortcode {---HEADER---}
{JM_CUSTOMHEADER: header=primary} it displays primary header (it is looking for html file in your theme/headers/header_* - in this case, header_primary.html).  This version is used mainly for custom pages (with correct template each custom page can have different header/layout)

{LAYOUT_BGIMAGE: template=bgimage} 

version 1.0 up

it displays background header image set for layout. It is special shortcodes for the header image, because, by default, you can set no image, external image (shortcodes work too) or image from media manager.  What is returned is set by template. Example:

$JMTHEME_TEMPLATE['bgimage'] = '<div class="image" style="background-image: url({BGIMAGE})"></div>';
$JMTHEME_TEMPLATE['cssimage'] = 'style="background-image: url({BGIMAGE})';

{LAYOUT_ELEMENT: element=title} 

version 1.0 up

It displays the value of the layout field for actual layout. It's good practice to write this shortcode to the description of your layout field. 

it replaces shortcodes. 

The output is not hardcoded. You can template it by using the template parameter. 

Parameter layout is ignored from version 2.1. It uses always actual layout.

{JM_CUSTOMFOOTER} version 2.1 up it displays the content of footer set for actual layout.  Now can be replaced with magic shortcode {---FOOTER---}
{JM_CUSTOMFOOTER: header=black} it displays black footer (it is looking for html file in your theme/footers/footer_* - in this case, footer_black.html).  This version is used mainly for custom pages (with correct template each custom page can have different footer/layout)

ShortCode Menu

The way how to use shortcodes with Menu Manager

This menu is replacement of former JM Shortcode plugin and it's available only with this plugin

DESCRIPTION

This menu adds possibility to use shortcodes directly in Menu manager.

No configuration is needed.

Reasons for this:

1. power of e107 menu manager  (visibility, configuration, templating).

2. you can use custom menus, but with Tinymce plugin there could be parse issues. With custom menu you create page too, so easier way is better.

3. you can use theme shortcodes, but you can't have them as menu 

4. there are menus with parameters, but they are missing configuration in Menu manager.

Shortly, this saves theme development time. 

Negative:

for now you need to click on configuration button to see menu parameters (I have feature request for this )

- you need to know how shortcodes look and how to set them.  For this I am creating list of available shortcodes on my site

Example:

Chapter menu (page/chapter_menu.php).  You can add it Menu manager (It's listed there). No parameters. 

You can insert it to theme.php this way:

{MENU: path=page/chapter_menu} to have the same result as in Menu manager.

You can use {MENU: path=page/chapter_menu&book=2} to display just chapters of book 2, but only hardcoded.

OR

you can add shortcode menu in Menu manager, click on configuration and insert shortcode there. This way each your menu can have a different caption (you can set there too) or can be without caption. 

Third parameter is 'id' for table_render() function.

Author note.  This menu was used mainly for elements shortcodes. The new version of JM Elements plugin has its own menu for any element, but you can still use it this way. 

D35ce09ac805

 

 

DEFAULT_MENUAREA shortcode

How this shortcode works

New global shortcode for easier managing menuareas if your theme has too much layouts
JMTheme plugin uses

{DEFAULT_MENUAREA=999}

shortcode. This shortcode displays all menus for default layout defined for defined area:

{MENU=999} or {MENUAREA=999}

 It is used mainly for the footer. So if you see something like this in your

$LAYOUT['_footer_']
{SETSTYLE=footer}
{MENU=43}
{DEFAULT_MENUAREA=43}

It means that :

  • you still can use special menu added via Menu Manager for your layout by using standard way
  • but you don't do anything if your menu area is the same as for default layout.

If you don't want this behaviour, just remove this shortcode from your footer layout. You can easily get it back by using the shortcode menu available with this plugin too.

How to upgrade to version 2.1.

How to update from 2.0 to 2.1 with theme packs with 2.0 version

How to update without breaking your existing site
Important.  You don't need to do this if your theme pack still works.  But our demos use this plugin version and if you are switching between more of our themes, you will need the same version of this plugin. 

IMPORTANT.  With the version 2.1.4 you don't need to move options to jmtheme folder and with themes without theme.html it looks in layouts folder. Documentation was updated.

There are 2 main changes in version 2.1:

-  database changes (removed not needed fields and moved important fields from options to separate fields)

-  the solution to work with both theme versions (HTML and PHP layouts).

Normally update would be managed by the plugin itself, but themes should be updated too then. It's not possible if you already customized them.  So now version 2.1 can manage old themes too.

Before update:

-  backup your layouts.  The best way is exporting them as XML file. You can do this 2 ways. In Database/Tools, Export data option and select table jmlayout.  Or directly in plugin by checking all layouts and use batch option Export records.

1d1dbfecfb93

 

Update files:

- upload the new version. It's recommended to delete folder content and upload the new one. 

Ac60e4eeb37a

Go to the admin area:

you should get a notice about the needed update.  It should be run twice times.  The first time database change is done, the second time values are moved. 

244e075277cd

Go to plugin admin area:

You should see the new fields there.

36af8993398d

Your site should work without any problems.

With old themes, you can change header and footer in 2 places. Changing in layout option is deprecated.

Possible issues:

1. neverending update  (it wasn't able to update tables)

Go to Database / Tools, option SQL Verification, check jmtheme plugin and run verify.

7bb3bcccf336

- check result and manually fix visible errors

844a5a42fcbe

- this should correct result:

Bf5247c4326b

2. if you don't see new field columns there

just click on Options and select them manually. Don't forget to press Save button. This happens if you already played with columns layout.

Dd8854add638

3. your header or footer is missing on Frontend. 

This shouldn't happen.  The only case could be if you used your own settings with the wrong file names. 

Just resave layout - edit, select header and footer and save.  

With old themes values from Layouts is used in theme layout, but there should the same value as in configuration.

If any other problem, contact us.

 

JM Theme Shortcodes

Update 15.05.2019

Global JM Theme shortcodes. Used mainly for layouts and plugin templates in theme itself
{DEFAULT_MENUAREA=999}
- displays menuarea 999  from default layout on all other layouts (not only default) where is this shortcode used
- example:
{DEFAULT_MENUAREA=100}
{MENUAREA=100}
displays menus from area 100 set in default layout + menus from area 100 set for this layout 

- it's helpfull if more layouts use the same footer with the same content.
{SITE_PRIVACY_LINK}
 example: 
  By signing up you agree to <a href="{SITE_TERMS_LINK}">  Terms of Service</a>

- returns e_PRIVACY_URL defined in theme.php
{SITE_TERMS_LINK}
 example: 
  By signing up you agree to <a href="{SITE_TERMS_LINK}">  Terms of Service</a>

- returns e_TERMS_URL defined in theme.php
{LAYOUT_BGIMAGE}
returns background image for layout
Example:
{LAYOUT_BGIMAGE: mode=full&template=bgimage}
returns: 
 <div class="image" style="background-image: url({BGIMAGE})"> </div> 

{LAYOUT_BGIMAGE: mode=full&template=login}
returns
style="background-image: url({BGIMAGE})'
this can be customized in theme template.
{LAYOUT_ELEMENT}
Any element defined for layout by theme.
Example:
{LAYOUT_ELEMENT: mode=full&element=title}
returns title element for full layout.