Shopify 테마 학습기 3

지난 글에서는 상품별 데이터를 화면에 연결하고, 옵션 변경과 장바구니 요청이 어디를 거쳐 실행되는지 따라갔다. 처음에는 테마를 열었을 때 무엇부터 봐야 할지 몰랐는데, 조금씩 코드를 고치면서 파일과 화면 사이의 연결이 보이기 시작했다. 이번에는 그 학습을 이어서 상품 카드와 번역을 다루고, 배운 내용을 조합하는 배송 안내 섹션을 만들었다.

공부한 내용을 팀에도 전달하고 싶었다. 내가 막혔던 부분을 남겨두면 다른 사람은 같은 자리에서 조금 덜 헤맬 수 있을 것 같았다. 그래서 README에 실습과 질문을 정리하기 시작했는데, 막상 다른 사람이 읽는다고 생각하니 작업 기록만으로는 부족한 부분이 많았다.

"내가 했던 일을 적어두면, 다른 사람도 그 순서대로 할 수 있을까?"

파일을 수정했다는 기록에는 어느 위치를 고쳐야 하는지, 무엇이 나오면 성공인지가 빠지기 쉬웠다. 질문에 답을 달아놓아도 어떤 문제에 대한 답인지 구분되지 않으면 앞뒤를 다시 읽어야 했다. 그래서 이번에는 공부한 내용을 남기는 것에서, 직접 따라 할 수 있는 가이드를 만드는 것까지 작업 범위를 넓혔다.

---

같은 코드를 어디까지 적용할 것인가

상품 상세 화면에서 사용하던 안내 문구를 상품 카드에도 출력해보았다. 상품에 저장한 메타필드 값을 읽어 표시하는 부분 자체는 익숙했다. 다만 카드 코드는 컬렉션 목록뿐 아니라 다른 화면에서도 사용하고 있어서, 한 파일을 수정한 영향이 예상보다 넓게 나타날 수 있었다.

처음에는 문구가 출력되는지만 확인했다. 그다음에는 컬렉션에서는 보여주되 검색 결과에서는 숨기려면 어떻게 해야 하는지 생각했다. 상품에 안내 문구가 있는지와, 지금 이 카드에서 그 문구를 보여줄지는 서로 다른 판단이었다.

그래서 상품 데이터에 표시 여부를 붙이는 대신, 카드를 호출하는 쪽에서 별도 매개변수를 전달하도록 했다. 스니펫 안에서는 메타필드 값과 매개변수를 함께 확인했다. 같은 상품이라도 호출 위치에 따라 표시 여부를 정할 수 있도록 범위를 나눈 것이다.

{% if card_product.metafields.custom.learning_notice.value != blank and show_learning_notice == true %}
  <p class="card-product__notice">
    {{ card_product.metafields.custom.learning_notice.value | escape }}
  </p>
{% endif %}

이 작업에서는 조건문을 쓸 수 있는지보다 표시를 결정하는 책임이 어디에 있는지가 더 중요했다. 상품별 문구는 상품의 메타필드가 가지고, 화면별 표시 여부는 스니펫을 호출하는 쪽이 정했다. 스니펫이 현재 검색 화면인지 직접 알아내도록 만들 필요가 없었다.

상품 정보에 붙였던 구매 가능 문구도 번역 키로 옮겼다. 한국어와 영어 문구를 각각 준비하고, Liquid에서 문자열 키에 t 필터를 적용했다. 화면의 언어가 바뀌었을 때 문구도 바뀌는 것을 확인하면서, HTML 요소의 ID와 번역 키가 서로 다른 역할이라는 점도 다시 정리했다.

옵션 변경 뒤 안내 영역을 갱신하는 JavaScript는 해당 ID의 요소를 찾아 내용을 교체했다. 번역은 그 ID를 읽어서 수행하는 일이 아니었다. 서버에서 Liquid가 렌더링될 때 번역된 문구가 만들어지고, JavaScript는 응답 HTML에서 그 결과를 가져왔다. 화면에 보이는 한 문장에도 데이터 선택, 번역, 화면 갱신이라는 여러 단계가 있었다.

