Serialization

Your app is likely to have to save and restore the content of the vwRtx instances it displays.

We get the value to store via the directly accessible vwRtx.config value.

Provide this value as the instantiation config object and the new vwRtx instance will be identical in appearance to the the data that was saved.

This is about why and how the output from vwRtx.config is missing some things you might expect to see there.

TLDR

You may notice some attributes appear to be missing from the output of instance.config. These missing atributes can be omitted because they match the baseline values hard-coded into vwRtx. They will be applied when you send the config object back into a vwRtx instance.

If you want the un-dehydrated version, use the instance.detailed getter instead of instance.config.

Getting the current value

To get a plain JS object that describes the configuration of a vwRtx instance, get the rtx.config value. Store this value and use it later to set up a new instance that will look and behave just like when it was serialized.

// set up instance #1 with shape #1
const rtx1 = new vwRtx({
    host: hostShape,
    text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod..."
})

const config = rtx1.config // get the config

// set up instance #2 with shape #2
const rtx2 = new vwRtx(config)  // #2 now appears same as instance #1

Note #1 - in practical use, the config object returned from vwRtx.config will more complex than shown in this example. In particular, multi-styled text will include a config.textDef object with style configurations for the text in the various paragraphs of the instance. Regardless, the getting and setting of vwRtx.config data is the optimum way to store and re-produce what is seen in a vwRtx instance.

Note #2 - the vwRrtx.id will be reset when a stored config is reloaded. This is done to ensure that the id continues to be unique in its current operational context.

Dehydration

We kow that we can get a serializable object via rtx.config. But when we look at the object it appears to be missing some or many attributes. This is dehydration.

Lets think about what information we need to save in order to be able to reload it into a new vwRtx instance in the future and have this new version be identical to the last.

Imagine a case like this, an instance displaying the first few lines from Carl Sagan's book Pale Blue Dot.

From this distant vantage point, \nthe Earth might not seem of any particular interest. \nBut for us, it's different.

Lets assume we give most of the passage the font config of Arial 16px, and the word distant will be italic Roboto 18px with a fill color of Aqua.

If we were to analyse this text letter by letter, make a para for each paragraph we find (using \n as the separator) and a run for each difference in the font styling we would get the following, using a simple pseudo approach to defining the fonts.

textDef: {
    paras: [
        {
            id: "para0",
            runs: [
                {
                    font: "Arial 16px",
                    text: "From this "
                },
                {
                    font: "Italic Roboto 18px Aqua",
                    text: "distant "
                },
                {
                    font: "Arial 16px",
                    text: "vantage point, "
                }
            ]
        },
        {
            id: "para1",
            runs: [
                {
                    font: "Arial 16px",
                    text: "the Earth might not seem of any particular interest. "
                }
            ]
        },
        {
            id: "para2",
            runs: [
                {
                    font: "Arial 16px",
                    text: "But for us, it's different."
                }
            ]
        }
    ]
}

Which gives us 5 runs of text. But we can already see that there are 4 repetitions of the font definition for Arial 16px. And this will be a common pattern. Think of an email you might write - it's probably mostly the same style with the odd word underlined or in bold for impact. Can we reduce that repetition? Yes - if we scoop up the fonts and put them into an indexed list then we can replace those individual definitions with the font index.

textDef: {
    fonts: [
         "Arial 16px",
         "Italic Roboto 18px Aqua"
    ]
    paras: [
        {
            id: "para0",
            runs: [
                {
                    font: 0,
                    text: "From this "
                },
                {
                    font: 1,
                    text: "distant "
                },
                {
                    font: 0,
                    text: "vantage point, "
                }
            ]
        },
        {
            id: "para1",
            runs: [
                {
                    font: 0,
                    text: "the Earth might not seem of any particular interest. "
                }
            ]
        },
        {
            id: "para2",
            runs: [
                {
                    font: 0,
                    text: "But for us, it's different."
                }
            ]
        }
    ]
}

Now we've simplified the font definitions. Is there anything we can do to compress the paras? There is - we can combine contiguous paras that have the same font definitions. Look at para 1 below, which is merged with para2.

textDef: {
    font: [
         "Arial 16px",
         "Italic Roboto 18px Aqua"
    ],
    paras: [
        {
            id: "para0",
            runs: [
                {
                    font: 0,
                    text: "From this "
                },
                {
                    font: 1,
                    text: "distant "
                },
                {
                    font: 0,
                    text: "vantage point, "
                }
            ]
        },
        {
            id: "para1",
            runs: [
                {
                    font: 0,
                    text: "the Earth might not seem of any particular interest. \nBut for us, it's different."
                }
            ]
        }
    ]
}

Is there any more we can do? Yes. The textDef is a child object inside the config object. There is also a font definition node in the config object. This is used to define the starting font information for a new vwRtx instance, and it is the initial go-to font info for any text that doesn't have an explicit font definition.

config: {
    font: "Arial",
    textDef: {
        font: [
            "Italic Roboto 18px Aqua"
        ],
        paras: [
            {
                id: "para0",
                runs: [
                    {
                        text: "From this "
                    },
                    {
                        font: 0,
                        text: "distant "
                    },
                    {
                        text: "vantage point, "
                    }
                ]
            },
            {
                id: "para1",
                runs: [
                    {
                        text: "the Earth might not seem of any particular interest. \nBut for us, it's different."
                    }
                ]
            }
        ]
    }
}

We can now see that the font references are all removed except for the distant run which is the only font that differs. All of the other runs no longer have a font index number because they use the font node in the config object.

Did you spot that the font size on the config.font has been removed? That is because there is a baseline font definition hard coded within vwRtx, and 16px is it's value for fontSize. This is slightly contrived to illustrate the point but actually, since the font definition has 12 attributes in total, the fact we can avoid having to specify everything all the time is useful. For example, not all your text will be in bold, underline, strikeout, or have a letterSpacing or lineHeight values set. See the font details for information about font definitions and defaults.

The reduction in byes here is from 437 in the initial structure to 341 with all of the space saving applied. Thats down to 78% of the original. Assuming a longer passage of text with more paragraphs, this compression rate will increase. Theoretically it would be possible to dehydrate further but at the expence of human readability and external usability.

Optimum dehydration

In the case that all of the text uses the same font styling, then it would produce an object as below. Becase all of the text uses a single font definition, we no longer need the more complex textDef object and we can use the single text attribute to contain all of the text regardless of the fact that it generates multiple paragraphs.

config: {
    font: "Arial 32px",
    text: "From this distant vantage point, \nthe Earth might not seem of any particular interest. \nBut for us, it's different."
}

Note that if any of the paragraphs had specific alignment, justification, or other attributes set then it would be necessary to employ the textDef approach.

The un-dehydrated version?

If you need to see the config object with all of the attributes remaining, then instead of instance.config use instance.detailed.