Widget Stories

If you are familiar with Storybook, you already know what story is. don't worry if it's the first time you hear about it, we will explain the advantage of stories and how can be used in details.

Why stories ?

An editable widget is great in order to modify content inside a specific page, but imagine you have to use a widget inside multiple pages and you would like it to have the same editable values without having to change the content for each page separately.

For example, if we have a widget that represents a menu and you would like to use it on many pages, but also you want to be able to edit the menu items depending on the group of pages. If you create multiple versions, you will need to change all versions when you decide to change the layout, and if you choose the editable way, you will have to update the menu on each page each time.

Here when the stories come in, they are associated with all the versions of the widget and can hold property values that can be used inside any page. 

Add new stories

There is two ways we can create stories for widget
1- Using the code editor
2- Using the data icon in the widget control bar

Using the code editor

Let's create a code that can use the stories first, then we will add a new stories to it.
The following example presents a menu widget with many items.

  // set default value for the menu
  export let menuItems = [
    {name: "Home", link: "/"},
    {name: "Contact", link: "/contact"},
  export let selected = "Home"

<div class="flex space-x-4 p-4 bg-tertiary text-white">
 {#each menuItems as item}
  <a class:border-b-2={selected === item.name} href={item.link} class="border-white" >


Now we would like to control the menu and the selected item from outside the widget, to do that we need to click on Data Stories from the top bar of the editor

fouita stories

We will see this UI appears

fouita stories

We can import stories from other widgets or we can start by creating a new Schema. 
A Schema is a representation of what kind of properties you want the stories to handle. you might create many properties in your widget and you only need few of them to be updated via stories.

In our case we need to create two schemas, the first one will have the menuItems and the second one will have the selected value.

Note: keep in mind that you cannot select multiple stories under the same schema later.

Creating out first schema, we need to click on the "+" button.

fouita schema

You will notice that the attributes are automatically selected with the appropriate types. you can update attribute names and types before you save. You can also add new exported properties and click on "reload attributes" to see the schema changes.

For the first schema will will need to remove "selected" attribute and "save"

fouita schema

This is our first schema

fouita schema

When we click on it we will be able to add new stories

fouita stories

A new story would require the inputs from the schema defined, since the menuItem property is of a type object we need to insert JSON valid format.

We have used a different menu from the default code. we click "Save" and test our new story.

This is how the story look like.

fouita story

if we click on the "DefaultMenu", anywhere inside the box, the story will be selected and the items inside the editor will change.

fouita story

If we click again, the story will become unselected and we can see the initial menu back to normal.
The selected store inside the editor will set the default story to use when we insert the widget inside the page.

Creating a schema and stories for the selected property, is the same process. Except the selected property will have 3 stories in this case.
- Home
- Features
- About

fouita sotries

When we select on an item, the menu will switch the selected value

fouita stories

When we save our widget and add it to the page, it will look like this by default.

fouita page story

Update the story on the page

Using the data icon in the widget control bar we can access and update the schemas and stories.

fouita stories

Clicking on the DB icon will show the schemas of the widget

fouita stories

Note: shemas that has background blue indicates that they have a selected story for that widget inside that page 

When we click on "SelectItem" schema we can see the selected story by default

fouita story

We can now select the story that we like and it won't affect any other widget of the same version in any other page, or even the same page. the selection of the story inside a widget that has been added to a page will only concern that widget.

If we select "Features" we will see the selected item changed to "Features" in the menu.

fouita story select

Note: When we update the property value of a story, this will affect all widgets using that story to be updated with the new value.

That's it we have seen how to add and manipulate stories to update data inside widgets.
Next we will take a look at how we can add trackers to create custom analytics to our widgets.

The missing pieces of your website.
kairouan, tunisia
built using fouita!