DXPR Builder 1.x 또는 2.x에서 마이그레이션.
DXPR Builder 3.x는 모든 1.x나 2.x 릴리스에서 제자리에서 업데이트됩니다. Composer가 코드를 교체하고 drush updatedb가 구성과 콘텐츠를 변환하는 dxpr_builder.install의 업데이트 후크를 실행합니다. 이 페이지에서는 해당 후크의 동작, 사용자 정의 코드의 변경 사항, 결과 확인 방법을 설명합니다. 릴리스 날짜는 git 태그 기준입니다. 이전 릴리스를 참조하세요.
버전 히스토리 요약
| 시리즈 | Drupal | 참고 |
|---|---|---|
| 7.x-1.x | Drupal 7 | Glazed Builder로 판매되었으며 나중에 이름이 변경됨 |
| 1.x (8.x-1.x) | Drupal 8, 9 | 2020년 5월 첫 1.x 릴리스부터 모듈 머신 이름 dxpr_builder. 마지막 릴리스 1.8.8 |
| 2.x | Drupal 9.3~11 | CKEditor 5, Key 모듈 지원, 첫 AI 기능. 마지막 릴리스 2.8.1 |
| 3.x | Drupal 10.2, 11 | Bootstrap 5 전용, Key 모듈 필수, 콘텐츠 마이그레이션, AI 페이지 및 이미지 생성 |
머신 이름은 1.x와 3.x 사이에서 바뀌지 않았습니다. Glazed 시절 마크업이 남아 있는 콘텐츠는 업그레이드 전에 1.x나 2.x에서 마이그레이션해야 합니다. 3.x는 더 이상 Glazed 이름을 재작성하지 않습니다(아래 참조).
시작 전 요구 사항
- Drupal 10.2 이상 또는 Drupal 11(
core_version_requirement는dxpr_builder.info.yml에 있음). - Key 모듈. 3.x의 하드 종속성이며,
drush updatedb실행 시 없으면dxpr_builder_update_9020()이 설치합니다. - DXPR Builder 2.0.0 이상용으로 발급된 제품 키.
dxpr_tier클레임이 없는 키는 설정 양식에서 거부됩니다. - Bootstrap 5를 제공하는 테마 또는 Bootstrap 5 사이드로드 옵션. Bootstrap 3, 4 사이드로드는 더 이상 없습니다.
마이그레이션 단계
-
데이터베이스와 파일을 백업합니다.
drush sql:dump --result-file=backup.sql -
Composer로 코드를 업데이트합니다. 3.x는 현재 사전 릴리스로 게시되므로 허용합니다.
composer require 'drupal/dxpr_builder:^3.0@beta' --with-all-dependencies -
업데이트 후크를 실행하고 캐시를 다시 빌드합니다.
drush updatedb drush cache:rebuild여러 3.x 후크가 모든 DXPR Builder 필드 값을 일괄 처리합니다(아래 참조). 대규모 사이트에서는 수초가 아니라 수분이 걸립니다.
-
페이지
/admin/dxpr_studio/dxpr_builder/settings를 열고 라이선스 섹션을 확인합니다. 업데이트 9020 이후 저장 방법은 Key 모듈이며 키는DXPR Builder JWT(dxpr_builder_jwt)입니다. -
같은 페이지에서 Bootstrap 파일 사이드로드를 확인합니다. Bootstrap 3이나 4가 선택되어 있던 사이트는 이제 Bootstrap 5로 설정됩니다.
-
페이지
/admin/dxpr_studio/dxpr_builder/ai_settings를 열고 기본적으로 켜져 있는 세 개의 AI 토글을 그대로 둘지 결정합니다. -
DXPR Builder를 사용하는 페이지를 방문하여 렌더링과 편집이 정상적인지 확인합니다.
업데이트 후크의 동작
후크 8005~8025는 1.x에 포함되었습니다. 1.x 사이트는 8026부터 전부 실행하며, 2.8.0이나 2.8.1 사이트는 8040과 9014부터 실행합니다. 함수 이름은 dxpr_builder_update_NNNN()입니다.
2.x에 추가됨(1.x에서 가져올 때 실행)
| 후크 | 동작 |
|---|---|
| 8026 | 중앙 DXPR Builder 사용자 저장소를 업데이트합니다. |
| 8027 | 라이선스 정보 블록과 사용자 보기에 “DXPR Builder User” 컬럼을 추가합니다. |
| 8028 | 콘텐츠 잠금용 dxpr_lock 테이블을 만듭니다. |
| 8029 | 사용자 라이선스 대시보드에 라이선스 블록을 추가합니다. |
| 8030 | “Bootstrap 3 Light” 옵션이 제거된 뒤 Bootstrap 설정을 전환합니다. |
| 8031 | 비활성화된 상태로 설치된 곳에 라이선스 정보 블록을 활성화합니다. |
| 8032 | 차단된 사용자를 라이선스 저장소에서 제거합니다. |
| 8033 | 항목 drm_last_contact를 초기화합니다. |
| 8034 | 항목 dxpr_user_is_disavowed 사용자 필드와 승인/비승인 사용자 작업을 설치합니다. |
| 8035 | 설정 hide_reminders를 초기화합니다. |
| 8036 | 프로필의 CKEditor 4 툴바 버튼 이름을 CKEditor 5로 마이그레이션합니다. |
| 8037 | 빠른 로딩 이미지용 기본 이미지 스타일을 추가합니다. |
| 8038 | Key 모듈 통합 서비스 등록을 위해 캐시를 지웁니다. |
| 8039 | 불완전한 image_scale_and_crop 설정의 이미지 스타일을 복구합니다. |
| 9007 | 기본 용어와 함께 ai_tone_of_voice와 ai_agent_commands 어휘를 만듭니다. |
| 9008 | 값 ai_enabled을 true로 설정하고 기존 ai_page_enabled 키를 제거합니다. |
| 9009 | 항목 drm_last_contact를 구성에서 상태로 옮깁니다. |
| 9010 | 캐시를 지웁니다. |
| 9011 | 모든 프로필에 AI 어시스턴트와 AI 말투 버튼을 활성화합니다. |
| 9012 | 값 ai_page_enabled을 기본값 true로 복원합니다. |
| 9013 | AI 출력 필터링 기본값(ai_output_allowed_domains)을 설정합니다. |
| 9015 | 값 ai_image_enabled를 기본값 true로 추가합니다. |
3.x에 추가됨(1.x 또는 2.x에서 가져올 때 실행)
| 후크 | 동작 |
|---|---|
| 8040 | 값 bootstrap을 bs5로 정규화합니다. 1(Bootstrap 3)과 bs4 값이 재작성됩니다. |
| 9014 | 일괄: Owl Carousel 마크업을 콘텐츠에서 Bootstrap 캐러셀로 변환합니다(src/Migration/OwlCarouselMigration.php). |
| 9016 | 값 ai_user_model_selection을 기본값 true로 추가합니다. |
| 9017 | 일괄: circliful 서클 카운터를 Bootstrap 진행 마크업으로 변환합니다(CircleCounterMigration.php). |
| 9018 | 일괄: 레거시 진행률 표시줄 마크업을 Bootstrap 진행 구조로 변환합니다(ProgressBarMigration.php). |
| 9020 | Key 모듈을 설치하고 json_web_token을 Key 엔티티 dxpr_builder_jwt로 옮기며, api_key_storage를 key로 설정하고 평문 값을 지웁니다. |
| 9021 | 사용자 템플릿의 type 속성을 마크업에서 백필합니다. |
| 9022 | 일괄: 내부 /node/N 링크에 data-entity-type과 data-entity-uuid를 추가합니다(EntityLinkMigration.php). |
| 9023 | 일괄: 업데이트 9022가 text_with_summary 필드에서 손실한 텍스트 형식, 요약, 삭제된 델타를 복구합니다. |
| 9024 | 일괄: 별칭 지정된 내부 링크를 9022와 같은 방식으로 보강합니다(AliasLinkMigration.php). |
| 9025 | 존재하지 않는 어휘를 가리키는 tone_of_voice_vocabulary를 지웁니다. |
| 9026 | 키가 Key 엔티티에 있는데 설정에 남아 있는 평문 json_web_token을 지웁니다. |
업데이트 9019는 없습니다.
콘텐츠 마이그레이션
3.x는 콘텐츠 마이그레이션을 일괄 방식으로만 실행합니다. 렌더링 시 변환은 더 이상 없습니다. 마이그레이션 상태 페이지(/admin/dxpr_studio/dxpr_builder/migration-status)와 상태 보고서에 대기 중인 콘텐츠가 나열됩니다. 위의 업데이트 후크가 마이그레이션하며, 해당 페이지의 지금 실행 및 모든 대기 마이그레이션 실행 작업도 마찬가지입니다. 마이그레이션은 dxpr_builder.content_migration 태그가 지정된 서비스입니다(dxpr_builder.services.yml). 실패를 기록한 일괄 작업은 완료로 표시되지 않으며, 실패한 항목은 로그에 기록되고 대기 상태로 남습니다.
항목 glazed_to_dxpr 문자열 재작성은 1.x와 2.x가 렌더링 시 적용하던 것으로, 제거되었습니다. Glazed 이름은 2020년 5월 1.0.0에서 삭제되었으며, 모든 Glazed 및 Carbide 시절 콘텐츠는 해당 릴리스에서 마이그레이션된 것으로 간주됩니다. 재작성은 단순 문자열 치환이었습니다. Glazed를 단순히 언급하는 콘텐츠(지원 문서, 문서 링크)가 있는 사이트에서는 마크업을 마이그레이션하는 대신 본문을 다시 쓰고 링크를 깨뜨렸을 것입니다. 저장된 콘텐츠에 Glazed 클래스 이름이 남아 있는 사이트는 먼저 2.x 릴리스를 실행해야 합니다.
사용자 정의 코드의 변경 사항
필드 포매터
필드 포매터 ID는 dxpr_builder_text(라벨 “DXPR Builder”, src/Plugin/Field/FieldFormatter/DxprBuilderFormatter.php)이며 1.x부터 바뀌지 않았습니다. 설정은 profile 하나뿐이며, 역할 기반 기본값은 비어 있고 프로필 ID를 사용합니다. 모든 빌더 필드의 뷰 디스플레이에 여전히 이 포매터가 사용되는지 확인합니다. 업데이트 9023의 복구는 해당 필드로 제한됩니다.
후크
dxpr_builder.api.php에 3.x 후크가 문서화되어 있습니다. Glazed Builder 후크는 다음과 같이 이름을 바꿉니다.
| Glazed Builder 후크 | DXPR Builder 3.x 후크 |
|---|---|
hook_glazed_builder_classes() |
hook_dxpr_builder_classes_alter(array &$dxpr_builder_classes) |
hook_glazed_builder_buttons_folders() |
hook_dxpr_builder_element_buttons_folders_alter(array &$dxpr_element_buttons_folders) |
hook_glazed_builder_elements_folders() |
제거됨. 대체 후크 없음. |
| none | hook_dxpr_builder_icon_sets_alter(array &$icon_sets), 신규. 아이콘 세트는 MODULE.dxpr_icon_sets.yml 파일에 선언됩니다. |
CSS 및 유틸리티 클래스
Glazed 클래스 이름을 대상으로 하는 사용자 정의 CSS는 dxpr-theme-util, panel-dxpr, dxpr-builder 같은 DXPR 이름을 사용해야 합니다. 에디터에 노출되는 유틸리티 클래스는 hook_dxpr_builder_classes_alter()를 통해 제공됩니다.
구성 및 배포
- 항목
json_web_token을 커밋된 구성에서 제거합니다. 업데이트 9020 이후 키는dxpr_builder_jwtKey 엔티티에 저장됩니다. 해당 Key는 구성 공급자를 사용하므로 키는 여전히key.key.dxpr_builder_jwt로 내보내집니다. 제외하려면 파일 또는 환경 공급자로/admin/config/system/keys에서 전환합니다. - 구성 내보내기에 두 개의 AI 어휘와 용어가 포함됩니다.
- 프로필은
inline_buttons와modal_buttons에 CKEditor 5 버튼 이름을 내보냅니다.
문제 해결
업데이트 후 콘텐츠가 올바르게 표시되지 않는 경우:
- 명령
drush cache:rebuild를 실행합니다. - 항목
/admin/reports/dblog에서dxpr_builder채널의 메시지를 확인합니다. 일괄 마이그레이션은 건너뛴 항목을 로그에 기록합니다. - 각 빌더 필드의 뷰 디스플레이에 여전히 DXPR Builder 포매터가 사용되는지 확인합니다.
- 테마가 Bootstrap 5를 로드하는지 확인하거나
/admin/dxpr_studio/dxpr_builder/settings에서 사이드로드를 활성화합니다.
