Skip to main content

Drupal 建立模組的設定頁面 create setting page for custom module

Submitted by admin on Thu, 02/13/2020 - 09:06

在許多模組中都會有一個自己的模組設定頁面。舉個例子,像是Switch page theme 模組,我們可以在Configuration > System > Switch Page Theme進入管理頁面,裡面提供一些這個模組可以根據使用者需求而改變設定的選項。

這篇我們會來聊聊如何為自己的自製模組做一個這樣的設定頁面。

因為新增的設定頁面毫無疑問是個表單,我們在這邊先假設我們已經看過並了解了簡單的自製表單這篇文章的內容。

老樣子,我們也假設這次的模組名稱叫做SimpleSetting。

 

0. 建立info以及routing檔案內容

兩個檔案都是每次都有介紹到的老東西。info內容這次就不貼了,參照以前的隨便敲就好。這次的SimpleSetting.routing.yml內容如下,提供了一個表單的路徑以及class定義,並且限制只有網站管理權限的使用者才能存取。

SimpleSetting.setting:
  path: '/admin/config/simple_setting'
  defaults:
    _form: 'Drupal\SimpleSetting\Form\SimpleSettingForm'
    _title: 'provides a dummy setting form'
  requirements:
    _permission: 'administer site configuration'

 

1. 建立SimpleSetting.links.menu.yml檔案

這份檔案位在[ModuleRoot]/SimpleSetting.links.menu.yml,跟上面兩個檔案在同一個資料夾階層,內容如下。

SimpleSetting.form:
  title: 'SimpleSettings settings'
  description: 'A dummy configure setting page.'
  route_name: SimpleSetting.setting
  parent: 'system.admin_config_development'

這份檔案關聯了route_name以及parent兩個項目,功能是讓我們由routing檔案所定義的SimpleSetting模組頁面可以出現在管理員選單中Configuration > development頁面底下。

 

2. 建立SimpleSetting.settings.yml檔案

這份檔案位在[ModuleRoot]/config/install/SimpleSetting.settings.yml。

SimpleSetting:
  my_selection: '0'

這個檔案提供了模組在一開始被Enable時所使用的設定初始值,請注意未來使用者更改的設定值並不會反應在這個檔案中。

 

3. 建立表單

位置在[ModuleRoot]/src/Form/SimpleSettingForm.php,有看過過往表單範例的話應該會很熟悉大部分的內容。

<?php

namespace Drupal\SimpleSetting\Form;

use Drupal\Core\Form\ConfigFormBase;
use Drupal\Core\Form\FormStateInterface;

class SimpleSettingForm extends ConfigFormBase {

  /**
   * {@inheritdoc}
   */
  public function getFormId() {
    return 'simple_setting_form';
  }
  
  /**
   * {@inheritdoc}
   */
  public function buildForm(array $form, FormStateInterface $form_state) {
      // Form constructor.
      $form = parent::buildForm($form, $form_state);
      // Default settings.
      $config = $this->config('SimpleSetting.settings');
      // select list
      $opt = array(
          '0' =>   'this is a default value',
          '1' => 'this is a other selection value',
      );
      // Page title field.
      $form['my_selection_in_form'] = array(
          '#type' => 'select',
          '#title' => $this->t('example select!'),
          '#default_value' => $config->get('SimpleSetting.my_selection'),
          '#description' => $this->t('choose one and click save :)'),
          '#options' => $opt,
      );
      
      return $form;
  }
  
  /**
   * {@inheritdoc}
   */
  public function submitForm(array &$form, FormStateInterface $form_state) {
      $config = $this->config('SimpleSetting.settings');
      $config->set('SimpleSetting.my_selection', $form_state->getValue('my_selection_in_form'));
      $config->save();
      return parent::submitForm($form, $form_state);
  }
  
  /**
   * {@inheritdoc}
   */
  protected function getEditableConfigNames() {
      return [
          'SimpleSetting.settings',
      ];
  }
  
}

這份表單提供一個下拉式選單,如下圖所示。

simple-setting-demo

 

4. 觀察結果

這次我們透過cron hook function來觀察設定表單的行為,這個函式應該寫在[ModuleRoot]/SimpleSetting.module檔案中,內容如下

<?php

function SimpleSetting_cron(){
	$config = \Drupal::config('SimpleSetting.settings');
	$my_selection = $config->get('SimpleSetting.my_selection');
	
	if($my_selection == '0'){
		\Drupal::logger('SimpleSetting')->info("default setting selected!");
	}
	else{
		\Drupal::logger('SimpleSetting')->info("new setting selected!");
	}
}

這段code在Drupal cron執行的時候會被觸發,我們可以在管理員選單Configuration > System > cron中點下Run cron按鈕來隨時手動觸發執行。

執行的結果會顯示在Reports > Recent Log messages裡面,根據SimpleSetting設定頁面的my_selection值不同而印出不同的訊息。

 

enjoy~