
Enter a search term above to see results...
Enter a search term above to see results...
Your components HTML structure is defined by template and a data context to generate your component’s html.
Comparing to React - Instead of using a
render()
function to returnjsx
each component’s template provides the high level logic for explaining how html should be rendered from data for your component and will automatically re-render sections of a template depending on the reactivity of the data.
Your template defines how your component’s html is rendered:
if
else if
and else
For more information on all the features of templates check our dedicated subsection on templates.
The templates data context is a combination of several data sources that are looked up in sequence.
For instance our template might include something like
Greetings, {name}
This will check for name
in each of these locations and then return the first available defined value.
name
name
name
passed in via html attribute or propertyname
name
Simplified Data Structures - A template’s data context is flat to make templates easier to read and to give flexibility when moving values between locations. For instance you may initially have a value as a
property
on your component, then move it tostate
to make it reactive, then finally move it tosettings
to make it user overridable without having to modify the underlying template.
Global helpers are special utilities that are available across all templates and provide utilities like classMap
, formatDate
, concat
stringify
that can be used to format values for output.
For a list of global helpers please visit the dedicated global helper page in templating.
In this example formatDate
is used to format the display of a date set in the components state.
{formatDate currentTime 'h:mm:ss a'}
For a complete list of available global helpers see global helpers.
Settings are values which you want users of your component to be able to modify. To specify settings for a component simply pass in a settings object when defining a component.
Data Types - A settings type will be inferred from its default value. This means you do not need to formally declare them as
String
orDate
.
const defaultSettings = { name: 'Jack'};
defineComponent({ tagName: 'name-card', defaultSettings});
Settings specified for a component are defaults which can be overridden by anyone using your component by passing in different data through the DOM.
<name-card name="Sally"></name-card>
const el = document.querySelector('name-card');el.name = 'Sam';
Functions cannot be serialized so they must be passed in via Javascript. This can be handled using Query’s settings
method after DOM Ready or initialize
method at any point in page load.
You can also manually set the function on the corresponding DOM element.
State is a reactive data store that uses Signals to recompute references to a value when its underlying vaalue is modified.
State is designed you to store internal reactive values that can be used to re-render portions of a template when a value changes, or to rerun reactive computations when underlying reactive data changes.
const defaultState = { name: 'Jack'};
defineComponent({ tagName: 'name-card', defaultState});
Each component will have its own copy of state
initialized with its default value set based off your configuration.
You can use state inside a component by destructuring state
from any lifecycle events.
const createComponent = ({self, state}) => ({ getGreeting() { // state is { name: Signal('Jack') } return `Hello ${state.name.value}` }});
state
like other reactive values can be accessed by name directly in templates without having to use value
or get
Hello {name}
Your component instance stores methods and properties that implement the functionality of your component. These can be various locations where you might want to access functionality, like from other parts of the component, templates, or externally via the DOM.
You can use your component instance to store specialized logic that is necessary for your component.
Any method or property declared in createComponent
can be accessed directly from your template.
const createComponent = ({self, state}) => ({ // get user's current age getAge(user) { // 31557600000 = 365.25 days * 24 hours * 60 minutes * 60 seconds * 1000 milliseconds return Math.floor((new Date() - new Date(user.born_date)) / 31557600000); }});
{getAge user}
You can access your template instance as self
, component,
or tpl
from other callbacks to invoke functionality.
For more information see lifecycle events.
const onRendered = ({ self }) => { self.incrementCounter();};
You can also access your component instance directly from the DOM from the component
property.
For more information see from DOM.
const { component } = document.querySelector('ui-counter');component.incrementCounter();
SUI components can either be rendered to a tagname as a web component or exported to be used as subtemplates in other components. This is dependent on whether tagName
is specified
When no tag name is specified they are returned as Subtemplates which can be passed in to other components.
When components are rendered as subtemplates, their data context is defined explicitly from the parent template.
For example, you might want to have a table that uses a subtemplate to output a table row, definining the data context as the row’s data for each initialization.
You can pass any type of javascript primitive as a setting however there may be serialization requirements depending on the date type.
Strings and numbers can be passed in either through html attributes or directly as properties.
Arrays, objects and dates can be passed in either through attributes or properties.
When passed in as attributes the data must be passed through JSON.stringify
to serialize the value as a string.
If you are passing it in as a property you can specify the value without serialization.
For a complete picture of how an expression is looked up from inside your template’s data context, please refer to the following chart: