BeSite Framework voor WordPress documentatie


BeSite maakt gebruik van een "framework" thema om op deze manier een aantal (frontend) oplossingen te standaardiseren.
Dit thema heet "bs-framework".


Wat doet het?

Het BeSite framework biedt frontend oplossingen voor:


Wat doet het (nog) niet?

Er moet nog een oplossing worden gemaakt voor:


Goed om te weten:

BeSite-eigen functies zijn ge-prefixed met "bs_", classes met "Bs" en bestandsnamen met "bs-".

Installatie


Gebruik maken van het BeSite framework gaat als volgt in zijn werk:

  1. Installeer een standaard setup van WP in de map "htdocs" (in de root).
  2. Kopieer de mappen "jquery" en "scss" naar de root.
  3. Kopieer de themas "bs-framework" en "theme" naar "htdocs/wp-content/themes".
  4. Hernoem indien gewenst de mappen "theme" (in "htdocs/wp-content/themes" en "scss") naar het project.

De mappenstructuur ziet er nu als volgt uit:

root
    htdocs
        ...
        wp-content
            ...
            themes
                bs-framework
                theme
            ...
        ...
    jquery
        ...
    scss
        bs-framework
        lib
        theme
            _variables.scss
            style.scss

  1. Open "scss/theme/style.scss" en pas de gegevens van het thema in het commentaar aan.
    Hierdoor kan WP het thema en het BeSite framework herkennen. Pas NIET de tekst achter "Template" aan!

Het commentaar ziet er nu als volgt uit:

/*
  Theme Name:   Theme
  Theme URI:    http://www.besite.nl
  Description:  Theme
  Author:       BeSite
  Author URI:   http://besite.nl
  Template:     bs-framework
  Version:      1.0.0
  Tags:         mijn, thema
  Text Domain:  theme
*/

  1. Open "htdocs/wp-config.php" en zet daar ergens (bijv. bovenin) de volgende regel:
define('WP_AUTO_UPDATE_CORE', false );

  1. Zet SASS aan:
cd /home/www/mijn-project
sass-wp

  1. Ga naar het CMS (/wp-admin), log in en kies het thema "mijn-thema".
    Kies het thema "bs-framework" om deze documentatie in plaats van de website te bekijken.

Nu kan gebruik worden gemaakt van SASS en het BeSite framework.

Gebruiken


Een kleine demonstratie van hoe het BeSite framework gebruikt kan worden, voor meer informatie, zie de hoofdstukken hieronder.

In "header.php", vóórdat "wp_head()" aangeroepen wordt, of in een php-pagina, vóórdat "get_header()" aangeroepen wordt:

//	Ondersteuning voor responsive websites toevoegen
bs_config()->responsive = true;
	
//	Een .js bestand inladen voor mobiel gebruik
bs_js( "js/layout-mobiel.js", "mobile" );

Configuratie


Het BeSite framework biedt de mogelijkheid om een aantal instellingen op te slaan en door de hele site heen te gebruiken.
Haal het config-object op door de functie "bs_config()" aan te roepen, doe dit in "header.php", vóórdat "wp_head()" aangeroepen wordt, of in een php-pagina, vóórdat "get_header()" aangeroepen wordt:

$conf = bs_config();

De volgende instellingen zijn beschikbaar:

$debug
Boolean die aangeeft of de website in een ontwikkel- of live omgeving draait.
$supportIE8
Boolean die aangeeft of de website IE8 moet ondersteunen (voegt CSS zonder media queries toe in "conditional comments").
$inc_root
Include pad naar de root van het project (één map verder terug dan de site root).
$responsive
Boolean die aangeeft of ondersteuning voor een responsive moet worden toegevoegd.
Als true, wordt de "jQuery.respontent" plugin ingeladen voor mobiel gebruik.
Standaard waarde: false.
$breakpoint
Nummer die het "breekpunt" tussen mobiel en desktop aangeeft.
Standaard waarde: 500.
$viewport
Het te gebruiken viewport.
Standaard waarde: "width=device-width initial-scale=1.0 maximum-scale=1.0 user-scalable=yes".

Voorbeeld

$conf = bs_config();
$conf->responsive = true;
$conf->breakpoint = 600;

if ( $conf->debug )
{
    require_once( $conf->inc_root . "/test.php" );
}

CSS


Het BeSite framework biedt een manier om vereenvoudigd en conditioneel .css bestanden in te laden en blokken CSS op de pagina te zetten.
Dit kan door de functie "bs_css()" aan te roepen, doe dit in "header.php", vóórdat "wp_head()" aangeroepen wordt, of in een php-pagina, vóórdat "get_header()" aangeroepen wordt:

bs_css( "css/layout.css" );

Deze functie kan 4 argumenten meekrijgen:

$iFile
String voor de bestandsnaam van het in te laden bestand of een blok CSS.
Wordt automatisch herkend door de samenstelling van de string.
$iMedia (optioneel)
String voor het te gebruiken media attribuut of één van de ondersteunde sleutelwoorden:
"mobile" voor mobiel gebruik of "desktop" voor desktop gebruik.
$iFirst (optioneel)
Boolean die aangeeft of het bestand/het blok CSS als eerste in de reeks van bestanden/blokken CSS moet worden geplaatst.
Standaard waarde: false.
$iBase (optioneel)
String voor het pad naar het bestand toe of de boolean true voor het pad naar het BeSite framework thema ("bs-framework") (inclusief slash aan het eind).
Standaard waarde: pad naar het thema (inclusief slash aan het eind).

