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:

  • het standaard inladen van generieke .js en .css bestanden;
  • het standaard weglaten van ongewenste (WP) HTML tags e.d.
  • het vereenvoudigd en conditioneel inladen van .js en .css bestanden;
  • het vereenvoudigd en conditioneel inladen van veelgebruikte jQuery plugins;
  • het vereenvoudigd plaatsen van HTML snippets;
  • het kunnen gebruiken van SASS met SASS mixins en functies.

Goed om te weten:

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

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 omgeving draait.
$test
Boolean die aangeeft of de website in een test 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 2 argumenten meekrijgen:

$iFile
String voor de bestandsnaam van het in te laden bestand of een blok CSS. Of een array met meerdere strings.
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.

Voorbeeld

bs_css( "css/layout.css" );
bs_css( "css/layout-mobile.css", "mobile" );
bs_css( "css/layout-desktop.css", "desktop" );
bs_css( "body { background: #eee; }" );

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 2 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. Of een array met meerdere strings.
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.).

Voorbeeld

bs_js( "js/layout.js" );
bs_js( "js/layout-mobile.js", "mobile" );
bs_js( "js/layout-desktop.js", "desktop" );

bs_js( array( "hammer", tosrus", "mmenu" ), "touch" );
bs_js( "var test = true;" );
bs_js( "$('#foo').hide();" );

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" );
}

Beschikbare jQuery plugins

Open het bestand "jquery/registry.php" om te zien welke jQuery plugins er beschikbaar zijn en met welk sleutelwoord het ingeladen kan worden.

Snippets

Het BeSite framework biedt een manier om vereenvoudigd HTML snippets te plaatsen.
Dit kan door de functie bs_snippets() aan te roepen.

Beschikbare snippets

De volgende snippets zijn beschikbaar:

besite_link( $options )
Maakt een link naar de BeSite website.

echo bs_snippets()->besite_link();

//	Argumenten met standaard waardes
echo bs_snippets()->besite_link(
	array(
		'text'		=> "Ontworpen en ontwikkeld door %s"	//	de tekst, bijv. "Website door: %s", "%s" wordt vervangen voor een link.
	)
);

breadcrumbs( $template, $options )
Maakt een broodkruimelpad.

echo bs_snippets()->breadcrumbs();

//	Argumenten met standaard waardes
echo bs_snippets()->breadcrumbs
	array(			//	array met template onderdelen
		'open'		=> '<ul class="breadcrumbs">',					//	html voor de opsomming van items
		'item'		=> '<li><a href="{url}" title="{name}">{name}</a></li>',	//	html van de items
		'last'		=> '<li><span>{name}</span></li>',				//	html van het laatste (huidige) item
		'close' 	=> '</ul>'							//	html na de opsomming van de items
	),
	array(			//	array met opties welke items te tonen
		'home'		=> true,	//	wel of niet de home pagina tonen
		'page'		=> true,	//	wel of niet tekst pagina's tonen
		'single'	=> true,	//	wel of niet (nieuws) detail-detail pagina's tonen
		'category'	=> false,	//	wel of niet (nieuws) categorie-pagina's tonen
		'last'		=> true		//	wel of niet het laatste (huidige) item tonen
	)
);

language_select( $template, $options )
Maakt een taalkeuze behorende bij de WPML plugin. Is een alternatief voor "icl_language_selector()".

echo bs_snippets()->language_select();

//	Argumenten met standaard waardes
echo bs_snippets()->language_select
	array(			//	array met template onderdelen
		'open'		=> '<ul class="language-select">',									//	html voor de opsomming van items
		'item'		=> '<li class="{active}"><a href="{url}" title="{name}" class="{code}"><span>{name}</span></a></li>',	//	html van de items
		'close' 	=> '</ul>'												//	html na de opsomming van items
	),
	array(			//	array met opties voor de "icl_get_languages" functie
				//	zie http://wpml.org/documentation/getting-started-guide/language-setup/custom-language-switcher/
		'skip_missing'	=> '1',
		'orderby'	=> 'custom',
		'order'		=> 'asc',
		'link_empty_to'	=> ''
	)
);

logo( $options )
Maakt een link naar de home pagina met daarin het logo.

echo bs_snippets()->logo();

//	Argumenten met standaard waardes
echo bs_snippets()->logo(
	array(
		'class'		=> "logo",			//	de classname van de link, bijv. "logo"
		'url'		=> esc_url( home_url( '/' ) ),					//	de url van de link, bijv. "/"
		'title'		=> esc_attr( get_bloginfo( 'name', 'display' ) ),		//	de titel van de link, bijv. "Home"
		'src'		=> get_stylesheet_directory_uri() . '/img/logo.png'		//	de src van de afbeelding, bijv. "/wp-content/themes/theme/img/logo.png"
	)
);

menu( $options )
Maakt een menu met de gewenste instellingen. Is een shortcut voor "wp_nav_menu()".

echo bs_snippets()->menu( "primary" );

//	Argumenten met standaard waardes
echo bs_snippets()->menu(
	array(				//	array met opties voor de "wp_nav_menu" functie of string voor de optie "theme_location"
					//	zie http://codex.wordpress.org/Function_Reference/wp_nav_menu
		'theme_location' 	=> 'primary',
		'items_wrap' 		=> '<ul>%3$s</ul>',
		'container' 		=> ""
	)
);

