라이믹스/매뉴얼/프론트엔드 라이브러리

상위 문서: 라이믹스/매뉴얼

1. 개요#

라이믹스 기본 페이지에서 사용하는 JavaScript 라이브러리와 Rhymix 오브젝트를 정리한다. 코어가 제공하는 리소스는 다른 버전을 중복 로딩하지 않도록 한다. 개별 API의 지원 버전은 사용 대상 사이트에서 확인한다.

2. 공용 라이브러리#

라이브러리	참조
jQuery	jQuery 또는 $. 관리자 설정에 따라 2.x·3.x 제공
js-cookie	Cookies 또는 Rhymix.cookie
URI.js	URI 또는 Rhymix.URI

3. Rhymix 오브젝트#

아래 메서드는 모두 Rhymix. 뒤에 붙여 호출한다. 표는 역할을 요약한 것으로, 선택 인자와 반환 타입 전체는 공식 명세를 함께 확인한다.

메서드	역할
isMobile()	현재 접속 환경이 모바일인지 반환
getColorScheme() / setColorScheme(value) / detectColorScheme()	light·dark 조회, 설정, 자동 감지
getLangType() / setLangType(value)	언어 조회와 변경. 화면 반영에는 새로고침이 필요할 수 있음
getCSRFToken() / setCSRFToken(token)	현재 세션의 CSRF 토큰 조회·설정
getRewriteLevel()	짧은주소 수준: 0 사용 안 함, 1 XE 호환, 2 전체
getBaseUrl()	origin을 제외한 설치 URL 경로
getDefaultUrl()	사이트 전체 주소
getCurrentUrl()	짧은주소를 풀어 쓴 현재 페이지 전체 URL
getCurrentUrlPrefix()	현재 mid, 빈 값일 수 있음
isCurrentUrl(url)	상대경로와 해시 등을 고려하여 현재 URL과 비교
isSameOrigin(url1, url2)	두 URL의 origin 비교
isSameHost(url)	도메인 중심의 느슨한 비교. 신규 사용은 권장하지 않음
redirectToUrl(url, delay)	페이지 이동. 현재 페이지면 새로고침, 지연값은 2.1.25부터
cancelPendingRedirect()	예약 이동 취소, 2.1.25부터
openWindow(url, target, features) / openPopup(url, target)	새 창·규격 팝업
modal.open(id) / modal.openIframe(url, target) / modal.close(id)	히스토리와 연동하는 모달 열기·닫기
ajax(action, params, success, error)	모듈 액션에 AJAX POST 요청
ajaxForm(form, success, error)	HTML 폼을 AJAX로 제출
filesizeFormat(size)	파일 크기를 읽기 쉬운 문자열로 변환
lang(key, val)	프론트엔드 다국어 코드 조회·저장
checkboxToggleAll(name) / displayPopupMenu(...)	문서 선택·팝업 메뉴 등의 내부 사용 API. 외부 코드의 직접 사용은 권장하지 않음

4. AJAX 요청#

Rhymix.ajax()는 라이믹스 2.1.24부터 제공한다. 첫 인자는 모듈명.액션명, 두 번째는 전송할 데이터이다. 일반 객체는 JSON으로 전송하며 JSON 응답을 처리한다. 다음 예제의 액션명은 실제 모듈의 액션으로 바꾼다.

Rhymix.ajax('example.procExampleSave', { title: '제목' }, function(data) {
    console.log(data.message);
}, function(error) {
    alert(error.message);
});

파일 등이 포함된 FormData를 넘길 때는 첫 인자를 null로 하고 FormData에 module과 act를 포함한다. 폼은 Rhymix.ajaxForm(form)을 쓰거나 <form>에 rx_ajax 클래스를 지정하여 제출을 연동할 수 있다.

4.1. Promise#

라이믹스 2.1.25부터 Promise 방식으로 결과를 받을 수 있다.

async function saveExample() {
    try {
        const data = await Rhymix.ajax('example.procExampleSave', { title: '제목' });
        console.log(data.message);
    } catch (error) {
        alert(error.message);
    }
}

이 예제는 함수 정의이며 버튼 등 실제 동작에서 호출해야 한다. 콜백 방식과 Promise 방식을 한 요청에 섞는 것은 공식 매뉴얼이 권장하지 않는다.

4.2. 오류와 이동#

• 통신 오류와 모듈이 반환한 오류가 오류 처리 경로로 전달된다.
• 정상 JSON이면 HTTP 상태 코드뿐 아니라 응답의 error 값을 기준으로 판단한다. 0이 아닌 값은 오류이고, error가 없으면 오류가 아닌 것으로 처리한다.
• JSON이 아닌 응답은 오류로 처리한다. 백엔드의 PHP 경고가 섞여 응답이 깨졌는지 확인한다.
• 별도 오류 처리가 없으면 기본 알림과 콘솔 출력을 사용할 수 있다.
• Promise 방식에서 redirect_url이 반환되면 자동 이동이 예약될 수 있다. 이를 직접 처리하려면 Rhymix.cancelPendingRedirect()로 취소한다. 콜백을 전달한 경우의 이동 동작과 구분한다.

5. 모달#

Rhymix.modal.open(id)는 지정한 ID의 요소에 active 클래스를 적용하여 표시하는 구조를 전제로 한다. 테마가 해당 클래스의 표시 스타일을 구현해야 한다. 뒤로가기로 닫을 수 있고, 코드에서 닫을 때도 Rhymix.modal.close(id)를 사용하여 히스토리를 맞춘다.

openIframe()은 웹뷰 앱처럼 일반 팝업을 쓰기 어려운 환경에서 대안으로 사용할 수 있다. iframe 모달을 닫을 때는 ID를 생략할 수 있다.

6. 호환성#

대문자 XE 오브젝트는 2.1.24부터 Rhymix의 별칭이다. XML 필터 등에서 사용하는 소문자 xe와는 다르다. 백엔드의 모든 다국어 코드가 프론트엔드에 자동 제공되는 것도 아니므로 사용할 코드는 미리 전달해야 한다.

7. 하위 문서#

• 전역 함수
• 레거시 전역 함수
• String 확장

8. 출처#

이 문서는 라이믹스 공식 매뉴얼을 바탕으로 설명과 예제를 정리하였다. 공식 매뉴얼은 CC BY-SA 4.0으로 배포된다. 원문의 기여 이력은 rhymix-docs 저장소에서 확인할 수 있다.