Voorbeeld

//  Een bestand uit de map "css" van het thema inladen:
bs_css( "css/layout.css" );

//  ...voor mobiel gebruik:
bs_css( "css/layout-mobile.css", "mobile" );

//  ...voor desktop gebruik:
bs_css( "css/layout-desktop.css", "desktop" );


//  Een blok CSS op de pagina zetten:
bs_css( "body { background: #eee; }" );

//  ...voor mobiel gebruik:
bs_css( "body { background: #eee; }", "mobile" );

//  ...voor desktop gebruik:
bs_css( "body { background: #eee; }", "desktop" );


//  De argumenten $iFirst en $iBase zul je niet snel nodig hebben.

//  Een bestand als eerste in de reeks van in te laden bestanden plaatsen:
bs_css( "css/layout.css", null, true );

//  Een bestand uit de map "css" van het BeSite framework thema inladen:
bs_css( "css/layout.css", null, false, true );

//  Een bestand uit een andere map inladen:
bs_css( "layout.css", null, false, "/wp-content/" );

Standaard ingeladen

Door gebruik te maken van het standaard "style.scss" bestand (en bijbehorend het "_variables.scss" bestand), wordt standaard "normalize.css" (om alle browsers dezelfde standaarden te laten hanteren) ingeladen en een set (aan te passen) standaard waarden voor de meest voorkomende HTML elementen.

Ook zijn direct een reeks SASS mixins en functies beschikbaar die het schrijven van CSS vereenvoudigen. Zie SASS.

Javascript


Het BeSite framework biedt een manier om vereenvoudigd en conditioneel .js bestanden en veelgebruikte jQuery plugins in te laden, blokken javascript en blokken jQuery op de pagina te zetten.
Dit kan door de functie "bs_js()" aan te roepen, doe dit in "header.php", vóórdat "wp_head()" aangeroepen wordt, of in een php-pagina, vóórdat "get_header()" aangeroepen wordt:

bs_js( "js/layout.js" );

Deze functie kan 4 argumenten meekrijgen:

$iFile
String voor de bestandsnaam van het in te laden bestand, de in te laden jQuery plugin, een blok javascript of een blok jQuery.
Wordt automatisch herkend door de samenstelling van de string.
$iMedia (optioneel)
String voor één van de ondersteunde sleutelwoorden:
"mobile" voor mobiel gebruik, "desktop" voor desktop gebruik of één van de standaard sleutelwoorden van "INC" (is geen documentatie van, maar o.a. "touch", "IElt6", "IElt7", etc.).
$iFirst (optioneel)
Boolean die aangeeft of het bestand/het blok javascript als eerste in de reeks van bestanden/blokken javascript moet worden geplaatst.
Standaard waarde: false.
$iBase (optioneel)
String voor het pad naar het bestand toe of de boolean true voor het pad naar het BeSite framework thema ("bs-framework") (inclusief slash aan het eind).
Standaard waarde: pad naar het thema (inclusief slash aan het eind).

Voorbeeld

//  Een bestand uit de map "js" van het thema inladen:
bs_js( "js/layout.js" );

//  ...voor mobiel gebruik:
bs_js( "js/layout-mobile.js", "mobile" );

//  ...voor desktop gebruik:
bs_js( "js/layout-desktop.js", "desktop" );

//  ...voor touchscreens:
bs_js( "js/layout-touch.js", "touch" );


//  Een jQuery plugin inladen:
bs_js( "tosrus" );

//  ...voor mobiel gebruik:
bs_js( "tosrus", "mobile" );

//  ...voor desktop gebruik:
bs_js( "tosrus", "desktop" );


//  Een blok javascript op de pagina zetten:
bs_js( "var test = true;" );

//  ...voor mobiel gebruik:
bs_js( "var mobile = true;", "mobile" );

//  ...voor desktop gebruik:
bs_js( "var desktop = true;", "desktop" );

//  ...voor touchscreens:
bs_js( "var touch = true;", "touch" );


//  Een blok jQuery op de pagina zetten:
bs_js( "$('#foo').hide();" );

//  ...voor mobiel gebruik:
bs_js( "$('.desktop').remove();", "mobile" );

//  ...voor desktop gebruik:
bs_js( "$('.mobile').remove();", "desktop" );


//  De argumenten $iFirst en $iBase zul je niet snel nodig hebben.

//  Een bestand als eerste in de reeks van in te laden bestanden plaatsen:
bs_js( "js/layout.js", null, true );

//  Een bestand uit het BeSite framework thema inladen:
bs_js( "js/layout.js", null, false, true );

//  Een bestand uit een andere map inladen:
bs_js( "js/layout.js", null, false, "/wp-content/" );

jQuery plugins

