Amber

Alalike < Skins > Barthelme   (talk | users | test page | RWD? | set as default | unset | validate: HTML, CSS)

Summary: responsive mobile-friendly skin for all devices
Version: 2017-06-15
Prerequisites: PmWiki 2.2.56 or newer
Status: stable
Maintainer: HansB
Categories: Skins, RWD, Mobile, HTML5, PHP55, PHP72
Users: +6 (view / edit)
Discussion: Amber-Talk

Description

Responsive skin adapting to mobile, tablet, laptop and desktop screens, with side menu either right or left.

On a computer you may resize your browser window to see it adapt.
On a smart phone try out portrait as well as landscape orientation.

Special navigation on mobiles:

  • The menu, top action links and top search box are hidden and accessible via icons.
  • Swipe movements to left and right will show and hide the side menu.
  • The side menu is fixed in position and can be scrolled if it is long.
  • Tapping on the main page area will close any page elements previously opened.
  • Tapping on the right bottom arrow icon will scroll to the top.
  • Tapping on the site header will lead to the home page.

General design:

  • HTML5 doc type and some HTML5 element tags
  • CSS3 media queries and proportional dimensions (relative to the users font default size, and to the zoom factor of the device/browser) are used.
  • Modern fonts imported from Google's open font library.
  • Most HTML elements have dedicated class or id parameters for easier styling and scripting.
  • PmWiki's injected CSS rules are disabled, and made part of a css file.
  • Many page elements like header, titlebar, top searchbox, top and foot action links, footer, can be set on a special Site.PageElements page, or a group specific page.
  • SideBar side menu can be set to right (default) or left side.

Installation

  1. Unzip amber.zipΔ into your pmwiki/pub/skins/ directory.
  2. Add to config.php these lines:
    $Skin = 'amber';
    $HTMLTagAttr = 'lang="en"';
    

Replace "en" with the language code of your site's main language.
Right-to-left rtl direction for RTL languages are supported, see RTL Support

Configuration

The SideBar menu position is by default on the right side.
To show the menu on the left side, add to config.php:
$AmberConfig['menu'] = 'left';

Many customisations can be done via CSS rules, ideally put into pub/css/local.css, like the following examples. Create local.css, if you do not have it. All rules in local.css are applied after the skin's own css files are loaded, and will overrule any matching rules.

Setting a custom background image in the header:

myheaderimage.jpg in folder pub/img/. The path is relative to pub/css/local.css.

#header { 
   background-image: url(../img/myheaderimage.jpg);	
   background-size: cover;
   background-repeat: no-repeat;		
} 

Or setting the header background to a grey gradient, instead of the amber:

#header { 
  background: #dbdbdb;
  background-image: linear-gradient(to top right, #c0c0c0, #ffffff);
} 

Custom mobile sidemenu, top actions and top search form

Here are two examples for a different colour scheme for the side menu, top action menu and top search form. Note the @media screen condition, as we do not want this to affect desktop (wider) screens, just the mobile and tablet screens, which have a slide-out menu and pop-up search form.

A grey background scheme:

@media screen and (max-width:54.9em) {
  #rightmenu, #leftmenu, #topsearch, #topactions {
      background-color: #777; color: #fff; }
  #rightmenu a, #leftmenu a, #topactions a { color: #fff; }
  #topsearch .inputbutton { background: #ccc; color: #333; }
}

An amber/yellow background scheme:

@media screen and (max-width:54.9em) {
  #rightmenu, #leftmenu, #topsearch, #topactions {
      background-color: #ffe31b; color: #333;}
  #rightmenu a, #leftmenu a, #topactions a { color: #333; }
  #topsearch .inputbutton {background: #ffe31b; color: #666; }
}

Adapting header text styling:

The header text is set in Site.PageElements. The example sets the text in the header to white (for a darker background image), and applies a custom shadow.

.site-title, .site-subtitle, #topactions a { 
   color: #fff;
   text-shadow: 2px 8px 6px rgba(0,0,0,0.7),
      0px -5px 35px rgba(255,255,255,0.8);		
} 

Custom setting of search, menu and tool icons in mobile header:

Again for a darker background image one can choose a white set of icons, which are already in the pub/skins/amber/img/ folder.

#menu-toggle-label { background-image: url(../skins/amber/img/menu-white.svg); }
#actions-toggle-label { background-image: url(../skins/amber/img/wrench-white.svg); }
#search-toggle-label { background-image: url(../skins/amber/img/search-white.svg); } 

Setting a maximum page width and body background:

The page appears in front of the body background and is centred.
The second media rule is to counteract automatic font increase for wide windows (same as next tip).

@media screen and (min-width:55em) {
  body { background: url(../img/mybackground.jpg) repeat; }
  #page { max-width: 70em; }
}
@media screen and (min-width: 75em) {body {font-size:1em;}} 

If you want a different page maximum width, say 1000px, set in the above:

 #page { max-width: 1000px; }

and add to config.php this line:

 $HTMLFooterFmt[] = '<script>var pageMaxWidth = 1000;</script>';

note the plain number, no px in the above. This is for the skin javascript function, which handles the width on window resizes.

Preventing font-increase for very wide or full screen windows:

(setting it to same values as for standard desktop window widths). @media screen and (min-width: 75em) {body {font-size:1em;}}

Custom fonts for header, headings and text

Google Fonts offer a vast selection of stylish fonts to use in web pages, so an admin person may want to choose some font families which suit best for a particular site. I've choosen the serif font family Lora as general text font for good readability, and Hind for headings. The site header is using PT Sans. All are imported via a css rule at the top of skin.css. Remove or replace this rule at your liking: @import url(https://fonts.googleapis.com/css?family=Lora:400,400italic|PT+Sans:700|Hind:500);

Page Elements and Side Menu

The skin uses Site.SideBar (or a Group SideBar page) for a main right-hand side menu, as is traditional with PmWiki. Creating a page Site.PageElements allows customisation by the admin for all important page elements. Look at the installed Site.PageElements as an example for some customised page elements.
The Page Elements sections:

  • #banner : for optional banner text /image above header, or, with absolute positioning, anywhere else.
  • #topactions : for action links at the top right.
  • #topsearch : for a search form in the right header area.
  • #header : for header text (site-title and site-subtitle).
  • #titlebar : for breadcrumb navigation links above the page title.
  • #footactions : for action links at the page foot, above the footer.
  • #footer : for footer text and links.

One can also create sections in group-specific PageElements pages, like GroupName.PageElements, which will be used instead of the section with same name in Site.PageElements.
If it is not desirable to allow this, please add to config.php:

  $SkinElementsPages = array('Site.PageElements');

which will exclude any use of <GroupName>.PageElements.

Images

Images are by default displayed with a slight box shadow. For individual images style %noshadow% will suppress the box shadow, or apply class noshadow to a div. To configure the whole site for showing images without box shadow add to pub/css/local.css:

#content img,  #content span > img, #content a > img {
  -webkit-box-shadow: none;
  -moz-box-shadow: none;
  box-shadow: none;
}

Then individual images can be shown with box shadow by using the style %shadow%, or setting class shadow to a div which contains images.

Fixed Header

I do not recommend it , but if you wish to fix the header, so it does not scroll up, add this to pub/css/local.css:

#headerwrap  { position:fixed; width:100%; z-index:10;}
#menu-toggle-label { position:fixed; z-index:11;}
#content, #sidebar { position: relative; top: 4em; }
#menu-close-label { position: absolute; top: 4em; }

@media screen and (min-width:55em) {
	#content, #sidebar { top: 6em; }
}

You may need to adjust the top spacings, depending on the size of your header.

RTL Support

Amber supports right-to-left RTL languages. You can configure switching the skin for RTL in a number of ways:

Set $HTMLTagAttr
setting $HTMLTagAttr = "lang='ar'"; or 'fa', 'he', 'ur' will switch Amber to RTL mode, with SideBar menu at left. Variable $RTLLanguages holds a list of language codes for the four main RTL languages (Arabic, Farsi (Persian), Hebrew, Urdu). Other language codes could be added.
$EnableRTL = 1;
skin will switch to RTL.
$HTMLStylesFmt['rtl']
if a css injection via $HTMLStylesFmt['rtl'] = "..."; is present in config the skin will switch to RTL. Note this method is not encouraged, as Amber will load all necessary css rules for RTL from a short style sheet (skin-rtl.css).
Multi Language Views
if this recipe is used, $HTMLTagAttr will be set according to the user language choosen, and if it is one of the RTL languages, and the page contains text in it, then the skin will switch to RTL.
classes 'rtl' and 'ltr'
these classes are provided by inclusion of scripts/xlpage-utf-8.php, which will be needed in any case for support of RTL languages (see UTF-8). 'rtl'and 'ltr' classes can be used to specify direction of text independently of the general text direction within a page, for example:
>>rtl<<
يتدفق هذا النص من اليمين إلى اليسار
>>ltr<<
This text flows left to right.
>><<