이미지에는 아래로 스크롤해야 보이는 배너라는 조건을 확인한 뒤 지연 로딩 속성을 추가했다. 여기서도 속성이 붙었는지와 실제 로딩 속도가 개선됐는지는 구분했다. 정상적으로 표시되는 것은 확인했지만, 그것만으로 페이지 전체가 빨라졌다고 쓰지는 않기로 했다.

---

종합 과제에는 새로운 판단이 필요했다

학습 마지막에는 앞서 만든 것들을 다시 확인하는 과정이 있었다. 배너가 나오고, FAQ가 접히고, 상품별 문구가 바뀌는지 점검하는 일은 필요했다. 하지만 이미 만든 기능을 다시 실행하는 것만으로는 요구사항을 읽고 구현하는 종합 과제라고 보기 어려웠다.

내가 원했던 것은 먼저 요구사항이 주어지고, 어떤 설정과 데이터를 사용할지 스스로 나눠보는 연습이었다. 막혔을 때는 힌트를 열어보고, 구현한 뒤에는 정해진 기준으로 결과를 비교할 수 있어야 했다. 그래서 마지막 실습을 별도의 배송 안내 섹션을 만드는 과제로 바꿨다.

요구사항	구현에서 결정할 부분
상품마다 배송 안내가 다를 수 있다	상품 메타필드에서 문구를 읽는다
상품에 문구가 없으면 공통 안내를 쓴다	섹션 설정에 대체 문구를 둔다
표시 여부를 편집기에서 바꾼다	체크박스 설정으로 전체 출력을 제어한다
제목이 없어도 안내는 보여준다	제목과 본문의 출력 조건을 나눈다
최종 문구가 없으면 빈 영역도 숨긴다	대체 문구까지 결정한 뒤 전체 조건을 검사한다
같은 섹션을 여러 개 추가할 수 있다	배경색 스타일을 섹션 인스턴스별로 제한한다

요구사항을 적고 나니 무엇을 먼저 해야 하는지도 정리됐다. 상품의 문구를 읽고, 비어 있으면 기본 문구를 선택한 뒤, 표시 여부와 최종 문구를 확인하면 됐다. 처음부터 마크업 안에 조건을 계속 붙이기보다 출력에 사용할 값을 먼저 결정하는 편이 읽기 쉬웠다.

{% assign notice_message = product.metafields.custom.shipping_notice.value %}
{% if notice_message == blank %}
  {% assign notice_message = section.settings.fallback_message %}
{% endif %}

{% if section.settings.show_notice == true and notice_message != blank %}
  <section id="ShippingNotice-{{ section.id }}">
    {% if section.settings.heading != blank %}
      <h2>{{ section.settings.heading | escape }}</h2>
    {% endif %}
    <p>{{ notice_message | escape }}</p>
  </section>
{% endif %}

그 과정이 처음부터 매끄럽지는 않았다. assign 안에 다시 출력용 중괄호를 넣기도 했고, CSS 속성명에 하이픈 대신 밑줄을 쓰기도 했다. 설정의 ID와 CSS 속성이 비슷한 이름을 가질 수는 있어도, 같은 문법을 사용하는 것은 아니었다. 짧은 코드에서도 Liquid, JSON, CSS의 경계를 구분해야 했다.

배경색은 편집기에서 받은 값을 {% style %} 안에 출력했다. 선택자는 section.id를 포함한 ID로 제한해서, 두 배송 안내 섹션의 색이 서로 영향을 주지 않게 했다. 이전에 배운 설정과 CSS 연결을 새로운 요구사항에 다시 적용한 부분이었다.

완료 확인도 화면에 문구가 나온다는 한 가지 조건으로 끝내지 않았다. 상품 문구와 대체 문구를 각각 비워보고, 제목만 지워보고, 표시 여부를 껐다. 두 섹션에 다른 색을 적용하고 좁은 화면에서 긴 문구도 확인했다. 무엇을 만들었는지보다 어떤 경우까지 동작해야 하는지를 먼저 정하니, 확인할 내용이 구체적으로 나왔다.

---

내 기록에서 실습자의 문서로

