위젯 사용법 - Rhymix Documentation

위젯 사용법¶

개요¶

라이믹스의 위젯 시스템을 활용하여 동적인 콘텐츠를 쉽게 추가하고 관리하는 방법을 학습합니다.

위젯이란?¶

위젯은 레이아웃이나 페이지에 삽입할 수 있는 재사용 가능한 콘텐츠 블록입니다.

위젯의 특징¶

재사용성: 한 번 만든 위젯을 여러 곳에서 사용
독립성: 각 위젯은 독립적으로 작동
설정 가능: 위젯별로 다양한 옵션 설정
캐싱 지원: 성능 최적화를 위한 캐싱 기능

위젯 사용하기¶

위젯 코드 생성¶

관리자 페이지 > 설정 > 위젯 코드 생성
원하는 위젯 선택
옵션 설정
코드 생성

레이아웃에 위젯 삽입¶

<!-- 위젯 코드 직접 삽입 -->
<img class="zbxe_widget_output" widget="content" 
     skin="default" 
     content_type="document" 
     module_srls="64" 
     list_type="normal" 
     tab_type="none" 
     markup_type="list" 
     list_count="5" 
     subject_cut_size="30" 
     thumbnail_type="crop" 
     thumbnail_width="100" 
     thumbnail_height="75" />

위젯 스타일 적용¶

<!-- 위젯을 특정 영역에 배치 -->
<div class="widget-container">
    <h3 class="widget-title">최신 글</h3>
    <img class="zbxe_widget_output" widget="content" ... />
</div>

<style>
.widget-container {
    background: #f8f9fa;
    padding: 20px;
    border-radius: 8px;
    margin-bottom: 30px;
}

.widget-title {
    font-size: 18px;
    margin-bottom: 15px;
    padding-bottom: 10px;
    border-bottom: 2px solid #007bff;
}
</style>

주요 위젯 종류¶

1. 콘텐츠 위젯¶

최신 글, 인기 글 등을 표시하는 가장 많이 사용되는 위젯입니다.

주요 옵션¶

content_type: document(문서), comment(댓글), image(이미지)
module_srls: 대상 모듈 번호 (쉼표로 구분)
list_type: normal(일반), popular(인기), random(랜덤)
list_count: 표시할 항목 수
subject_cut_size: 제목 글자 수 제한
thumbnail_type: crop(자르기), ratio(비율유지), none(없음)

예제: 갤러리형 최신 이미지¶

<img class="zbxe_widget_output" 
     widget="content" 
     skin="gallery" 
     content_type="image" 
     module_srls="64,65,66" 
     list_type="normal" 
     list_count="12" 
     thumbnail_type="crop" 
     thumbnail_width="200" 
     thumbnail_height="200" 
     cols_list_count="4" />

2. 로그인 위젯¶

사용자 로그인 폼을 표시합니다.

<img class="zbxe_widget_output" 
     widget="login_info" 
     skin="default" />

3. 언어 선택 위젯¶

다국어 사이트에서 언어를 선택할 수 있습니다.

<img class="zbxe_widget_output" 
     widget="language_select" 
     skin="default" />

4. 카운터 위젯¶

방문자 통계를 표시합니다.

<img class="zbxe_widget_output" 
     widget="counter_status" 
     skin="default" />

위젯 스킨 커스터마이징¶

스킨 디렉토리 구조¶

widgets/content/skins/custom/
├── content.html
├── content.css
├── content.js
└── info.xml

기본 스킨 복사 및 수정¶

# 기존 스킨 복사
cp -r widgets/content/skins/default widgets/content/skins/mycustom

# 스킨 파일 수정
vi widgets/content/skins/mycustom/content.html

스킨 HTML 수정 예제¶

<!-- content.html -->
<div class="custom-widget-content">
    <ul class="content-list">
        <!--@foreach($widget_info->content_items as $key => $item)-->
        <li class="content-item">
            <!--@if($item->getThumbnail())-->
            <div class="thumbnail">
                <img src="{$item->getThumbnail()}" alt="{$item->getTitle()}" />
            </div>
            <!--@end-->

            <div class="content-info">
                <h4 class="title">
                    <a href="{$item->getLink()}">{$item->getTitle()}</a>
                </h4>
                <p class="summary">{$item->getSummary(100)}</p>
                <div class="meta">
                    <span class="author">{$item->getNickName()}</span>
                    <span class="date">{$item->getRegdate('Y.m.d')}</span>
                </div>
            </div>
        </li>
        <!--@end-->
    </ul>
