import{R as i,j as e}from"./index-bIIEL2MP.js";import{useMDXComponents as a}from"./index-CO-0pc0F.js";import{M as d}from"./index-Z-6k0Xrj.js";import{p as h}from"./docsPage-CT2vyZOj.js";import"./_commonjsHelpers-D6-XlEtG.js";import"./iframe-CzjIX-qr.js";import"./index-aQYXhgXp.js";import"./index-DrFu-skq.js";const t=({number:o,children:n})=>{const r={display:"flex",alignItems:"flex-start",gap:"0.5em",marginTop:"1.5em"},l={display:"flex",justifyContent:"center",alignItems:"center",backgroundColor:"rgb(0 156 253)",color:"white",borderRadius:"50%",width:"1.8em",height:"1.8em",fontSize:"1em",fontWeight:"bold",lineHeight:"1",boxShadow:"0 2px 4px rgba(0, 0, 0, 0.2)",flexShrink:0},c={paddingTop:"0.25em",fontSize:"1em",lineHeight:"1.4em",wordBreak:"break-word"};return i.createElement("div",{style:r},i.createElement("div",{style:l},o),i.createElement("div",{style:c},n))};function s(o){const n={a:"a",blockquote:"blockquote",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",p:"p",pre:"pre",strong:"strong",...a(),...o.components};return e.jsxs(e.Fragment,{children:[e.jsx(d,{title:"Guides/Using with ArchieML docs",parameters:{...h}}),`
`,e.jsx(n.h1,{id:"using-components-with-archieml-docs",children:"Using components with ArchieML docs"}),`
`,e.jsxs(n.p,{children:["Most of the snippets in these docs show how to use components by passing data into their props directly. In most cases, though, you don't want to hard-code content in your project and instead will get those values from an ",e.jsx(n.a,{href:"https://archieml.org/",rel:"nofollow",children:"ArchieML"}),"-formatted document, hosted in either ",e.jsx(n.a,{href:"https://rngs.io",rel:"nofollow",children:"RNGS.io"})," or a Google Doc."]}),`
`,e.jsx(n.p,{children:"In most cases, it's straight forward to fill in component props from ArchieML values, but in some cases you may need to write a small bit of code to translate strings from an ArchieML doc into a different data type or to rearrange data from a doc into a specific format to match a component's props."}),`
`,e.jsx(n.h2,{id:"simple-example",children:"Simple example"}),`
`,e.jsxs(n.p,{children:["Let's look at a basic component, a ",e.jsx(n.code,{children:"ProfileCard"}),", with a demo that looks like this in the docs:"]}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-svelte",children:`<script>
  import { ProfileCard } from '@reuters-graphics/graphics-components';
<\/script>

<ProfileCard
  name="Kitty"
  age={2}
  img="https://cats.com/cat1.jpg"
  birthday={new Date('2020-09-25')}
  bio="Some notes.\\n\\nWith multiple paragraphs."
  isGood={true}
/>
`})}),`
`,e.jsx(n.p,{children:"Notice the component's props includes strings, a date, a number and a boolean."}),`
`,e.jsx(t,{number:"1",children:"In our ArchieML doc, we might fill out a block for this component like ..."}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-yaml",children:`[blocks]
# ...

type: profile-card
name: Tom
age: 10
picture: images/tom-the-cat.jpg
birthday: 2020-09-25
bio: A very frisky feline.

... and an avid mouser!
:end
isGood: true

# ...
[]
`})}),`
`,e.jsxs(n.p,{children:["It's often a good idea to give the properties in your ArchieML doc the same names as the props on the component you're using. That's what we've done above, but you can also name them something else. For example, we went with ",e.jsx(n.code,{children:"picture"})," instead of ",e.jsx(n.code,{children:"img"}),"."]}),`
`,e.jsxs(n.blockquote,{children:[`
`,e.jsxs(n.p,{children:["If the ArchieML syntax above looks foreign to you, check out the Help docs on any story in ",e.jsx(n.a,{href:"https://rngs.io",rel:"nofollow",children:"RNGS.io"})," or read the official ",e.jsx(n.a,{href:"https://archieml.org/#demo",rel:"nofollow",children:"ArchieML docs"})," to get familiar with the basics."]}),`
`]}),`
`,e.jsx(t,{number:"2",children:"When we download the doc, our ArchieML will turn into JSON data like ..."}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-json",children:`{
  "blocks": [
    {
      "type": "profile-card",
      "name": "Tom",
      "age": "10",
      "picture": "images/tom-the-cat.jpg",
      "birthday": "2020-09-25",
      "bio": "A very frisy feline.\\n\\n... and an avid mouser!",
      "isGood": "true"
    }
  ]
}
`})}),`
`,e.jsxs(n.p,{children:["Notice all the values in the data are ",e.jsx(n.strong,{children:"strings"}),". More on that soon."]}),`
`,e.jsx(t,{number:"3",children:"Now we can use that data to feed our component the information it needs for its props:"}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-svelte",children:`<script>
  // These are usually already imported for you
  import { assets } from '$app/paths';
  // Your ArchieML doc
  import content from '$locales/en/content.json';

  // Your component from graphics-components
  import { ProfileCard } from '@reuters-graphics/graphics-components';
<\/script>

{#each content.blocks as block}
  {#if block.type === 'text'}
    <!-- ... -->
  {:else if block.type === 'profile-card'}
    <ProfileCard
      name={block.name}
      age={parseInt(block.age)}
      img={\`\${assets}/\${block.picture}\`}
      birthday={new Date(block.birthday)}
      bio={block.bio}
      isGood={block.isGood === 'true'}
    />
    <!-- ... -->
  {/if}
{/each}
`})}),`
`,e.jsx(n.h3,{id:"but-lets-break-that-last-bit-down-",children:"But let's break that last bit down ..."}),`
`,e.jsxs(n.p,{children:["This is a loop that goes over each block in the ",e.jsx(n.code,{children:"blocks: []"})," array in the JSON data we downloaded from our ArchieML doc."]}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-svelte",children:`{#each content.blocks as block}
  <!-- ... -->
{/each}
`})}),`
`,e.jsxs(n.p,{children:["While we're looping over each individual block, we check its ",e.jsx(n.code,{children:"type"})," so we know which component to match it with. For example, ",e.jsx(n.code,{children:"block.type === 'text'"})," will signal we want to use our ",e.jsx(n.a,{href:"./?path=/docs/components-text-elements-bodytext--docs",children:"BodyText"})," component in this case."]}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-svelte",children:`{#if block.type === 'text'}
  <!-- ... -->
{:else if block.type === 'profile-card'}
  <!-- ... -->
{/if}
`})}),`
`,e.jsx(n.p,{children:"Once we've identified we have the right block for our component, we need to convert several of the data values from strings to the appropriate data type for each prop."}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-svelte",children:`<ProfileCard
  name={block.name}
  age={parseInt(block.age)}
  img={\`\${assets}/\${block.picture}\`}
  birthday={new Date(block.birthday)}
  bio={block.bio}
  isGood={block.isGood === 'true'}
/>
`})}),`
`,e.jsxs(n.p,{children:["For example, we're converting Tom's age into a number with JavaScript's ",e.jsx(n.a,{href:"https://www.w3schools.com/jsref/jsref_parseint.asp",rel:"nofollow",children:"parseInt"})," function ..."]}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-svelte",children:`{parseInt(block.age)}
`})}),`
`,e.jsx(n.p,{children:"... and we're parsing his birthday into a JavaScript Date ..."}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-svelte",children:`{new Date(block.birthday)}
`})}),`
`,e.jsxs(n.p,{children:["... and we're checking if he's a good cat by converting the string into a ",e.jsx(n.code,{children:"true"}),"/",e.jsx(n.code,{children:"false"})," boolean:"]}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-svelte",children:`{block.isGood === 'true'}
`})}),`
`,e.jsxs(n.p,{children:[e.jsx(n.strong,{children:"Especially note"})," how we're using the ",e.jsx(n.code,{children:"assets"})," module we talked about in ",e.jsx(n.a,{href:"./?path=/docs/guides-using-with-the-graphics-kit--docs",children:'"Using with the graphics kit"'})," to turn the ",e.jsx(n.em,{children:"relative"})," path to Tom's profile pic in our ArchieML doc into an ",e.jsx(n.em,{children:"absolute"})," path that will have the full ",e.jsx(n.code,{children:"https://reuters.com..."})," bit attached."]}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-svelte",children:"{`${assets}/${block.picture}`}\n"})}),`
`,e.jsx(n.h3,{id:"sum-it-all-up-",children:"Sum it all up 🏁"}),`
`,e.jsx(n.p,{children:"Tying your ArchieML doc to a component is as easy as:"}),`
`,e.jsx(t,{number:1,children:"Read what props your component needs in these docs."}),`
`,e.jsx(t,{number:2,children:"Write your ArchieML block to match those props."}),`
`,e.jsx(t,{number:3,children:`Convert the string values in your ArchieML JSON into the data types the
  component's props expect and pass them into your component!`}),`
`,e.jsx(n.h2,{id:"a-slightly-more-complex-example",children:"A slightly more complex example"}),`
`,e.jsxs(n.p,{children:["The simple example above is a variation of the majority of the components in these docs. Sometimes, though, a component's props get a little more complex, especially when they require an ",e.jsx(n.em,{children:"array"})," of objects with different data."]}),`
`,e.jsx(n.p,{children:"Let's look at another example component:"}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-svelte",children:`<Timeline
  title="A brief history of BitCoin"
  dates={[
    {
      date: new Date('1992-01-01'),
      subhed:
        'Cynthia Dwork and Moni Naor come with an idea for "cryptocurrency"',
      img: \`\${assets}/images/dwork-naor.jpeg\`,
    },
    {
      date: new Date('2008-08-18'),
      subhed: 'Domain name for bitcoin.org registered',
      link: 'https://bitcoin.org',
    },
    {
      date: new Date('2013-07-22'),
      subhed: 'The Winklevoss twins buy in',
      img: \`\${assets}/images/winkle-boys.jpeg\`,
    },
  ]}
/>
`})}),`
`,e.jsxs(n.p,{children:["Notice our ",e.jsx(n.code,{children:"Timeline"})," component's ",e.jsx(n.code,{children:"dates"})," prop takes an array of objects, each with required ",e.jsx(n.code,{children:"date"})," and ",e.jsx(n.code,{children:"subhed"})," properties and what appears to be ",e.jsx(n.em,{children:"optional"})," ",e.jsx(n.code,{children:"img"})," or ",e.jsx(n.code,{children:"link"})," properties."]}),`
`,e.jsx(n.p,{children:"To match that structure in our ArchieML doc, we might write it like ..."}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-yaml",children:`[blocks]
# ...

type: timeline
title: A brief history of Bitcoin
[.dates]
  date: 1992-01-01
  subhed: Cynthia Dwork and Moni Naor ...
  img: images/dwork-naor.jpeg

  date: 2008-08-18
  subhed: Domain name for bitcoin.org ...
  link: https://bitcoin.org

  date: 2013-07-22
  subhed: The Winklevoss twins ...
  img: images/winkle-boys.jpeg
[]

# ...
[]
`})}),`
`,e.jsxs(n.p,{children:[e.jsx(n.strong,{children:"Especially notice"})," the ",e.jsx(n.code,{children:"[.dates] ... []"})," bit. The ",e.jsx(n.code,{children:"."})," on ",e.jsx(n.code,{children:".dates"})," creates a ",e.jsx(n.em,{children:"nested"})," array on this block."]}),`
`,e.jsx(n.p,{children:"That leaves us with JSON data that looks like ..."}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-json",children:`{
  "blocks": [
    {
      "type": "timeline",
      "title": "A brief history of Bitcoin",
      "dates": [
        {
          "date": "1992-01-01",
          "subhed": "Cynthia Dwork and Moni Naor ...",
          "img": "images/dwork-naor.jpeg"
        },
        {
          "date": "2008-08-18",
          "subhed": "Domain name for bitcoin.org ...",
          "link": "https://bitcoin.org"
        },
        {
          "date": "2013-07-22",
          "subhed": "The Winklevoss twins ...",
          "img": "images/winkle-boys.jpeg"
        }
      ]
    }
  ]
}
`})}),`
`,e.jsxs(n.p,{children:["Now our data looks OK and all the properties on each date object that go into the Timeline component's ",e.jsx(n.code,{children:"dates"})," prop appear to match. It may look like we can pass our data straight into our component like ..."]}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-svelte",children:`<!-- ... -->
{:else if block.type === 'timeline'}
  <Timeline
    title="{block.title}"
    dates="{block.dates}""
  />
{/else}
<!-- ... -->
`})}),`
`,e.jsx(n.p,{children:"... but we have a couple problems and they all have to do with data types."}),`
`,e.jsxs(n.p,{children:["According to the component's docs, our ",e.jsx(n.code,{children:"date"})," property's value should be a JavaScript Date and our ",e.jsx(n.code,{children:"img"})," needs to be an absolute path."]}),`
`,e.jsx(n.p,{children:"But this is a problem we can solve by looping over our JSON data and making a new array where all the values are of the right type for our props."}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-svelte",children:`<script>
  // ...

  const timelineBlock = content.blocks.find((block) => block.type === 'timeline');

  const timelineDates = timelineBlock.dates.map((d) => {
    const date = new Date(d.date);
    const subhed = d.subhed;
    let img;
    let link;

    if (d.img) {
      img = \`\${assets}/\${d.img}\`;
    }
    if (d.link) {
      link = d.link;
    }

    return {
      date,
      subhed,
      img,
      link,
    };
  });
<\/script>

<!-- ... -->

{:else if block.type === 'timeline'}
  <Timeline
    title="{block.title}"
    dates="{timelineDates}""
  />
{/else}

<!-- ... -->
`})}),`
`,e.jsx(n.h3,{id:"ok-lets-break-down-that-new-chunk-of-code-",children:"OK, let's break down that new chunk of code ..."}),`
`,e.jsxs(n.p,{children:["First, notice I'm writing this code inside my ",e.jsx(n.code,{children:"script"})," tags so I can easily just write it with JavaScript."]}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-svelte",children:`<script>
  // Normal JavaScript is OK here ...
<\/script>
`})}),`
`,e.jsxs(n.p,{children:["Now the first thing I do is get ahold of ",e.jsx(n.em,{children:"just"})," my timeline block, leaving behind all the other blocks on my page, using a simple ",e.jsx(n.a,{href:"https://www.w3schools.com/jsref/jsref_find.asp",rel:"nofollow",children:"find"})," function."]}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-javascript",children:`// Gets JUST my timeline block from the array of all the blocks that make up my page
const timelineBlock = content.blocks.find((block) => block.type === 'timeline');
`})}),`
`,e.jsxs(n.p,{children:["With my timeline block in hand, I can loop over all my dates and create a ",e.jsx(n.em,{children:"new"})," array with all the values correctly parsed using a basic ",e.jsx(n.a,{href:"https://www.w3schools.com/jsref/jsref_map.asp",rel:"nofollow",children:"map"})," function."]}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-javascript",children:`const timelineDates = timelineBlock.dates.map((d) => {
  // "d" is each date object in the ArchieML JSON
  // ...
});
`})}),`
`,e.jsxs(n.p,{children:["Inside my ",e.jsx(n.code,{children:"map"})," I can convert the required properties into new variables matching my component's prop names. In this case, I need to convert the data, but the subhed is just a string ..."]}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-javascript",children:`const timelineDates = timelineBlock.dates.map((d) => {
  const date = new Date(d.date);
  const subhed = d.subhed;
  // ...
});
`})}),`
`,e.jsxs(n.p,{children:["For the optional ones, I'll do a tiny ",e.jsx(n.code,{children:"if"})," to check if the date has them before adding them to a variable:"]}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-javascript",children:`const timelineDates = timelineBlock.dates.map((d) => {
  // ...

  let img; // Start as an empty variable ...
  let link;

  // If our date has an image, we'll make it an absolute URL
  if (d.img) {
    img = \`\${assets}/\${d.img}\`;
  }

  // If it has a link, we'll just pass that on, as is
  if (d.link) {
    link = d.link;
  }

  // ...
});
`})}),`
`,e.jsxs(n.p,{children:["All that done, I can create my new object by returning it from my ",e.jsx(n.code,{children:"map"})," ..."]}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-javascript",children:`const timelineDates = timelineBlock.dates.map((d) => {
  // ...

  return {
    date,
    subhed,
    img,
    link,
  };
});
`})}),`
`,e.jsxs(n.p,{children:[e.jsx(n.strong,{children:"Finally"}),", I have a new array of dates all sorted for my timeline and I can pass them direcly in to the component's ",e.jsx(n.code,{children:"dates"})," prop:"]}),`
`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-svelte",children:`<script>
  const timelineDates = timelineBlock.dates.map((d) => {
    // ...
  });
