Die Settings-API ist ein einfacher Weg die Optionen eines Plugins in die Standardoptionsseiten von WordPress zu integrieren. Für Plugins mit vielen Optionen eignet sich die API nicht, da dann die Seiten überladen wären, aber für kleine Plugins mit wenigen Optionen ist sie ideal. Der Codex erklärt die Settings-API schon ganz gut, aber ich hatte trotzdem ein paar Probleme und darum hier dieses Tutorial.

Alle Aufrufe der Settings-API sollten im Hook ‘admin_init’ gemacht werden. Die zwei wichtigsten Aufrufe der API sind die beiden Funktionen add_settings_field zum Anzeigen einer Option und register_setting zum Speichern. Hier zunächst ein Beispiel. Hier wird ein Textfeld auf der “Schreiben”-Optionsseite hinzugefügt:

add_action('admin_init', 'test_admin_init');
function test_admin_init() {
  add_settings_field(
    'test_option',
    '<label for="test_option">Test</label>',
    'test_option',
    'writing',
    'default',
    array()
  );
  register_setting('writing','test_option');
}

function test_option() {
  $value = get_option('test_option');
  echo '<input type="text" class="regular-text"
    id="test_option" name="test_option" value="'.$value.'" />';
}

Fangen wir mit der einfachen Funktion an: register_setting

register_setting sorgt dafür, dass eine Option gespeichert wird sobald auf der entsprechenden Seite der Speichern-Button gedrückt wurde. Sie hat zwei Parameter. Der erste Parameter gibt an auf welcher Seite die Option hinzugefügt wurde und beim Speichern mitgespeichert werden soll. Der zweite Parameter ist der Name der Option. Genau unter diesem Namen wird die Option auch in der Datenbank abgelegt. In dem Fall oben ist es die Option test_option auf der Seite writing. Optionen können auf allen acht Standardoptionsseiten von WordPress hinzugefügt werden:

• general
• writing
• reading
• discussion
• media
• privacy
• permalink
• misc

Die andere Funktion add_settings_field hat einige Parameter mehr.

add_settings_field(
  $option_name,
  '<label for="'.$option_name.'">'.
    $option_description.
  '</label>',
  $callback_function_name,
  $page,
  'default',
  array()
);

Ich denke die meisten Parameter sind so bereits klar. Hier einige Anmerkungen:
Der zweite Parameter gibt den Text vor dem Optionsfeld aus. Bei WordPress ist es üblich, dass dieser Text ein Label ist (also den Fokus an das Input-Element weitergibt). Das geschieht aber nicht automatisch und muss extra angegeben werden. Mit diesem Funktionsaufruf wird noch nicht das Eingabefeld angezeigt. Darum kümmert sich die Callback-Funktion. Hier das passende Beispiel:

function test_option() {
  $value = get_option('test_option');
  echo '<input type="text" class="regular-text"
    id="test_option" name="test_option" value="'.$value.'" />';
}

Die Funktion muss den aktuellen Wert selbst laden und anschließend das komplette Input-Element ausgeben. Der Name des Input-Elements muss der Name der Option sein (s. register_setting). Bitte nicht die ID vergessen, sonst funktioniert das label nicht.

Gruppieren

Wenn das Plugin mehr als eine Option hat, ist es sinnvoll die Optionen zu gruppieren. Dafür muss zuerst eine Gruppe anlegt werden und anschließend können die Optionen dieser Gruppe zuordnen werden. Gruppe anlegen:

add_action('admin_init', 'test_admin_init');
function test_admin_init() {
  add_settings_section(
    'test_section',
    'Test Titel',
    'test_section_description',
    'writing'
  );
  ...
}

function test_section_description() {
  echo '<p>info</p>';
}

Die Callback-Funktion gibt die Beschreibung zu der Gruppe aus und wird vor den Optionsfeldern angezeigt. Damit sie richtig formatiert wird, sollte in der Callback-Funktion auch ein Absatz ausgegeben werden. Um ein Optionsfeld dieser Gruppe zuzuordnen, muss nur der vorletzte Parameter in der add_settings_field von ‘default’ auf den Sectionname (im Beispiel ‘test_section’) geändert werden. Beispiel:

add_settings_field(
  'test_option',
  '<label for="test_option">Test</label>',
  'test_option',
  'writing',
  'test_section',
  array()
);

Best Practise

Ich habe jetzt schon einige male die Settings-API benutzt. Dabei wurde mir eins klar. Es ist wichtig die Bezeichner überall gleich zu wählen, sonst kommt man durcheinander. Was meine ich damit: Im Falle der test_option habe ich an allen Stelle test_option verwendet:

• Optionsname
• Name der Callback-Funktion (ggf. mit einheitlichem Prefix versehen)
• Name und ID des Input-Elements

Das Gleiche gilt natürlich auch für die Section und deren Callback-Funktion. Wenn möglich sollte auch eine Vereinheitlichung über Plugingrenzen angestrebt werden.

Die Settings-API unterstützt auch die objekt-orientierte Programmierung. Alle Callback-Funktionen können auch als array mit Verweis auf &$this angegeben werden.