279 lines
8.5 KiB
Text
279 lines
8.5 KiB
Text
import { Meta } from '@storybook/blocks';
|
|
|
|
import * as ScrollerStories from './Scroller.stories.svelte';
|
|
|
|
<Meta of={ScrollerStories} />
|
|
|
|
# Scroller
|
|
|
|
The `Scroller` component creates a basic scrollytelling graphic with layout options.
|
|
|
|
This component is designed to handle most common layouts for scrollytelling. To make something more complex, customise [ScrollerBase](?path=/story/components-graphics-scrollerbase--docs), which is a Svelte 5 version of the [svelte-scroller](https://github.com/sveltejs/svelte-scroller).
|
|
|
|
[Demo](?path=/story/components-graphics-scroller--demo)
|
|
|
|
```svelte
|
|
<script>
|
|
import { Scroller } from '@reuters-graphics/graphics-components';
|
|
|
|
import MyBackground from './MyBackground.svelte'; // Your own background component
|
|
|
|
// Array of step objects that define the steps in your scroller.
|
|
const steps = [
|
|
{
|
|
background: MyBackground,
|
|
backgroundProps: { colour: 'red' }, // Optional props for your background component
|
|
foreground: '#### Step 1\n\nLorem ipsum red',
|
|
altText: 'Red background',
|
|
},
|
|
{
|
|
background: MyBackground,
|
|
backgroundProps: { colour: 'blue' },
|
|
foreground: '#### Step 2\n\nLorem ipsum blue',
|
|
altText: 'Blue background',
|
|
},
|
|
{
|
|
background: MyBackground,
|
|
backgroundProps: { colour: 'green' },
|
|
foreground: '#### Step 3\n\nLorem ipsum green',
|
|
altText: 'Green background',
|
|
},
|
|
];
|
|
</script>
|
|
|
|
<Scroller {steps} foregroundPosition="middle" backgroundWidth="fluid" />
|
|
```
|
|
|
|
## Using with ArchieML and ai2svelte
|
|
|
|
[Demo](?path=/story/components-graphics-scroller--archie-ml)
|
|
|
|
In your graphics kit project, import your ai2svelte graphics in `App.svelte` and add them to the `aiCharts` object:
|
|
|
|
```svelte
|
|
<!-- App.svelte -->
|
|
<script>
|
|
import AiMap1 from './ai2svelte/my-map-1.svelte';
|
|
import AiMap2 from './ai2svelte/my-map-2.svelte';
|
|
import AiMap3 from './ai2svelte/my-map-3.svelte';
|
|
|
|
import content from '$locales/en/content.json';
|
|
|
|
// Graphics kit only
|
|
import { assets } from '$app/paths'; // 👈 If using in the graphics kit...
|
|
import { truthy } from '$utils/propValidators'; // 👈 If using in the graphics kit...
|
|
|
|
const aiCharts = {
|
|
AiMap1,
|
|
AiMap2,
|
|
AiMap3,
|
|
// Other charts...
|
|
};
|
|
</script>
|
|
```
|
|
|
|
Then add the following structure to your ArchieML Doc, making sure that the names of your charts in the `aiCharts` object match the names of each step's `background` in the ArchieML doc:
|
|
|
|
```yaml
|
|
# ArchieML doc
|
|
[blocks]
|
|
type: ai-scroller
|
|
id: my-map-scroller
|
|
width: fluid
|
|
foregroundPosition: right
|
|
stackBackground: true
|
|
|
|
# Array of step objects
|
|
[.steps]
|
|
background: AiMap1
|
|
foreground: #### Step 1
|
|
|
|
Here's where something happend.
|
|
:end
|
|
altText: A map showing the Upper West side in New York City.
|
|
|
|
Can add paragraphs of alt text if you want to break up sentences.
|
|
:end
|
|
|
|
background: AiMap2
|
|
foreground: #### Step 2
|
|
|
|
Something happened on some street...
|
|
:end
|
|
altText: The same map now highlights 98th Street.
|
|
:end
|
|
|
|
background: AiMap3
|
|
foreground: #### Step 3
|
|
|
|
... and now there are multiple protests.
|
|
:end
|
|
altText: The same map now highlights three locations near 98th Street where something particulary important happened.
|
|
:end
|
|
[]
|
|
[]
|
|
```
|
|
|
|
Then parse the relevant ArchieML block object before passing to the `Scroller` component.
|
|
|
|
```svelte
|
|
<!-- App.svelte -->
|
|
{#each content.blocks as block}
|
|
{#if block.type === 'ai-scroller'}
|
|
<Scroller
|
|
id={block.id}
|
|
backgroundWidth={block.backgroundWidth}
|
|
foregroundPosition={block.foregroundPosition}
|
|
stackBackground={truthy(block.stackBackground)}
|
|
steps={block.steps.map((step) => ({
|
|
background: aiCharts[step.background],
|
|
backgroundProps: { assetsPath: assets || '/' },
|
|
foreground: step.foreground,
|
|
altText: step.altText,
|
|
}))}
|
|
/>
|
|
{/if}
|
|
{/each}
|
|
```
|
|
|
|
> **Note:** Some props, like `stackBackground`, expect boolean values. If you're using the graphics kit, use the `truthy()` util function to convert a string value to a boolean.
|
|
|
|
> **Note:** In the graphics kit, the image source paths in ai2svelte components have to be fixed by passing `assets` to each step object, like in the example above.
|
|
|
|
## Custom foreground
|
|
|
|
[Demo](?path=/story/components-graphics-scroller--custom-foreground)
|
|
|
|
Instead of just text, you can use components as foregrounds, and optionally pass props to it.
|
|
|
|
If you're customising your own foreground component, remember to add alt text that describes the background graphic.
|
|
|
|
```svelte
|
|
<script>
|
|
import MyBackground from './MyBackground.svelte'; // Your own background component
|
|
import MyInteractiveForeground from './MyInteractiveForeground.svelte'; // Your custom foreground component
|
|
|
|
const steps = [
|
|
{
|
|
background: MyBackground,
|
|
backgroundProps: { colour: 'red' }, // Props for your background component, if needed
|
|
foreground: MyInteractiveForeground, // Custom foreground component
|
|
},
|
|
{
|
|
background: MyBackground,
|
|
backgroundProps: { colour: 'blue' },
|
|
foreground: '#### Step 2\n\nLorem ipsum blue', // You can still add a markdown string as foreground; you can mix and match
|
|
},
|
|
{
|
|
background: MyBackground,
|
|
backgroundProps: { colour: 'green' },
|
|
foreground: MyInteractiveForeground,
|
|
foregroundProps: { count: 100 }, // Props for your custom foreground component, if needed
|
|
},
|
|
];
|
|
</script>
|
|
|
|
<Scroller {steps} />
|
|
```
|
|
|
|
## Custom foreground with ArchieML
|
|
|
|
[Demo](?path=/story/components-graphics-scroller--customforeground-archie-ml)
|
|
|
|
You can use custom foreground components with ArchieML with a few additional steps.
|
|
|
|
In your graphics kit project's `App.svelte`, import your custom foregroud components and add them to a `foregroundComponents` object, just as you import ai2svelte background graphics and add them to the `aiCharts` object:
|
|
|
|
```svelte
|
|
<!-- App.svelte -->
|
|
<script>
|
|
import content from '$locales/en/content.json';
|
|
|
|
// Background ai2svelte graphics
|
|
import AiMap1 from './ai2svelte/my-map-1.svelte';
|
|
import AiMap2 from './ai2svelte/my-map-2.svelte';
|
|
import AiMap3 from './ai2svelte/my-map-3.svelte';
|
|
|
|
// Foreground components, which can be ai2svelte or not.
|
|
import Foreground1 from './ai2svelte/my-foreground-1.svelte';
|
|
|
|
// Graphics kit only
|
|
import { assets } from '$app/paths'; // 👈 If using in the graphics kit...
|
|
import { truthy } from '$utils/propValidators'; // 👈 If using in the graphics kit...
|
|
|
|
// Background ai2svelte graphics components
|
|
const aiCharts = {
|
|
AiMap1,
|
|
AiMap2,
|
|
AiMap3,
|
|
// Other charts...
|
|
};
|
|
|
|
// Foreground components
|
|
const foregroundComponents = {
|
|
Foreground1,
|
|
// Other components...
|
|
};
|
|
</script>
|
|
```
|
|
|
|
Then add the following structure to your ArchieML Doc, making sure that the names of your charts in the `aiCharts` and `foregroundComponents` objects match the names of each step's `background` and `foreground` in the ArchieML doc:
|
|
|
|
```yaml
|
|
# ArchieML doc
|
|
[blocks]
|
|
type: ai-scroller
|
|
id: my-map-scroller
|
|
foregroundPosition: left
|
|
stackBackground: true
|
|
|
|
# Array of step objects
|
|
[.steps]
|
|
background: AiMap1
|
|
# You can still use a markdown string even if other step/s use a custom foreground component
|
|
foreground: #### Step 1
|
|
|
|
Here's where something happend.
|
|
:end
|
|
altText: A map showing the Upper West side in New York City.
|
|
:end
|
|
|
|
background: AiMap2
|
|
foreground: Foreground1 # The name of your custom foreground component
|
|
altText: The same map now highlights 98th Street.
|
|
:end
|
|
background: AiMap3
|
|
foreground: #### Step 3
|
|
|
|
... and now there are multiple protests.
|
|
:end
|
|
altText: The same map now highlights three locations near 98th Street where something particulary important happened.
|
|
:end
|
|
[]
|
|
[]
|
|
```
|
|
|
|
Then parse the relevant ArchieML block object before passing to the `Scroller` component.
|
|
|
|
```svelte
|
|
<!-- App.svelte -->
|
|
{#each content.blocks as block}
|
|
{#if block.type === 'ai-scroller'}
|
|
<Scroller
|
|
id={block.id}
|
|
backgroundWidth={block.width}
|
|
foregroundPosition={block.foregroundPosition}
|
|
stackBackground={truthy(block.stackBackground)}
|
|
steps={block.steps.map((step) => ({
|
|
background: aiCharts[step.background],
|
|
backgroundProps: { assetsPath: assets || '/' },
|
|
foreground: foregroundComponents[step.foreground] || step.foreground,
|
|
foregroundProps: { assetsPath: assets || '/' },
|
|
altText: step.altText,
|
|
}))}
|
|
/>
|
|
{/if}
|
|
{/each}
|
|
```
|
|
|
|
> **Note:** You only need to pass `foregroundProps: { assetsPath: assets || '/' }` in the graphics kit if your foreground components are ai2svelte graphicss.
|