يتدفق هذا النص من اليمين إلى اليسار

This text flows left to right.

Translation of words and phrases
see Internationalizations for adding special translation pages. You can add your own phrases to such pages. You can also change text of Amber's Site.PageElements, write the site header in your rtl language etc.
$WikiTitle
this variable is usually set in config.php and will appear as part of a page's title tag, which is seen in the browser's tab. $WikiTitle can be set to a rtl word or phrase, but only if care is taken to save the config.php page encoded in UTF-8 (NO BOM). Your text editor needs to support this.

Usage

Amber skin uses four different view modes, via @media screen CSS rules, depending on the browser width and a user's default font size setting.

  • mobile (portrait): page content and images are viewed in one column, side menu is hidden out of the way.
  • mobile (landscape) and tablet: page content and images can be placed in several columns, side menu is hidden out of the way.
  • laptop and desktop: content can be in several columns, SideBar menu appears as a right-side (or left-side) column.
  • wide and full-screen desktop: same as before, but the font size is increased to 150% for easier reading/working at a distance.

View mode classes

You can use three classes, or a combination of them, for divs to display specific content for a specific view mode:

  • mobile : display for mobile portrait screens (narrow screen mode).
  • tablet: display for mobile landscape or tablet screens (medium wide screen mode).
  • desktop: display for desktop screens (wide screen mode).

Note that the skin has a number of layout classes, which result in the layout adapting to the screen width. See grid layouts below.

Tables

The use of tables can be tricky for a responsive design. It is best to avoid tables for the purpose of positioning page sections, and use some method of responsive grid as outlined below. Horizontally wide tables will receive a horizontal scroll bar, to avoid content not being accessible.

Tables and table cells can be styled using a number of class names:

(none)
default, show no borders.
class=lines
show a horizontal line under each row.
class=grid
show lines both horizontally and vertically around and within the table.
class=zebra
show every odd row with a light grey background.
class="zebra grid"
show every odd row with a light grey background, and show both horizontal and vertical lines.
border=1
show borders, borders are not collapsed (not thin).

Positioning divs into a responsive grid layout

These grid float classes are experimental, and I would love your feedback for improvement on this system! HansB

The skin offers a range of shorthand style classes for easy positioning and proportionally sizing divs into a grid system, all defined in the grid.css file. Content layouts with two, three and four columns or div boxes floating side by side can be created, as boxes with margins in between, or as tiles without in-between margins. On a mobile in portrait orientation these floats will be arranged in a single column. For instance

>>lf50<<
this will create a left-floating div with 50% width.
>>rf25<<
this will create a right-floating div with 25% width.
>>lf33 clear<<
this will create a left-float div with 33.33% width, and it will not float into space above (useful if it is the first floating div in a row).
>>lfx33<<
this will create a left-floating tile (no space between such tile divs) 33.33% wide.

All the grid float classes have padding, and classes like lf50, rf33 have a margin, so the boxes leave a little space in between. Classes like lfx50, rfx33 have no margin, so will look like tiles, touching each other. To easily remember: lf stands for left float, rf for right float, the attached number for the nominal percentage width, of which there are:

  • 25, 50, 75: for four columns
  • 33, 66: for three columns
  • 50: for two columns
Example:

>>lfx25<<
left-float 25% wide div, no margin, border or background.

>>lf50 h6 bd bgcolor=yellow<<
left-float 50% wide, 6 rows height, border, background color yellow

>>lf25 center frame<<
25% wide div
text is centred
frame: border light gray background

>>lfx33 h6 bgcolor=#ffeeee clear<<'
33% wide div tile
clear puts this on clear new row, otherwise it may float upwards, wrecking the grid layout.

>>lfx33 h6 bgcolor=#eeefff<< 33% wide div tile

Other classes defined in grid.css:

margin-classes like rm2 (2% right margin) or lm3 (3% left margin), minimum-height-classes like h5 (ca. 5 text rows height), width-classes like w20 (20% width), image maximum-width-classes like iw20 (20% image maximum width) useful in style markup, padding-classes like p10 (10 pixel padding).

Boxes behaving as links (link boxes)

To create link box divs, which act as links when clicked or tapped, use style class link on a div, and put exactly one link into it, plus optional text and optional image. Put other styles to the div if needed.

An example for three link boxes floated side-by-side with lf33 float positioning classes from grid.css (33% wide left-float):