<\/script>

{:else if block.type === 'timeline'}
  <Timeline
    title="{block.title}"
    dates="{timelineDates}""
  />
{/else}
`})}),`
`,e.jsxs(n.blockquote,{children:[`
`,e.jsxs(n.p,{children:["This is just ",e.jsx(n.em,{children:"one way"})," to prepare your data for your component in JavaScript. In many cases, generative AI tools like ChatGPT can also help you write the small bit of code you need. Just provide it a sample of the ArchieML JSON data and describe the format you need to convert it to for your component."]}),`
`]}),`
`,e.jsx(n.h3,{id:"sum-it-all-up--1",children:"Sum it all up 🏁"}),`
`,e.jsx(n.p,{children:"If your component has more complex props like arrays of objects ..."}),`
`,e.jsx(t,{number:1,children:"Write your ArchieML doc with nested arrays to match your component's props."}),`
`,e.jsx(t,{number:2,children:"Format your data in JavaScript using simple `find` and `map` functions."}),`
`,e.jsx(t,{number:3,children:"Pass the new formatted array into your components' props instead of the original ArchieML data."})]})}function y(o={}){const{wrapper:n}={...a(),...o.components};return n?e.jsx(n,{...o,children:e.jsx(s,{...o})}):s(o)}export{y as default};