가이드를 만들면서 가장 많이 고친 것은 설명의 관점이었다. 처음에는 내가 어디까지 진행했는지, 다음에 무엇을 할지, 작업을 어떻게 이어받을지가 문서에 섞여 있었다. 나에게는 유용한 내용이지만 처음 실습하는 사람에게는 필요하지 않았다. 팀원에게 전달할 자료라면 읽는 사람이 해야 할 행동이 중심이어야 했다.

그래서 개인 진도와 인계 내용을 빼고, 각 단계에 학습 이유와 목표를 넣었다. 수정할 파일과 위치를 먼저 적고, 이어서 문제와 완료 기준을 보도록 정리했다. 가이드가 주로 상품 상세 화면을 기준으로 진행된다는 점도 앞에서 명시했다. 장바구니나 컬렉션·검색 카드로 범위를 넓히는 단계는 그 흐름 안에서 설명하도록 했다.

실습 환경도 정확히 적어야 했다. 내가 사용한 테마의 메타데이터에는 Generated Data Theme라는 이름이 있었고, 개발 스토어의 생성된 테스트 데이터와 함께 제공되는 테마였다. 이것을 모든 스토어를 만들 때 기본으로 주어지는 테마라고 소개하면 시작부터 다른 화면을 볼 수 있었다. 별도의 테마 패키지를 배포하는 대신, 내가 사용한 환경을 안내하고 각자의 개발용 테마에서 작업하도록 정리했다.

"설명을 읽었는데도 어디를 고쳐야 할지 모르겠다면, 무엇이 빠진 걸까?"

내가 실습하면서 자주 했던 질문도 결국 그 부분이었다. 표현식을 작성하라는 말만 있으면 어느 파일에서 시작해야 할지 알기 어려웠다. 결과를 확인하라는 말에도 어떤 상품을 열고 무엇을 봐야 하는지가 필요했다. 문법 설명이 맞는 것과 실습 안내가 충분한 것은 별개의 문제였다.

힌트와 정답은 기본적으로 접어두고 필요할 때 열도록 했다. 처음부터 완성 코드를 보여주면 스스로 생각할 구간이 없어지고, 반대로 아무 안내도 없으면 막힌 위치를 찾기 어렵다. 따라서 힌트는 접근할 순서를 알려주고, 정답은 구현과 판단 이유를 확인하는 역할로 나눴다.

여기서 단순히 접기 기능만 넣는 것으로는 부족했다. 한 실습에 여러 문제가 있는데 힌트와 해설이 긴 문단으로 이어지면, 지금 읽는 설명이 몇 번 문제의 답인지 다시 찾아야 했다. 문제 번호에 맞춰 힌트를 구분하고, 정답에도 대응하는 번호를 붙였다. 하나의 구현을 여러 단계로 나누는 곳에서는 위치 확인, 조건 판단, 작성 시 주의점처럼 순서를 드러냈다.

마지막 배송 안내 과제에는 특히 내가 실제로 질문했던 지점을 반영했다. 메타필드와 기본 문구 중 무엇을 먼저 선택할지, 제목을 비웠을 때 전체를 숨겨도 되는지, 표시 여부 조건을 어디에 둘지를 단계로 나눴다. 정답을 바로 복사하지 않더라도 다음 한 단계를 시도할 수 있는 정도의 안내를 목표로 했다.

문서에 정답이 있다는 사실만으로 학습이 검증되는 것은 아니었다. 이해하지 못한 채 다음 단계로 넘어가지 않으려면 문제를 풀고 자신의 결과를 설명하는 과정이 필요했다. HTML 가이드에 자동 채점이나 진도 차단 기능을 넣은 것은 아니므로, 그 역할까지 문서가 수행한다고 소개하지는 않았다.

---

읽는 화면도 실습의 일부였다

README를 정리한 뒤에는 HTML 형태의 가이드도 만들었다. Markdown 파일은 보는 도구에 따라 원문이 보일 수 있고, 접기나 배치가 내가 의도한 모습과 다를 수 있었다. 파일을 전달받은 사람이 브라우저에서 바로 열어볼 수 있는 형태가 필요했다. README를 원본으로 삼아 HTML을 생성하도록 해서 내용을 두 군데에서 따로 고치지 않게 했다.

생성된 페이지에는 스타일과 필요한 스크립트를 넣고, 가이드에 쓰인 이미지도 포함했다. 문서 본문을 읽는 데 별도의 서버를 띄우지 않도록 한 것이다. 다만 외부 문서 링크를 방문하는 일까지 오프라인으로 가능해지는 것은 아니었다. 파일 하나로 읽을 수 있는 범위와 외부 자료가 필요한 범위는 구분했다.

실제 화면으로 보니 글을 쓸 때는 잘 보이지 않던 문제가 있었다. 위치와 목표가 한 줄에 이어져서 어디서 끊어 읽어야 하는지 분명하지 않았고, 정답 영역은 문장이 오른쪽 끝에 도달하기 전에 좁게 끊겼다. 문제 목록은 왼쪽 들여쓰기에 비해 오른쪽 여백이 달라 비대칭으로 보였다. 각각 내용을 문단으로 나누고, 폭 제한과 좌우 여백을 조정했다.

처음 보였던 문제	바꾼 방식
위치와 목표가 한 문장처럼 이어졌다	항목별로 줄과 문단을 나눴다
긴 목차가 화면을 많이 차지했다	학습과 실습을 각각 접을 수 있게 묶었다
문제와 설명이 비슷하게 보였다	목표와 문제 영역의 배경을 구분했다
힌트가 긴 문단으로 나열됐다	문제 번호와 풀이 순서에 맞춰 구분했다
열린 정답에도 열기라는 표시가 남았다	접힌 상태와 열린 상태에 맞춰 문구를 바꿨다
링크를 누르면 가이드에서 벗어났다	외부 링크는 새 탭에서 열도록 했다

목차는 기초 학습과 P1~P8 실습으로 나누어 접고 펼칠 수 있게 했다. 좁은 화면에서는 목차를 필요할 때 열고, 원하는 항목으로 이동한 뒤 본문을 볼 수 있도록 했다. 코드 영역과 목차의 스크롤 모양도 페이지와 맞췄다. 문서가 길어질수록 본문 자체뿐 아니라 원하는 위치로 돌아오는 방법도 중요했다.

새 탭 처리는 외부 링크에 적용했다. 같은 문서의 학습 단계로 이동하는 목차까지 새 창에서 열면 오히려 흐름이 끊기기 때문이다. 독립 HTML 파일에서 접근할 수 없는 저장소 내부 경로는 클릭 가능한 파일 링크처럼 보이게 두지 않고, 실습자가 찾아야 할 경로로 표시했다. 어디로 이동하는 링크인지도 문서 사용성에 영향을 줬다.

이 작업을 하면서 가이드의 디자인이 단순히 보기 좋게 꾸미는 문제가 아니라는 생각이 들었다. 문제를 찾기 어렵거나 힌트의 대응 관계가 흐리면, 코드를 이해하기 전에 문서를 해석하는 데 힘을 쓰게 된다. 내가 여러 번 요구했던 줄바꿈과 여백도 결국 같은 이유였다. 읽는 사람이 지금 해야 할 일을 놓치지 않게 만드는 것이 우선이었다.

---

결과

상품 카드의 안내 표시 범위를 분리하고, 구매 가능 문구에 번역을 적용했으며, 배송 안내 섹션으로 여러 개념을 함께 사용해보았다. 그 과정을 바탕으로 README와 브라우저에서 열 수 있는 HTML 가이드를 정리했다. 기초 학습부터 후속 실습까지 이어지는 구조 안에 목표, 문제, 힌트, 정답과 완료 기준을 두었다.

구현 실습에서는 실제 미리보기로 문구와 조건별 표시를 확인했다. 가이드 화면은 Chromium에서 1440, 768, 390, 320px 너비로 확인했고, 목차와 접기 영역의 동작, 키보드 조작, 이미지와 내부 이동도 점검했다. 펼친 상태에서도 좁은 화면의 본문이 가로로 밀리지 않는지 확인했다. 단순히 HTML 파일이 생성됐다는 것과 읽을 수 있는 화면이 나왔다는 것을 나눠 확인한 셈이었다.

