ChangwooWiki

사용자 도구

사이트 도구

추적:
wordpress:settings_api

차이

문서의 선택한 두 판 사이의 차이를 보여줍니다.

차이 보기로 링크

다음 판		이전 판
wordpress:settings_api [2016/01/28 14:49] – 만듦 changwoowordpress:settings_api [2016/04/30 18:50] (현재) – [예제 코드] 버그 수정 changwoo
줄 19: 줄 19:
 [[http://codex.wordpress.org/Function_Reference/register_setting|register_setting]] 함수는 세팅 항목을 시스템에 등록하는 일을 맡는다. [[http://codex.wordpress.org/Function_Reference/register_setting|register_setting]] 함수는 세팅 항목을 시스템에 등록하는 일을 맡는다.
  
-  ''register_setting( $option_group, $option_name, $sanitize_callback )''+  register_setting( $option_group, $option_name, $sanitize_callback )
  
   * option_group: 아이템들은 그룹화될 수 있다. 집합의 이름을 입력한다.   * option_group: 아이템들은 그룹화될 수 있다. 집합의 이름을 입력한다.
줄 25: 줄 25:
   * sanitize_callback: 값을 세정하기 위한 콜백 함수.   * sanitize_callback: 값을 세정하기 위한 콜백 함수.
  
-  ''unregister_setting( $option_group, $option_name, $sanitize_callback )''+  unregister_setting( $option_group, $option_name, $sanitize_callback )
      
 MVC 패턴 관점에서 설명하자면 세팅의 <모델>을 정의하는 작업이라고 보면 된다. MVC 패턴 관점에서 설명하자면 세팅의 <모델>을 정의하는 작업이라고 보면 된다.
줄 31: 줄 31:
 ===== 필드와 섹션 ===== ===== 필드와 섹션 =====
  
-  ''add_settings_field( $id, $title, $callback, $page, $section, $args )''+  add_settings_field( $id, $title, $callback, $page, $section, $args )
  
   * id: 이 필드의 태그가 가질 id. 이 id는 실제로 html 태그의 id 속성으로도 되어야 한다. 하지만 세팅값을 저장하고 불러오는 데 있어 id가 반드시 필요한 것은 아니다.   * id: 이 필드의 태그가 가질 id. 이 id는 실제로 html 태그의 id 속성으로도 되어야 한다. 하지만 세팅값을 저장하고 불러오는 데 있어 id가 반드시 필요한 것은 아니다.
줄 45: 줄 45:
  
  
-  ''add_settings_section( $id, $title, $callback, $page )''+  add_settings_section( $id, $title, $callback, $page )
  
   * id: 이 섹션의 태그가 가질 id. add_settings_field() 함수의 id 인자와 같은 역할을 한다.   * id: 이 섹션의 태그가 가질 id. add_settings_field() 함수의 id 인자와 같은 역할을 한다.
줄 67: 줄 67:
 </code> </code>
  
-  ''settings_fields( $option_group )''+  settings_fields( $option_group )
  
 이 함수는 <컨트롤>과 관련이 있다. form 내부의 부가적인 컨트롤, 즉 워드프레스가 부가적으로 사용할 html 태그를 삽입하는 함수이다. 그러므로 반드시 form 태그 안쪽에서 불려야 한다. 이 함수는 <컨트롤>과 관련이 있다. form 내부의 부가적인 컨트롤, 즉 워드프레스가 부가적으로 사용할 html 태그를 삽입하는 함수이다. 그러므로 반드시 form 태그 안쪽에서 불려야 한다.
   * option_group: register_setting() 함수의 인자인 option_group을 여기에도 입력해야 한다.   * option_group: register_setting() 함수의 인자인 option_group을 여기에도 입력해야 한다.
  
-  ''do_settings_sections( $page )'' +  do_settings_sections( $page ) 
-  ''do_settings_fields( $page, $section )''+  do_settings_fields( $page, $section )
      
 이 두 함수는 MVC 패턴에서 <뷰>를 담당한다. 직접적으로 컨트롤들을 화면에 그려 내는 역할을 맡는다. 이 두 함수는 MVC 패턴에서 <뷰>를 담당한다. 직접적으로 컨트롤들을 화면에 그려 내는 역할을 맡는다.
줄 80: 줄 80:
  
 ===== 에러 ===== ===== 에러 =====
-  ''add_settings_error( $setting, $code, $message, $type )'' +  add_settings_error( $setting, $code, $message, $type )   
-  ''get_settings_errors( $setting, $sanitize )'' +  get_settings_errors( $setting, $sanitize )   
-  ''settings_errors( $setting, $sanitize, $hide_on_update )''+  settings_errors( $setting, $sanitize, $hide_on_update )
      
 +===== 예제 코드 =====
 +다음은 아주 간단하게 세팅 API의 예제를 작성한 것이다. 위 장황한 설명보다 더욱 도움이 되리라 생각한다.
 +<code php hand-written-settings-sample.php>
 +<?php
 +/**
 +Plugin Name: My Settings
 +Version: 1.0
 +Author: changwoo
 +Author URI: mailto://ep6tri@hotmail.com
 +License: GPL2 or later
 +*/
 +
 +/**
 + * 메뉴 집어넣는 코드
 + */
 +add_action( 'admin_menu', 'my_settings_admin_menu' );
 +function my_settings_admin_menu() {
 +
 +    add_submenu_page(
 +        'options-general.php',
 +        'my settings', // html <title> ... </title> 에 표시될 텍스트
 +        'my settings', // admin menu 에 표시될 텍스트
 +        'manage_options', // 권한.
 +        //
 +        // page slug.
 +        // add_settings_section(), add_settings_fields(), do_settings_sections() 의 page 인자로 쓰임.
 +        'my_settings',
 +        'my_settings_output_settings'
 +    );
 +}
 +
 +/**
 + * 메뉴 집어넣는 코드 콜백
 + */
 +function my_settings_output_settings() { ?>
 +
 +    <form method="post" action="<?php echo admin_url( 'options.php' ); ?>" >
 +
 +        <?php
 +        // register_setting() 의 option_group 인자.
 +        // 이 함수는 몇몇 hidden field 를 생성하는데, 이 중 하나는 name=option_page, value={$option_group} 인 필드이다.
 +        // 그러므로 한 번에 submission 되는 form field 는 모두 같은 option group 이어야 제대로 처리된다는 뜻이다.
 +        settings_fields( 'my_settings_group' );
 +        ?>
 +
 +        <?php
 +        // do_settings_sections 로 sections, 복수가 쓰인 것에 유의.
 +        // 그러므로 인자는 섹션의 슬러그가 아닌, 페이지의 슬러그여야 한다.
 +        do_settings_sections( 'my_settings' );
 +        ?>
 +
 +        <?php
 +        // 이건 뭐 그냥 템플릿 펑션.
 +        submit_button();
 +        ?>
 +    </form>
 +
 +<?php }
 +
 +
 +/**
 + * 필드 정의 부분.
 + */
 +add_action( 'admin_init', 'my_settings_register_settings' );
 +
 +/**
 + * 필드 정의 부분 콜백
 + */
 +function my_settings_register_settings() {
 +
 +    // 옵션 그룹이란, 한 폼에 submission 되는 필드의 단위이다.
 +    // 워드프레스는 폼이 submission 될 때 POST 값에서 그룹이 미리 등록되었는지를 체크한다.
 +    // register_setting 에서 두번째 인자는 옵션 값이다.
 +    // 세 번째는 sanitization 콜백 함수. 문자열이라 오해하지 말 것.
 +    register_setting( 'my_settings_group', 'my_settings_a01', 'sanitize_text_field' );
 +    register_setting( 'my_settings_group', 'my_settings_a02', 'sanitize_text_field' );
 +    register_setting( 'my_settings_group', 'my_settings_a03', 'sanitize_text_field' );
 +    register_setting( 'my_settings_group', 'my_settings_a04', 'sanitize_text_field' );
 +
 +    register_setting( 'my_settings_group', 'my_settings_b01', 'sanitize_text_field' );
 +    register_setting( 'my_settings_group', 'my_settings_b02', 'sanitize_text_field' );
 +    register_setting( 'my_settings_group', 'my_settings_b03', 'sanitize_text_field' );
 +    register_setting( 'my_settings_group', 'my_settings_b04', 'my_settings_custom_sanitize' );
 +
 +    // 하나의 옵션에 여러 값을 집어 넣는 테크닉이다. PHP 의 serialization 을 이용한다.
 +    register_setting( 'my_settings_group', 'my_settings_c' );
 +}
 +
 +
 +// 섹션과 필드 설정
 +add_action( 'admin_init', 'my_settings_sections_fields' );
 +function my_settings_sections_fields() {
 +
 +    // 섹션 A
 +    add_settings_section( 'group_a', 'Group A', '', 'my_settings' );
 +
 +    add_settings_field(
 +        // id 파라미터이지만, 이것이 HTML 요소에서의 id 속성과 반드시 연관되어야만 하지는 않다.
 +        'a01',
 +        'A01',
 +        'my_settings_common',
 +        'my_settings',
 +        'group_a', array( 'id' => 'a01' )
 +    );
 +
 +    add_settings_field( 'a02', 'A02', 'my_settings_common', 'my_settings', 'group_a', array( 'id' => 'a02' ) );
 +    add_settings_field( 'a03', 'A03', 'my_settings_common', 'my_settings', 'group_a', array( 'id' => 'a03' ) );
 +    add_settings_field( 'a04', 'A04', 'my_settings_common', 'my_settings', 'group_a', array( 'id' => 'a04' ) );
 +
 +    // 섹션 B
 +    add_settings_section( 'group_b', 'Group B', '', 'my_settings' );
 +
 +    add_settings_field( 'b01', 'B01', 'my_settings_common', 'my_settings', 'group_b', array( 'id' => 'b01' ) );
 +    add_settings_field( 'b02', 'B02', 'my_settings_common', 'my_settings', 'group_b', array( 'id' => 'b02' ) );
 +    add_settings_field( 'b03', 'B03', 'my_settings_common', 'my_settings', 'group_b', array( 'id' => 'b03' ));
 +    add_settings_field( 'b04', 'B04', 'my_settings_common', 'my_settings', 'group_b', array( 'id' => 'b04' ));
 +
 +    // 섹션 C
 +    add_settings_section( 'group_c', 'Group C', '', 'my_settings' );
 +
 +    // 한 옵션 키에 여러 값을 저장하기
 +    add_settings_field( 'c01', 'C01', 'my_settings_serialized', 'my_settings', 'group_c', array( 'id' => 'c', 'key' => 'x' ) );
 +    add_settings_field( 'c02', 'C02', 'my_settings_serialized', 'my_settings', 'group_c', array( 'id' => 'c', 'key' => 'y' ) );
 +    add_settings_field( 'c03', 'C03', 'my_settings_serialized', 'my_settings', 'group_c', array( 'id' => 'c', 'key' => 'z' ));
 +    add_settings_field( 'c04', 'C04', 'my_settings_serialized', 'my_settings', 'group_c', array( 'id' => 'c', 'key' => 'w' ) );
 +}
 +
 +/** html 콜백 펑션 */
 +function my_settings_common( $args ) {
 +
 +    $id    = esc_attr( $args['id'] );
 +    $value = esc_attr( get_option( 'my_settings_' . $args['id'] ) );
 +
 +    printf( '<input type="text" id="my_settings_%1$s" name="my_settings_%1$s" value="%2$s" />', $id, $value );
 +}
 +
 +/** html 콜백 펑션 */
 +function my_settings_serialized( $args ) {
 +
 +    $id    = esc_attr( $args['id'] . "[{$args['key']}]" );
 +    $opt   = get_option( 'my_settings_' . $args['id'] );
 +    $value = isset( $opt[ $args['key'] ] ) ? esc_attr( $opt[ $args['key'] ] ) : '';
 +
 +    printf( '<input type="text" id="my_settings_%1$s" name="my_settings_%1$s" value="%2$s" />', $id, $value );
 +}
 +
 +// 옵션 값의 validation 처리
 +// 어이없게도 아직 settings API 에는 제대로 된 validation 이 없고 일단 sanitize 만 되면 옵션 값은 모두 DB 로 돌진한다.
 +// 그러므로 만약 옵션 값이 자연수 100 이하의 값만 요구한다 하더라도, 이를 잘 구별할 방법 자체가 존재하지 않는다.
 +// 그러므로 다음과 같은 우회 방법들을 적절히 찾는 것이 좋다.
 +//
 +// 1. 모든 옵션 값들은 디폴트 값을 갖게 하라.
 +// 2. sanitization 단계에서 validation 을 수행한다. validation 이 fail 하면 settings error 를 띄우고,
 +//    입력된 값을 세팅 디폴트로 수정한다.
 +// 3. 사실상 값이 무시된 것으로 간주할 수 있다.
 +
 +function my_settings_custom_sanitize( $value ) {
 +
 +    $default = '50';
 +
 +    $v = (int)$value;
 +    if( ctype_digit( strval( $value ) ) && 0 < $value && $value < 101 ) {
 +
 +        return $value;
 +    }
 +
 +    add_settings_error( 'my_settings_group', 'error', 'B04 세팅은 1에서 100까지 정수만 가능합니다.' );
 +
 +    return $default;
 +}
 +</code>
wordpress/settings_api.1453992572.txt.gz · 마지막으로 수정됨: 2016/01/28 14:49 저자 changwoo
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki