5.2.0 B1 – Documentation Requests

[devinelston]

I know you guys are working on the documentation/videos, just sharing a few notes about stuff I’d find useful as I try to wrap my head around this new feature set (the complexity of what’s possible increased dramatically with this release, so it’s a little tougher to just “get” on first glance).

No need to respond to these all here. These are mostly just brain dumps of things that I wondered about, but couldn’t figure out, in the current drafts of the docs.

Parameters

• I’d find it useful to have examples illustrating real world use-cases for the different settings.
• What are all the possible type values?
• Is there a way to mimic the base/interaction color picker?
• Is there a way to reference global colors as the initial value for colors?
• Can parameters be used to turn on/off things like the sub headline controls? Or to turn on/off padding? etc.
• In the section referencing the Conditions logic, I’d like to suggest using a different example than the one that includes a side parameter. Reason being is that earlier in the documentation, you talk about things to the "left “side” of the : and the “right side” of the :. So I got super confused in the example that references left and right and side as a parameter name too in the conditional logic, because I kept thinking the example had to do with the left and right side of the : explanation. So another real-world example would be super helpful here too.

Also, are Parameters currently intended for the use-case of setting a global value and being able to reference that in any component (for example, being able to set a specific text value that shows up in a bunch of different places, etc.)? Or is that something more for one of the future releases you’re working on?

Components

• Can you share some more about how the Private setting is useful? With maybe an example?
• Do you have recommendations for how to handle something like wanting to have 3 different styles of a button that all maintain the exact same padding and shape – but have different styling for colors? For example, a Primary Button, Secondary Button, and Ghost Button that all have the exact same setup, but different colors depending on the type. Would this be a scenario where using the power of the parameters could help – like maybe set up a type : select parameter with condition logic for the different colors for different types of buttons?
• The explanation of how to access section components within the builder would be handy too

––

I’ll just tack on to this thread if think of any others. Thanks!

[devinelston]

Masks

• Maybe I’m just not reading the documentation correctly, but I can’t figure out how to do a linear mask at an angle (e.g. mask the bottom left corner). I’m assuming it’s possible, as one of the examples of the bridge appears to be doing that… but I’m missing something.

[alexander]

Thank you! We’ll review this and update docs with more information. I’ll answer some of these here inline as well for a less official reference in the meantime. I’ll add a few comments here to answer some questions inline while also serving as some notes we can use to source the docs from.

Parameters

Is there a way to mimic the base/interaction color picker?

Unfortunately no, in Parameters each unique value must be managed on its own line.

Is there a way to reference global colors as the initial value for colors?

Yes, but you need to go locate the ID first. If you inspect an element using the color and use the Dev Toolkit you’ll find values that look like global-color:4bab657e-3c22-4ab2-86dc-3af3820e5755. To use that as an initial color, you can define a parameter like this:

{
  "my-accent-color": "color|global-color:4bab657e-3c22-4ab2-86dc-3af3820e5755"
}

Can parameters be used to turn on/off things like the sub headline controls?

Unfortunately no, you can’t really do anything with Parameters that isn’t already possible via Dynamic Content. You could use it to zero out a value or set it to an empty string though. Like this:

"padding": {
  "type": "choose",
  "options": [ { "value": "20px", "label": "On" }, { "value": "0px", "label": "Off" } ]
}

Thanks for pointing out how using left, right, etc. for an example us confusing! We can definitely make some tweaks there.

Also, are Parameters currently intended for the use-case of setting a global value and being able to reference that in any component (for example, being able to set a specific text value that shows up in a bunch of different places, etc.)? Or is that something more for one of the future releases you’re working on?

The underlying tech for Parameters was made to eventually serve that purpose, which we’re calling “Globals”. When that is available it will feature a visual editor instead of having to author them with JSON.

[alexander]

What are all the possible type values?

Choose

{
  "type": "choose",
  "options": [ { "value": "visible", "label": "Visible" }, { "value": "hidden", "label": "Hidden" } ]
}

Code

{
  "type": "code",
  "placeholder": "Shown when the editor is empty",
  "lint": "json"
}

• placeholder is optional.
• lint is optional and not linting will be applied when omitted. It can be css, js, or json.

Color

{ 
  "type": "color",
  "palette": false
}

• palette is optional. It may be helpful to disable the palette if integrating with something that isn’t compatible with our global color system

Dimension

{
  "type": "dimension"
}

Options:

• units - Should be an array of strings of units types you want available. All CSS units are enabled by default
• keywords - Determine which keyword and CSS functions like auto calc etc. should be shown in the unit picker. This doesn’t prevent the value from being hand typed, it just keeps it out of the unit picker UI.
• slider - Set to false to disable the slider

Size

{
  "type": "size"
}

Same as Dimension but includes the “auto” keyword by default

Min Size

{
  "type": "min-size"
}

Same as Dimension but includes the “none” keyword by default

Max Size

{
  "type": "max-size"
}

Same as Max Size, just a different name for semantics

Font Size

{
  "type": "min-size"
}

Same as Dimension but has more appropriate default ranges for the sliders

Letter Spacing

{
  "type": "min-size"
}

Same as Dimension but has more appropriate default ranges for the sliders

Fa Icon

{
  "type": "fa-icon"
}

Shows a Font Awesome picker. No options.

Font Family

{
  "type": "font-family"
}

Font Weight

{
  "type": "font-weight"
}

This parameter must always be immediately after a Font Family parameter to properly display the weights available with that family. If you want to move it somewhere else, you need to set a family option to the name of the parameter to synchronize with.

Image

{
  "type": "image"
}

No Options

Number

{
  "type": "number",
  "silder": false,
  "min": 0,
  "max": 1,
  "step": 0.1
}

None of these options are required

• slider disable the unit slider
• min set a lower bound of the slider
• max set an upper bound of the slider
• step set the amount the slider increases/decreases

Placehment

{
  "type": "placement"
}

Used for integrating with some of the flex or grid controls.

• display - can be set to flex or grid. This determines what spec to work with since flex and grid have different values available
• axis - defaults to main but could be cross. This determines which justify/alignment options are presented
• iconDirection defaults to x. could also be y
• self set to true to only show flex options that pertain to aligning the current element rather than a parent element.

Select

{
  "type": "select",
  "options": [
    { "value": "n", "label": "North" },
    { "value": "s", "label": "South" },
    { "value": "e", "label": "East" },
    { "value": "w", "label": "West" }
  ]
}

Text

{
  "type": "text",
  "placeholder": "Shown when the editor is empty"
}

Also accepts a monospace option that can be set to true

Textarea

{
  "type": "textarea",
  "placeholder": "Shown when the editor is empty"
}

Also accepts a monospace option that can be set to true

Text Editor

{
  "type": "text-editor",
  "placeholder": "Shown when the editor is empty"
}

Also accepts a monospace option that can be set to true

[alexander]

Components

Can you share some more about how the Private setting is useful? With maybe an example?
Sure! Private components are useful for cases when you want to define abstractions for yourself that will only be used to make other components.

Scenario 1

• You’ve designed a site for a client.
• Your client has access to the page builder. and they can edit and add pages as needed.
• You disable most of the elements in the Cornerstone Library
• You create Components that follow your own design system and expose those to the client, effectively replacing the Element Library with your own patterns.

Expanding on that further…

• Maybe your “Library” to the client is just several predefined “blocks”, and you don’t give them any dropzones. They can scaffold new pages quickly and there’s low risk of them breaking the layout
• While building those blocks, you might realize you’re recreating the same two or three column layout over and over and want to abstract that to speed up producing more blocks.

Scenario 2

• Setup two rows (with single columns), some text in the first row and a dropzone in the second row. The second row has some generous padding, and centers the content
• Wire a parameter to the text, and make the dropzone a slot
• The whole section is exported as a component called “Documented Component” and make it private since it will never be needed on actual site content.
• Now when you want to make a bunch of Components, you can start by dropping in the "Documented Component. Then inside the slot/dropzone you can design whatever you want to be the actual Component. This helps eliminate the distraction of the wrapping markup when you’re focusing on designing smaller atomic patterns.
• In this example, the private component actually never reaches the front end and is mainly to help enforce consistency in the workflow

Do you have recommendations for how to handle something like wanting to have 3 different styles of a button that all maintain the exact same padding and shape – but have different styling for colors? For example, a Primary Button, Secondary Button, and Ghost Button that all have the exact same setup, but different colors depending on the type. Would this be a scenario where using the power of the parameters could help – like maybe set up a type : select parameter with condition logic for the different colors for different types of buttons?

Because Parameters are just a form of Dynamic Content, it’s not something we can conditionally wire up within a single element. However, you’re right, Element Conditions are still at play here. I’d recommend something like this:

1. Start with a Div and define some parameters

"btn-type": "choose",
  "options": [ { "value": "primary", "label": "Primary" }, { "value": "secondary", "label": "Secondary" }, { "value": "ghost", "label": "Ghost" } ]
}

2. Within that Div, add a new Div for each button. On each of them setup Element Conditions to only show when the correct type is selected like: {{dc:param:btn-type}} is ghost.

3. Style each inner div as needed.

Unfortunately there isn’t way to get rid of the wrapping markup.

The explanation of how to access section components within the builder would be handy too

In case anyone reading this needs it in the meantime: 5.2.0 B1 – Can't set a section as a component?

[alexander]

Great questions here by the way! We’ll see about getting this all surfaced in the official docs before launch.

[devinelston]

@alexander

In this example, the private component actually never reaches the front end and is mainly to help enforce consistency in the workflow

Ahhh, ok. Applying that to my button example, another way of accomplishing what I want is that I could make a “skeleton” button shape in one component set & mark it private. Then, in a second component set, I add that skeleton 3 times and apply different “skins” to each one, then export these as “Primary”, “Secondary”, & “Ghost”, etc. That kind of thing?

[alexander]

Yeah! That’s a great way of describing it. It lets you keep the main element library clean of any interstitial components that may not be useful as general purpose building elements.