phonenumber( $options )
Maakt een link welke alleen op touch-devices naar een telefoonnummer linkt.

echo bs_snippets()->phonenumber( '0123 456 789' );

//	Argumenten met standaard waardes
echo bs_snippets()->phonenumber(
	array(			//	array met opties of string voor het telefoonnummer, tekst en titel
		'text'		=> null,	//	de weer te geven tekst
		'number'	=> null,	//	het telefoonnummer
		'title'		=> null		//	de titel van de link
	)
);

searchform( $options )
Maakt een zoekformulier.

echo bs_snippets()->searchform();

//	Argumenten met standaard waardes
echo bs_snippets()->searchform(
	array(			//	array met opties
		'method' 		=> 'get',			//	de te gebruiken method voor het FORM element, bijv. "GET" of "POST"
		'action' 		=> home_url(),			//	de te gebruiken action voor het FORM element, bijv. "/"
		'placeholder' 		=> __( 'Zoeken.', 'besite' ),	//	de placeholder tekst in het input veld, bijv. "Doorzoek de site"
		'submit'		=> __( 'Zoek', 'besite' )	//	de tekst op de submit knop, bijv. "Zoek nu"
	)
);

SASS

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

Beschikbare functies

De volgende functies zijn 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

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

alignleft() en alignright()
Laat een element links of rechts uitlijnen.

.alignleft
{
	@include alignleft( 20px );
}

//  Wordt:
.alignleft
{
	margin-right: 20px;
	float: left;
}

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

.clearfix
{
	@include clearfix;
}

//  Wordt:
.clearfix: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.

.ellipsis
{
	@include ellipsis;
}

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

strechitems()
Maakt dat alle childnodes even hoog worden, een soort "equalheights".

.strechitems
{
	@include strechitems;
}

//  Wordt:
.strechitems
{
	display: flexbox;
	display: flex;
	flex-flow: wrap;
	align-items: strech;
}

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, $rowSelector ) en grid_cols12/10/8( $affix )
Maken een grid met instelbare classnames en padding.

@include grid_rows();	
@include grid_cols12();

//	Argumenten met standaard waardes
@include grid_rows(
	false,		//	padding tussen kolommen, bijv. 10px of false
	".row"		//	selector voor rows, bijv. ".row-with-padding"
);	
@include grid_cols12(
	""		//	toevoeging achter ".col"
);

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

a[href="#menu"]
{
	@include hamburger();
}

//	Argumenten met standaard waardes
a[href="#menu"]
{
	@include hamburger( 
		#333, 	//	kleur van het icon, bijv. #000
		4px, 	//	dikte van de balkjes, bijv. 2px
		false, 	//	padding rondom het icon, bijv. 10px of false voor geen padding
		false, 	//	ruimte tussen de balkjes, bijv. 2px of false voor even dik als de balkjes
		false	//	breedte van het icon, bijv. 30px of false om de breedte automatisch te laten berekenen
	);
}

language_select( $direction, $flagWidth, $showName, $showCode, $padding )
Maakt een taalkeuze voor de bs_snippet "language_select" (behorende bij de WPML plugin).

.language-select
{
	@include language_select();
}

//	Argumenten met standaard waardes
.language-select
{
	@include language_select(
		"horizontal",	//	orientatie, "horizontal" of "vertical"
		25px,		//	breedte van de vlaggen, bijv. 30px of false voor geen vlaggen
		true,		//	naam v/h land tonen, true of false
		false,		//	landcode tonen, true of false
		10px 		//	padding tussen vlaggen, namen, landcodes, etc, bijv. 15px
	);
}

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();
}

//	Argumenten met standaard waardes
div.list {
	@include list(
		false,	//	selector voor de keys, bijv. ".key" of false voor alle oneven childnodes
		false,	//	selector voor de values, bijv. ".value" of false voor alle even childnodes
		false,	//	de border tussen regels, bijv. 1px solid #ccc of false voor geen padding
		false,	//	padding voor de keys en values, bijv. 10px, of false voor geen padding
		false,	//	breedte van de lijst, bijv. 400px, 80% of false voor 100%
		false,	//	breedte van de keys, bijv. 100px, 50% of false voor 40%
		false	//	breedte van de values, bijv. 100px, 50% of false voor 60%
	);
}

menu( $direction, $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();
}

//	Argumenten met standaard waardes
#menu > ul
{
	@include menu(
		"horizontal",	//	orientatie, "horizontal" of "vertical"
		40px,		//	hoogte van items in het menu, bijv. 50px
		40px,		//	hoogte van items in een submenu, bijv. 50px
		20px,		//	regelhoogte van items, bijv. 30px
		20px		//	padding links en rechts tussen items, bijv. 10px
	);
}

noscript( $color, $background )
Maakt een fixed (noscript) melding.

.noscript
{
	@include noscript();
}

//	Argumenten met standaard waardes
.noscript
{
	@include noscript(
		#f33,				//	kleur van de tekst, bijv. #333
		rgba( 255, 255, 255, 0.9 )	//	achtergrond(kleur), bijv. #fff
	);
}