Icon

Benutzung der Klasse Icon

Auf dieser Seite... (ausblenden)

  1.   1.  Quick Start
  2.   2.  Icon-API im Detail
    1.   2.1  Factory-Methoden
    2.   2.2  Ausgabe-Methoden
    3.   2.3  Getter
    4.   2.4  "Setter"
  3.   3.  Was fehlt noch?

Stud.IP stellt eine reichhaltige Auswahl an Icons zur Verfügung. Ab Stud.IP v3.4 werden diese Icons mit einer PHP-API angesprochen. In den früheren Versionen musste man dazu eine Pfad im Dateisystem kennen. Jetzt reicht es, die Form des Icons zu kennen, um dieses einzubinden.

Zu diesem Zweck wurde die Klasse Icon geschaffen. Instanzen dieser Klasse haben 3 Eigenschaften:

  • die Form des Icons
  • die Rolle (und damit implizit die Farbe) des Icons
  • semantische Attribute wie title

1.  Quick Start

Wir wollen das "Startseite"-Icon (das man links oben auf jeder Stud.IP-Seite findet) einbinden. Dazu schreibt man einfach:

<?= Icon::create('home', 'navigation', ['title' => _("Zur Startseite")]) ?>

Und damit erhält man ein img-Element wie dieses:

Die Form des Icons ist "home". Die Rolle/Funktion des Icons ist "navigation". Das Icon soll ein semantisches Attribut, einen Titel, bekommen: _("Zur Startseite").

Die Signatur von Icon::create sieht daher so aus:

public static function create($shape, $role = Icon::DEFAULT_ROLE, $attributes = array())

Wenn man früher Icons verwenden wollte (Assets::img("icons/16/lightblue/home.png")), war dort die Farbe hartkodiert. Wollte man in seiner Installation ein Redesign vornehmen, ist das mehr als unschön. Aus diesem Grund wurden die Farben aus dem PHP-Code verbannt und auf Rollen umgestellt.

Derzeit befindet sich die Abbildung der Rollen auf Farben in der Variablen Icon::$roles_to_colors.

Will man eigene Icons verwenden, schreibt man einfach:

Icon::create($eigeneURL)

2.  Icon-API im Detail

Die Klasse Icon bietet nur wenige Methoden an.

2.1  Factory-Methoden

Icon::create($shape, $role = Icon::DEFAULT_ROLE, $attributes = [])

Das ist die Methode, um ein Icon zu instanziieren. Die $shape gibt die Form des Icons an, ohne weiter auf eine Färbung etc. einzugehen.

Die Rolle $role definiert den Kontext, in dem das Icon verwendet werden soll. Der Stud.IP-Style-Guide gibt zB vor, dass alle Icons in Links einheitlich gefärbt sein sollen (in der Regel blau). Die Rolle hilft dabei, Farbwerte nicht hart zu kodieren und trotzdem im ganzen System einheitlich zu differenzieren.

Die Eigenschaften $attributes enthalten nur semantische Attribute wie title. Nicht-semantische Werte wie CSS-Klassen, Größen, oder data-Attribute dürfen hier nicht eingetragen werden.

2.2  Ausgabe-Methoden

$icon->asImg($size = null, $view_attributes = [])

Diese Methode gibt das Icon als img-Element aus:

Icon::create('vote', 'clickable')->asImg(16)

erzeugt:

<img width="16" height="16" src="images/icons/blue/vote.svg" alt="vote" class="icon-role-clickable icon-shape-vote">

Der erste Parameter $size legt die width/height des img-Elements fest. Die $view_attributes können mit beliebigen Attributen wie class usw. befüllt werden.

$icon->asInput($size = null, $view_attributes = [])

Eine Variation von Icon::asImg, die das Icon als input-Element ausgibt:

Icon::create('upload', 'clickable')->asInput(20, ['class' => 'text-bottom'])

ergibt:

<input type="image" class="text-bottom icon-role-clickable icon-shape-upload" width="20" height="20" src="images/icons/blue/upload.svg" alt="upload">

Die Parameter funktionieren wie bei Icon::asImg.

$icon->asCSS($size = null)

Diese (selten verwendete) Methode gibt das Icon als CSS-Style-Angabe via @background-image@@ aus:

Icon::create('vote+add', 'clickable')->asCSS(17)

generiert:

background-image:url(images/icons/17/blue/add/vote.png);background-image:none,url(images/icons/blue/add/vote.svg);background-size:17px 17px;

Der Parameter $size legt die background-size fest.

$icon->asImagePath()

Mit dieser Methode erhält man einfach den Pfad zum SVG, dass für das gewünschte Icon steht:

Icon::create('vote+add', 'clickable')->asImagePath() === 'images/icons/blue/add/vote.svg'

$icon->__toString() aka echo $icon

Die magische __toString-Methode ist nur ein Alias mit Default-Werten für Icon::asImg, so dass folgendes:

echo Icon::create('vote+add', 'clickable')

einfach nur:

<img width="16" height="16" src="images/icons/blue/vote.svg" alt="vote" class="icon-role-clickable icon-shape-vote">

ausgibt.

2.3  Getter

  • $icon->getShape()
  • $icon->getRole()
  • $icon->getAttributes()

Diese Methoden geben einfach die entsprechenden Werte zurück.

2.4  "Setter"

  • $anotherIcon = $icon->copyWithShape($shape)
  • $anotherIcon = $icon->copyWithRole($role)
  • $anotherIcon = $icon->copyWithAttributes(array $attributes)

Diese Methoden ändern nicht das $icon, sondern geben ein neues Icon mit verändertem Shape/Role/Attributes zurück. Instanzen von Icon sind immutable, so dass unerwünschte Seiteneffekt nicht auftauchen können.

3.  Was fehlt noch?

  • $size === false
  • Additions
  • CSS-Mixins
  • Rollen-zu-Farben-Abbildung

Letzte Änderung am November 15, 2016, at 09:46 AM von mlunzena.