</div>

위젯 캐시 설정¶

개별 위젯 캐시¶

<!-- 5분(300초) 캐시 -->
<img class="zbxe_widget_output" 
     widget="content" 
     cache="300" 
     ... />

전역 캐시 설정¶

// config/config.user.inc.php
$config->widget = new stdClass();
$config->widget->cache = true;
$config->widget->cache_time = 300; // 기본 5분

반응형 위젯 디자인¶

CSS 미디어 쿼리 활용¶

/* 기본 스타일 */
.widget-content {
    display: grid;
    grid-template-columns: repeat(4, 1fr);
    gap: 20px;
}

/* 태블릿 */
@media (max-width: 768px) {
    .widget-content {
        grid-template-columns: repeat(2, 1fr);
    }
}

/* 모바일 */
@media (max-width: 480px) {
    .widget-content {
        grid-template-columns: 1fr;
    }
}

위젯 성능 최적화¶

1. 적절한 캐시 시간 설정¶

<!-- 자주 변경되지 않는 콘텐츠: 1시간 -->
<img class="zbxe_widget_output" cache="3600" ... />

<!-- 실시간성이 중요한 콘텐츠: 1분 -->
<img class="zbxe_widget_output" cache="60" ... />

2. 필요한 필드만 가져오기¶

<!-- 제목과 날짜만 필요한 경우 -->
<img class="zbxe_widget_output" 
     widget="content" 
     show_browser_title="N" 
     show_category="N" 
     show_comment_count="N" 
     show_trackback_count="N" 
     show_icon="N" 
     ... />

3. 적절한 목록 수 설정¶

<!-- 너무 많은 항목은 성능 저하 -->
<img class="zbxe_widget_output" 
     list_count="10" 
     ... />

위젯 문제 해결¶

위젯이 표시되지 않을 때¶

캐시 삭제
bash rm -rf files/cache/widget/*
권한 확인
- 대상 모듈의 권한 설정 확인
- 비공개 게시판의 경우 권한 문제일 수 있음
모듈 번호 확인
- module_srls 값이 정확한지 확인
- 관리자 페이지에서 모듈 번호 확인

위젯 스타일이 깨질 때¶

CSS 충돌 확인
css /* 위젯 전용 네임스페이스 사용 */ .my-widget-wrapper .content-list { ... }
스킨 파일 확인
- 스킨 디렉토리에 필요한 파일이 모두 있는지 확인
- info.xml 파일 문법 오류 확인

고급 활용¶

동적 위젯 로딩¶

// AJAX로 위젯 동적 로딩
function loadWidget(targetId, widgetCode) {
    $.ajax({
        url: request_uri,
        type: 'POST',
        data: {
            module: 'widget',
            act: 'procWidgetGenerateCode',
            widget_code: widgetCode
        },
        success: function(response) {
            $('#' + targetId).html(response.widget_content);
        }
    });
}

커스텀 위젯 개발¶

// widgets/mywidget/mywidget.class.php
class mywidget extends WidgetHandler
{
    function proc($args)
    {
        // 위젯 로직 구현
        $output = $this->getLatestData($args);

        // 템플릿 변수 설정
        Context::set('widget_info', $output);

        // 템플릿 컴파일
        $tpl_path = sprintf('%sskins/%s', $this->widget_path, $args->skin);
        $tpl_file = 'content.html';

        return $this->compile($tpl_path, $tpl_file);
    }
}

모범 사례¶

적절한 캐싱: 콘텐츠 특성에 맞는 캐시 시간 설정
반응형 디자인: 모든 기기에서 잘 보이도록 설계
성능 고려: 필요한 데이터만 가져오기
접근성: 스크린 리더 등을 고려한 마크업
재사용성: 범용적으로 사용할 수 있는 스킨 개발

다음 단계¶

위젯 사용법을 익혔다면, 더 고급 기능을 학습해보세요:
- 커스텀 위젯 개발
- 위젯 스킨 제작
- 위젯 캐싱 최적화