Fudgel comes with a few helpful functions that you should leverage to squeeze as much as you can out of this tiny library. They will help you communicate with other web components and perform common activities.
emit - Sending Data to ParentsDispatching events from your controller can be tricky with the shadow DOM. Also, for minification, you will probably want to leverage shared code to send events.
rootElement - Access the content DOM element
Your component creates all of its template elements in one
parent element. When using a shadow DOM, this is the shadow DOM
element. Otherwise, this is the custom element. To easily
access this element from your controller for content
manipulation, use rootElement().
update - Redrawing the UIWhen you update internal data within an object, the change detection will not pick it up. You can flag specific properties as needing to be redrawn, as this example shows.
Name: {{user.name}}
` }, class { onInit() { this.user = { name: "Test User" }; } clicked() { this.user.name = "Updated"; update(this, "user"); } });
update() takes two optional parameters and behaves
differently depending on what you pass into the function.
update(controller, 'property') - Updates all
bindings for a single property on a controller. This is the
fastest call to make.
update(controller) - Reruns all bindings that
are attached to the controller. This affects all properties
and every dynamic piece of HTML that is controlled by your
controller.
update() - The slowest of all ways to trigger
an update, this form will update all bindings for all Fudgel
components everywhere.
html and css - Dummy Tagged Template
Functions
There are some build tools that will allow minification of HTML
and CSS when they are used within
tagged template literals. Fudgel exports html() and css() as
empty tag functions so your toolset will detect the appropriate
type of template and allow minification. You can see them in use
with the
Be Prepared
PWA, which also uses Vite and a plugin to minify the HTML and
CSS used the template literals.
di - Dependency InjectionAlso included is a minimal dependency injection system, allowing you to inject services into your components. Why use dependency injection? Well, it makes testing much easier, plus you only need to indicate what you want as opposed to how you obtain it or its dependencies.
A requirement for this system is that you must not have side-effects in the constructors of the services being injected. If you can follow that rule, then this system will work for live sites, test systems, and even work after your code is minified.
When you write tests, you will potentially want to push in a
mock to the dependency injection service. You can do that using
diOverride(). The only trick is that this must run
within the same browser sandbox (eg. iframe) where Fudgel is
running.
Emitter - Send data to other things outside of the
DOM
Node.js has an EventEmitter and it's useful for communication
between services. The browser has an Event object that can be
emitted up the DOM tree, but nothing really geared for services.
Fudgel comes with a tiny event emitter you can use in your code.
The emitter that is created supports
.on(name, callback),
.off(name, callback) and
.emit(name, ...data). Also,
.on(name, callback) returns a function to remove
the callback (the same as using
.off(name, callback) with the correct parameters).
controllerToElement - Get an element from a controllerFudgel components have controllers that are separated from the DOM element. To help eliminate circular references and encourage garbage collection, Fudgel only links elements directly to controllers and not vice-versa. This map allows you to query for an element if you have a controller. This might be useful when you need to manipulate the DOM element from a component that uses the shadow DOM.
It is possible for this to return null when the
DOM element is deleted. Because JavaScript doesn't support
destroying objects, the controller instance might persist long
after the DOM element is gone.
Look this value up every time you need it. Do not cache the result because it could lead to memory leaks in your application.
elementToController - Get a controller from a Fudgel DOM elementWhen a child needs to access a parent's controller, this map will retrieve the current bindings between DOM elements and Fudgel controllers.
It is possible for this to return null when the
element is not registered to Fudgel.
The below examples use the shadow DOM just to help illustrate when this is needed. Using shadow DOMs is not required for this to work.