The Wayback Machine - https://web.archive.org/web/20221102145008/https://github.com/symfony/ux
Skip to content

symfony/ux

2.x
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

This PR was squashed before being merged into the 2.x branch.

Discussion
----------

[LiveComponents] Hello Component JS Object

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| Tickets       | Fix None
| License       | MIT

Hi!

This is effectively a rewrite of the LiveComponents frontend (with minimal effect on users). It introduces:

A) A `Component` object that "mirrors" your PHP component object and lives in a `__component` property of your element - this allows you to do cool things like:

```js
const component = document.getElementById('component-id').__component

// set the firstName property and re-render
// effectively set the firstName property on your PHP object
component.firstName = 'Ryan';

// trigger the "save" LiveAction
component.save();
```

B) Logic is much more organized between `live_controller.ts` (mostly event listening & initialization), `Component.ts` (model+action & Ajax handling) and a number of "plugins" that add loading, polling, etc).

C) Child handling is more intelligent: child components will NOT re-render when their parent component re-renders, unless the data passed *into* the child has changed. It does this by generating a "fingerprint" (checksum) of the values that are passed *into* a child component when `{{ component() }}` is called. Then, when a parent re-renders, the "fingerprints" if its children are sent with the request. If any of those fingerprints are seen to have changed during the re-render, then we know the "input" to a child has changed and the child should be re-rendered (which is done basically by sending a signal to the child component to re-render itself with a new set of props).

D) Child/parent data passing is now done with a `dataModel` prop.

TODOs:

* [x] 1) Update CHANGELOG
* [x] 2) add some sort of `v-model` (previously called `data-model-map`) ability: where a child can communicate a model change to its parent
* [X] 3) BACKEND: pass `data` (writable props) & `props` separately as live controller values
* [x] 4) BACKEND: pass the a deterministic `data-live-id` attribute to the child unless manually specified
* [x] 5) BACKEND: pass a "fingerprint" value to Stimulus (fingerprint is a checksum of the values passed IN when creating a component)
* [x] 6) BACKEND: read `childrenFingerprints` data for GET (JSON-encoded query param) and POST (request body). Use this to compare to the NEW fingerprint value for each child. If not changed, render the child as an empty element (with only `data-live-id`). If changed, render an empty element, but with `data-live-id`, the new fingerprint `data-` value *and* the new `data-live-props-value`.
* [ ] 7) DOCS: Add at least one new example to ux.symfony.com
* [ ] 8) DOCS: add example with data-live-id manually being set on a child so it re-renders under some situation
* [ ] 9) Find better example for the custom Stimulus controller that goes around the component in the docs
* [ ] 10) (Maybe later) a way for a child component to trigger a re-render on the parent (without a model in the parent needing to change)

Cheers!

Commits
-------

aac55bf Adding a data-model system for sync'ing data between parent and child components
fd97102 Fixes various tests
9701450 Resetting deterministic id to avoid numbering problems in different parents
5df34f2 Renaming class that was in a bad directory & new event
4909915 Setting childrenFingerprints from request onto MountedComponent
2ffbd2c fixing outdated internal reference to before rerender
0adcdc3 Adding a fingerprint to child components that is a hash of their "input props"
297e388 Fixing bug where file paths on the system caused id to not be so deterministic
ed462f3 Adding ComponentStack to keep track of currently-rendered components and parents
fc4883c Split backend to data and props
d1076f8 Updating docs for working via JS & making change event always update a model
e38381e abstracting last bits of markup out of component
30619de Making several component methods return a Promise
0c56bc6 Removing todo and other things that will be re-worked later
321f2e4 Moving more systems into plugins
45bcaf4 removing data-live-id-value in favor of data-live-id - no need for both
3ccf783 Abstracting more markup-related thing to the new "driver" + plugin system
1394883 Reset models when resetting data from server
07f8517 Work on child rendering tests
e5cc4e0 Starting new child tests
6b7fcd2 Sending childrenFingerprints data to server on Ajax call
526e570 Adding the fingerprint to the system, but not using it yet
b1ac91c client-side implementation of differentiating between data & props
2a22483 initial component child tracking/setup
32d4ff3 WIP heavy refactoring to Component
9bf843b # This is a combination of 6 commits. # This is the 1st commit message:
01412c2

Git stats

Files

Permalink
Failed to load latest commit information.

Symfony UX: a new JavaScript ecosystem for Symfony

Symfony UX is an initiative and set of libraries to seamlessly integrate JavaScript tools into your application. For example, want to render a chart with Chart.js? Use UX Chart.js to build the chart in PHP. The JavaScript is handled for you automatically.

That's Symfony UX.

Symfony UX leverages Stimulus for JavaScript and the Stimulus Bridge for integrating it into Webpack Encore.

Resources

Let's build an amazing ecosystem together

Symfony UX is an initiative: its aim is to build an ecosystem. To achieve this, we need your help: what other packages could we create in Symfony UX? What about a library that automatically adds an input mask to the text fields of your Symfony forms? Or the ability to make the EntityType render with AJAX auto-completion? Anything you do in JavaScript could be done streamlined as a UX package.

We have some ideas, and we will release more packages in the coming days. The rest is on you: let's create an amazing ecosystem together!

Contributing

If you want to test your code in an existing project that uses Symfony UX packages, you can use the link utility provided in this Git repository (that you have to clone). This tool scans the vendor/ directory of your project, finds Symfony UX packages it uses, and replaces them by symbolic links to the ones in the Git repository.

# Install required dependencies
$ composer install

# And link Symfony UX packages to your project
$ php link /path/to/your/project