Theme Check 결과도 그대로 기록했다. 새 번역 키를 일부 언어 파일에만 추가해 누락 진단이 생긴 부분은 나머지 파일에도 키를 보완했다. 다만 영어 문구로 채운 항목을 각 언어의 번역이 끝난 것으로 볼 수는 없었다. 실제 프로젝트에서는 제공하는 언어 전체에 맞는 번역을 준비해야 한다는 설명을 가이드에 남겼다.

테마 전체의 기존 진단과 다른 변경에서 생긴 진단도 남아 있었으므로, 전체 Theme Check를 통과했다고 정리하지 않았다. 이번 학습으로 생긴 문제인지, 원래 있던 문제인지를 구분하는 일이 먼저였다. 경고가 있다는 이유만으로 모든 실습이 잘못됐다고 판단하거나, 화면이 나온다는 이유로 검사 결과를 무시하는 쪽 모두 피하려 했다.

아직 확인하지 못한 부분도 있다. 처음 보는 사람이 새로운 개발 스토어에서 가이드 전체를 끝까지 따라 하는 검증은 하지 않았다. 모든 브라우저와 실제 모바일 기기에서 동일한 결과를 확인한 것도 아니다. 이번 결과는 내가 수행한 실습을 다른 사람이 시도할 수 있게 정리하고, 문서 화면의 주요 동작을 확인한 단계다.

직접 따라 해볼 수 있도록 가이드를 첨부했다

아래 두 자료는 HTML 파일이다. 내려받은 뒤 브라우저에서 열면 된다. 테마 실습 가이드는 상품 상세 화면을 중심으로 코드를 수정하는 연습 자료이고, Admin 가이드는 관리자 메뉴의 역할과 연결 관계를 살펴보는 참고 자료다. 실습은 각자의 개발용 테마에서 진행하면 된다.

• Shopify 테마 실습 가이드 다운로드 (.html) — 학습 목표, 단계별 문제, 접어서 확인하는 힌트와 정답을 포함했다.
• Shopify Admin 메뉴 가이드 다운로드 (.html) — 주문·상품·고객·콘텐츠 등 관리자 메뉴를 파악할 때 함께 볼 수 있다.

Admin 가이드는 별도로 정리해두었던 자료를 함께 첨부했다. 외부 참고 문서를 열려면 인터넷 연결이 필요하며, Admin 가이드의 웹폰트도 온라인에서 불러온다. 두 가이드 모두 처음에는 기기의 밝은 테마·어두운 테마 설정을 따른다. 상단의 화면 테마 메뉴에서 직접 바꿀 수 있으며, 브라우저가 저장을 허용하면 선택이 유지된다. 첨부 파일은 이 글을 작성한 시점의 버전이다.

---

느낀점

• 같은 코드를 쓴다는 것과 같은 설정을 쓴다는 것은 다르다. 상품 데이터, 섹션 인스턴스의 설정, 스니펫 호출 매개변수를 구분하니 수정이 어디까지 영향을 주는지 설명하기 쉬워졌다.
• 종합 과제에는 선택해야 할 조건이 있어야 한다. 이미 만든 기능의 재확인도 필요하지만, 요구사항을 보고 데이터와 설정의 역할을 나누는 연습은 별도로 필요했다.
• 내가 이해한 순서를 남기는 것만으로는 부족했다. 파일 위치와 기대 결과, 실패했을 때 확인할 지점이 있어야 다른 사람이 같은 실습을 시작할 수 있었다.
• 힌트도 문제와 연결되어야 했다. 설명이 많아지는 것보다 몇 번 문제의 어느 부분을 돕는지 분명하게 만드는 편이 읽는 사람에게 유용했다.
• 문서의 화면도 확인할 대상이었다. 줄바꿈과 여백, 접기와 목차가 어색하면 내용이 맞아도 따라 읽기 어려웠다. 가이드를 만드는 일에도 실제 사용 화면을 보는 과정이 필요했다.

처음에는 테마 공부를 어디서 시작할지 알아보는 것이 목적이었다. 이제는 직접 수정한 내용을 설명하고, 다른 사람이 시도할 수 있는 순서로 다시 정리하는 단계까지 왔다. 이 문서를 팀에 전달한 뒤 실제로 막히는 지점을 받아보면, 내가 혼자 읽을 때 놓친 부분도 더 분명해질 것 같다.

긴 글 읽어주셔서 감사하다.