Angel3 Developer Guide
  • README
  • Foreword
  • Tutorial
    • Getting Started
    • Minimal Setup
  • Command Line Interface
    • Setup
  • Templates and Views
    • Server Side Rendered Views
    • JAEL3
      • About
      • Basics
      • Custom Elements
      • Strict Resolution
      • Directive: declare
      • Directive: for-each
      • Directive: extend
      • Directive: if
      • Directive: include
      • Directive: switch
  • Authentication
    • About
    • Strategies
    • Local
  • Databases
    • Object Relational Mapping (ORM)
      • About
      • Basic Functionality
      • Relations
      • Migrations
      • PostgreSQL
    • NoSQL
  • Extensions and Plugins
    • Using Plug-ins
    • Writing a Plugin
  • Under the hood
    • Basic Routing
    • Requests & Responses
    • Request Lifecycle
    • Dependency Injection
    • Middleware
    • Controllers
    • Parsing Request Bodies
    • Serialization
    • Service Basics
    • Testing
    • Error Handling
    • Pattern Matching and Parameter
  • Angel Framework Migration
    • Angel 2.x.x to Angel3
      • Rationale - Why a new Version?
      • Framework Changelog
      • 3.0.0 Migration Guide
    • Angel 1.x.x to 2.x.x
      • Framework Changelog
      • 2.0.0 Migration Guide
  • Packages
    • Authentication
    • CORS
    • Database-Agnostic Relations
    • Configuration
    • Databases
      • ORM
      • MongoDB
      • JSON File-based
      • RethinkDB
    • Templates and Views
      • Jael template engine
      • Mustache Templates
      • compiled_mustache-based engine
      • html_builder-based engine
      • Markdown template engine
      • Using Angel with Angular
    • Hot Reloading
    • Pagination
    • Polling
    • Production Utilities
    • REST Client
    • Reverse Proxy
    • Router
    • Serialization
    • Service Seeder
    • Static Files
    • Security
    • Server-sent Events
    • shelf Integration
    • Task Engine
    • User Agents
    • Validation
    • Websockets
  • Resources
    • Dependency Injection Patterns
    • Example Projects
    • YouTube Tutorials
    • Ecosystem
Powered by GitBook
On this page
  • Defining Elements
  • Passing Data
  • Specifying a Tag Name
  • Emitting without a Tag Name

Was this helpful?

  1. Templates and Views
  2. JAEL3

Custom Elements

PreviousBasicsNextStrict Resolution

Last updated 3 years ago

Was this helpful?

HTML is good for its purpose, because each element (ex. div, a, ul), has its own purpose, and when invoked, reproduces specific functionality.

The goal of proposals like Web Components, and frameworks like React, Vue, and Angular, is to let developers create custom components that encapsulate data and can be called to reproduce specific output.

Jael also supports defining elements; in fact, they are analogous to defining functions in Dart code.

The benefit of defining custom elements in Jael as opposed to in a client-side framework is that they build directly to standard HTML, and require no additional features in an end-user's browser.

Defining Elements

To define your own element, simply use the <element> tag:

<element name="todo-item">
    <input type="checkbox" checked=todo.completed disabled>
    {{ todo.text }}
</element>

The best practice is to define elements in their own file, so that they can be imported into the scope using an tag:

<extend src="layout.jl">
    <block name="content">
        <include src="todo-item.jl" />
        <todo-item for-each=todos @todo=item />
    </block>
</extend>

Passing Data

You might have noticed that in the earlier example, some attributes of the todo-item were prefixed with an arroba (@), while others were not. There is, of course, a reason for this.

When rendering a custom element, attributes with the @ are injected into the custom element's scope. This is analogous to passing arguments to a function.

Attributes without the @ are passed to the root of the created element. Thus, you can pass attributes like class and style to custom elements, and therefore apply visual effects, etc.

Directives like if and for-each also work with custom elements, of course.

Specifying a Tag Name

By default, custom elements are replaced with a div. There may be times you wish to override this, for example, to render a todo-item as an a element.

Use the special as attribute to facilitate this:

<todo-item as="a" for-each=todos @todo=item />

Emitting without a Tag Name

There may be times when you need to emit the contents of an element, without a container element. In such a case, pass as=false, and the contents will be rendered in the current context, rather than in a new element.

include