Bij ieder paginabezoek (in de ontwikkel omgeving, getest met "bs_config()->debug") worden de benodigde .js en .css bestanden van te laden jQuery plugins uit de map "jquery" (in de root) gekopieerd en samengevoegd in één .js en één .css bestand.
Het is dus erg belangrijk dat alle jQuery plugins die ingeladen moeten worden, ALTIJD ingeladen worden.

Dit is dus NIET de bedoeling:

bs_js( "tosrus" );
if ( een_test )
{
    bs_js( "mmenu" );
}

Stel dat "een_test" bij het laatste paginabezoek in de ontwikkel omgeving false is, dan wordt de "mmenu" jQuery plugin NIET bij in het gegenereerde .js en .css bijgevoegd en kan het in de live omgeving niet worden gebruikt.

SASS


Van de mogelijkheden die SASS biedt, gebruiken we wel "variables", "nesting" en "mixins", maar niet "selector inheritance" en "nested properties".


Beschikbare functies

Nadat "_bs-generic.scss" (in de map "scss/lib") is geïmporteerd, zijn de volgende functies beschikbaar:


_url( $img, $path, $version )
Maakt van een korte url een volledige url met versienummer (om caching tegen te gaan).

#foo
{
    background-image: _url( “header.jpg” ).
}

//  Wordt:
#foo
{
    background-image: url( “../img/header.jpg?v=100” );
}

Het pad wordt uit de variabel "$_IMG_DIR_" gehaald, het versienummer uit "$_APP_VERSION_".
Beide kunnen in "_variables.scss" overschreven worden.


Beschikbare mixins

Nadat "_bs-generic.scss" (in de map "scss/lib") is geïmporteerd, zijn twee soorten mixins beschikbaar: "functionele mixins" en "layout mixins".


Functionele mixins

Deze mixins geven een reeks eigenschappen aan een element met een functioneel doeleinde.


clearfix()
Voegt een :after toe waardoor floats worden gecleard.

#foo
{
    @include clearfix;
}

//  Wordt:
#foo:after
{
    content: "":
    display: block;
    float: none;
    clear: both;
}

ellipsis()
Maakt dat er een ellipsis (...) achter de tekst komt wanneer niet alle tekst op één regel past.

#foo
{
    @include ellipsis;
}

//  Wordt:
#foo
{
    text-overflow: ellipsis;
    white-space: nowrap;
    overflow: hidden;
}

transition( $properties, $duration, $easing, $delay )
Zet de transition eigenschap met alle vendor-prefixes.

#foo
{
    @include transition( ( left, right ) );
}

//  Wordt:
#foo
{
    -webkit-transition: none 0.5s ease 0s;
    -moz-transition: none 0.5s ease 0s;
    -ms-transition: none 0.5s ease 0s;
    -o-transition: none 0.5s ease 0s;
    transition: none 0.5s ease 0s;

    -webkit-transition-property: left, right;
    -moz-transition-property: left, right;
    -ms-transition-property: left, right;
    -o-transition-property: left, right;
    transition-property: left, right;
}

vendor-prefix( $property, $value )
Zet de meegegeven eigenschap met alle vendor-prefixes.

#foo
{
    @include vendor-prefix( box-sizing, border-box );
}

//  Wordt:
#foo
{
    -webkit-box-sizing: border-box;
    -moz-box-sizing: border-box;
    -ms-box-sizing: border-box;
    -o-box-sizing: border-box;
    box-sizing: border-box;
}

Layout mixins

Deze mixins geven een reeks eigenschappen aan een element (en sub-element) met een layout doeleinde.


grid_rows( $padding, $selector ) en grid_cols12/10/8( $affix )
Maken een grid met instelbare classnames en padding.

//  Altijd de rows met padding:
@include grid_rows( 20px );	

//  12 kolommen
@include grid_cols12();

//  12 kolommen met "-x" affix voor bredere schermen
@media (min-width: 1200px) {
    @include grid_cols12( “-x” );
}

//  10 kolommen
@include grid_cols10();

//  8 kolommen
@include grid_cols8();

hamburger( $color, $borderWidth, $padding, $spacing, $width )
Maken een menu/hamburger icon met instelbare kleur en afmetingen.

//  Maak een hamburger icon:
a[href="#menu"]
{
	@include hamburger( #333 );
}

//	Met aangepaste afmetingen
a[href="#menu"]
{
	@include hamburger( #333, 5px, 10px, 10px );
}

list( $key_selector, $value_selector, $border, $padding, $width, $key_width, $value_width )
Maakt een key/value lijst met instelbare selectors, border, padding en breedtes.

//  Maak een lijst van een DL, alle oneven childnodes (de DTs) zijn keys, alle even (de DDs) zijn values:
dl {
    @include list();
}

//  Hetzelfde voor tabellen:
table tr {
    @include list();
}

//  Ander gebruik:
div.list {
    @include list( “.key”, “.value”, 1px solid green, 20px, 600px, 200px, 400px );
}

menu( $height, $subheight, $lineheight, $padding )
Maakt een (nog verder te stijlen) horizontaal menu met :hover submenu's met instelbare hoogtes, lineheight en padding.

#menu > ul
{
    @include menu();
}