>>lf33 link<<
%lf%Attach:HaleyDog.jpg
!!![[PmWiki/Images]]
Clicking or tapping anywhwere on this link-box will take you to page ''Images''
>>lf33 link bgcolor=white<<
%lf%Attach:pmwiki-rollover.gif
!!!![[Main/Home Page| beyond home...]]
reaching far out with powerful flexible collaborative web design
>>link center bgcolor=yellow<<
[[Skins Gallery]]\\
simple text box
>><<

The rf and lf style class in front of an image inside a link class box adapts according to device width:

  • for mobile portrait mode the image will be a third wide of the full-width box.
  • for mobile landscape and other screens it will be half the width of the surrounding link box (which may well be less than full width, like half or third width of the content area)
  • if it is used for an image inside 20% (fifth width) boxes, the image will not have text float beside it (as there is little space), but have text below it instead, when viewed in anything but mobile portrait mode.

Notes

Change log / Release notes

  • 2017-06-15: removed all calls to Markup_e(), using Markup() instead. Added (:nofooter:) and (:nochrome:) markup definitions.
  • 2017-06-13: added full RTL (right-to-left) language support (added skin-rtl.css). Added $EnableRTL variable, added Multi Language Views support to set $HTMLTagAttr and switch to RTL if needed.
  • 2016-10-17: fixed bug preventing any GroupName.PageElements sections to be used if a Site.PagElements section was present. Fixed CSS to prevent long non-breaking words to spill over right sidebar.
  • 2016-09-30: fixed bug with (:noright:) (parts of javascript did not work); added (CSS) indicator for horizontal scroll bars for wide tables for mobile and tablet screen sizes. Added CSS for HTML blockquote and cite tags.
  • 2016-09-19: added javascript variable maxPageWidth to change maximum page width easier, if one wants a fixed page width. Some small style modifications on some elements.
  • 2016-09-15: fixed javascript bug introduced in v.2016-09-07, modified headings spacings and some other small style changes.
  • 2016-09-12: modified css for list bullets, modified css for pre and code text, long lines will now wrap, rather than a user cannot see the overflow.
  • 2016-09-10: modified css (font) for links.
  • 2016-09-09: fixed css bug for .site-title.
  • 2016-09-08a: modified table styles, added classes for various table styles.
  • 2016-09-08: modified closing of mobile screen sidemenu to allow it to stay open if elements on it are clicked/tapped.
  • 2016-09-07: added script to responsively add horizontal scrollbars to tables, if tables get too wide. Changed table css styling. Adjusted left padding for list items.
  • 2016-09-06: fixed bug in window resizing page-width calculation, fixed css for horizontal rule NOT to clear floats.
  • 2016-08-25: fixed bug preventing checkboxes from being seen.
  • 2016-08-20a: improved javascript width calculation for resizing.
  • 2016-08-20: fixed bug in left/right swipe action, fixed resizing window bug, fixed css for (:noleft:), (:noright:), (:noheader:) markup.
  • 2016-08-16: fixed opening/closing menu by swipe motion (bug crept into last version).
  • 2016-08-12: table style changes: removed 100% width, added padding and vertical-align: top to cells.
  • 2016-08-11: added skin variation with SideBar menu on left side, which can be set via a variable in config.php.
  • 2016-08-08: fixed bug to hide actions toggle if no action links.
  • 2016-08-07: imgonly and imgcaption classes added for vertical-align images. Changes to grid.css: changed names for border classes, display:block for margin classes, added aside class, for floated aside sections in mobile mode.
  • 2016-08-05: grid.css styles reworked. Mobile sidemenu widened. Small style changes.
  • 2016-08-03: fixed some styles, changed font for links, added positioning css classes via new grid.css file, added clickable 'link' box styles and javascript.
  • 2016.08.01: initial release.

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

See also

Responsive skins:

Cookbook /
GridWorks  GridWorks - general utility css grid markup for wiki pages (Active/Stable)
ResponsiveGrid  A collection of CSS classes to help fast grid layouts (new)
Skins /
2016  Responsive skin very close to the default skin (alpha)
Adapt  A mobile-friendly skin that adapts to suit the display size. (Beta)
Mobile  Plain vanilla PmWiki responsive template that is compatible with mobile devices. (Active)
Vanilla5  Vanilla5 is a simple HTML5 compliant skin for PmWiki v2+

Contributors

Comments

See discussion at Amber-Talk

User notes +6: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Skins listings and will help newcomers browsing through the wiki.