Block API

Pregled

Blokovi u Drupalu 8 zapravo se sastoje od dve odvojene API strukture da bi se napravio korisnički interfejs sličan onom koji je Drupal podržavao u prethodnim verzijama. Te dve API strukture su Block Plugin API, koji je samostalni API za višekratnu upotrebu, i Block Entity API, koji je specifičan za Drupal 8 i koristi se za pozicioniranje blokova i kontrolu vidljivosti.

Kreiranje blokova pomoću Block Plugin API

Kreiranje blokova definisanih u kodu vašeg modula zahteva učenje i razumevanje Plugin API-ja i posebno mehanizma pluginova zasnovanih na anotacijama, koji Drupal 8 koristi da pronađe kod koji definiše vaš blok.

Kreiranje prilagođenog bloka koji definiše vaš modul uključuje sledeće korake:

• Kreirajte block plugin koristeći anotacije
• Proširite klasu Drupal\Core\Block\BlockBase
• Implementirajte metode iz interfejsa Drupal\Core\Block\BlockPluginInterface koje su potrebne za vašu upotrebu

Učinite svoj blok vidljivim za Drupal i korisnike

Drupal koristi PSR-4 standard za otkrivanje. Pretpostavljajući da je ime modula fax, kod za vaše prilagođene blokove treba da bude smešten u direktorijum fax/src/Plugin/Block/. Svaki fajl u tom direktorijumu mora biti imenovan po klasi koju sadrži. Ako definišemo klasu FaxBlock, mora biti u fajlu fax/src/Plugin/Block/FaxBlock.php sa sadržajem sličnim sledećem primeru:

namespace Drupal\fax\Plugin\Block;

use Drupal\Core\Block\BlockBase;

/**
 * Provides a 'Fax' block.
 *
 * @Block(
 *   id = "fax_block",
 *   admin_label = @Translation("Fax block"),
 * )
 */
class FaxBlock extends BlockBase {
  // Override BlockPluginInterface methods here.
}

Osobina id u anotaciji definiše jedinstveni mašinski čitljivi identifikator vašeg bloka i ime koje će biti dostupno iz drugog koda. Anotacija admin_label definiše lako čitljivo ime bloka koje će biti prikazano u administratorskom interfejsu. Dostupna svojstva anotacije možete pronaći u \Drupal\Core\Block\Annotation\Block (javni atributi).

Dva najčešća metoda za redefinisanje su:

• BlockPluginInterface::build() — treba da vrati render niz koji definiše sadržaj koji želite da blok prikazuje.
• BlockBase::access() — kontroliše vidljivost bloka. Očekuje se da vrati AccessResult objekat.

Dodavanje prilagođenih konfiguracionih opcija u blok

Možete dodati prilagođene konfiguracione opcije u formu konfiguracije bloka tako što ćete redefinisati metode BlockPluginInterface::blockForm() i BlockPluginInterface::blockSubmit(), a zatim koristiti BlockBase::setConfigurationValue() i BlockBase::getConfiguration().

U sledećem primeru dodajemo novo tekstualno polje u metodu blockForm(), a zatim čuvamo korisnički unete podatke u metodi blockSubmit(). Kod pokazuje kako da vrednosti dobijete prilikom pravljenja forme, proverite ih i ažurirate pomoću odgovarajućih metoda.

use Drupal\Core\Block\BlockBase;
use Drupal\Core\Block\BlockPluginInterface;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Access\AccessResult;
use Drupal\Core\Cache\Cache;

/**
 * Provides a 'Fax' block.
 *
 * @Block(
 *   id = "fax_block",
 *   admin_label = @Translation("Fax block"),
 * )
 */
class FaxBlock extends BlockBase implements BlockPluginInterface {

  // Access method ovde...

  /**
   * {@inheritdoc}
   */
  public function build() {
    $config = $this->getConfiguration();
    $fax_number = isset($config['fax_number']) ? $config['fax_number'] : '';
    return [
      '#markup' => $this->t('The fax number is @number!', ['@number' => $fax_number]),
    ];  
  }

  /**
   * {@inheritdoc}
   */
  public function blockForm($form, FormStateInterface $form_state) {
    $form = parent::blockForm($form, $form_state);

    // Preuzmi postojeću konfiguraciju za ovaj blok.
    $config = $this->getConfiguration();

    // Dodaj polje u postojeću konfiguracionu formu bloka.
    $form['fax_number'] = [
      '#type' => 'textfield',
      '#title' => t('Fax number'),
      '#default_value' => isset($config['fax_number']) ? $config['fax_number'] : '',
    ];
    
    return $form;
  }

  /**
   * {@inheritdoc}
   */
  public function blockSubmit($form, FormStateInterface $form_state) {
    // Sačuvaj naše prilagođene postavke kad se forma pošalje.
    $this->setConfigurationValue('fax_number', $form_state->getValue('fax_number'));
  }

  /**
   * {@inheritdoc}
   */
  public function blockValidate($form, FormStateInterface $form_state) {
    $fax_number = $form_state->getValue('fax_number');

    if (!is_numeric($fax_number)) {
      $form_state->setErrorByName('fax_number', t('Needs to be an integer'));
    }
  }
}

Možete koristiti metodu BlockBase::getConfiguration() u metodi build() da dobijete konfiguracione podatke i prikažete ih korisnicima. Metoda access() može sadržati složeniju logiku da definiše da li blok treba da bude prikazan.

Primer metode za proveru pristupa:

/**
 * {@inheritdoc}
 */
public function access(AccountInterface $account, $return_as_object = FALSE) {
  return \Drupal\Core\Access\AccessResult::allowedIf($account->isAuthenticated());
}

Takođe možete definisati svoje sopstvene uslove keširanja.

Primer metode sa keš tagovima. Više o keš tagovima saznajte u dokumentaciji.

/**
 * {@inheritdoc}
 */
public function getCacheTags() {
   return \Drupal\Core\Cache\Cache::mergeTags(parent::getCacheTags(), ['node_list']);
}

Ako želite da promenite maksimalno vreme keširanja bloka na 0, pogledajte temu o maksimalnom vremenu keširanja.

public function getCacheMaxAge() {
  // Ako želite da onemogućite keširanje za ovaj blok.
  return 0;
}