pulsar_web 0.1.4

A lightweight frontend framework for Dart with HTML templates, CSS styles, reactivity and Jinja-like templating.

Pulsar Web Framework

Pulsar is a lightweight Dart web framework for building web SPAs combining the simplicity of HTML + CSS with Dart using Jinja templates and reactive components

Installation

Disclaimer: Pulsar Web Framework is still under development so the versions 0.x.y can be strongly modified as this package gets new features and fixes. This version of Pulsar is only recommended for personal, private or test use. Please consider to give feedback for every bug you find or open a new issue at the Github Repository.

Use the pulsar_cli to create and serve projects. Run the following command to activate it

  dart pub global activate pulsar_cli

Then use the create command for make a new project.

  pulsar create hello

Project structure

A Pulsar project must have the structure of the example below:

  web/
    ├─ index.html
    ├─ main.dart
    └─ components/
        └─ hello/
            ├─ hello.dart
            ├─ hello.html
            └─ hello.css

Component creation

Every component extends from Component class and defines:

• tagName -> Name of the wrapper tag for the component (div by default)
• props() -> Available variables in the HTML template
• template() -> Component's HTML content (inline using multiline Strings or extern using loadFile() function)
• style() -> Component's CSS content (inline using multiline Strings or extern using loadFile() function)
• methodRegistry -> Available methods in the HTML template

Example: hello.dart

import 'package:pulsar_web/pulsar.dart';

class Hello extends Component {
  String hello = "Hello Pulsar!";

  @override
  Map<String, dynamic> props() => {'hello': hello};

  @override
  Map<String, Function> get methodRegistry => {
    "helloMethod": helloMethod,
  };

  @override
  Future<String> template() async =>
      await loadFile('path/to/hello.html');
  @override
  Future<String?> style() async =>
      await loadFile('path/to/hello.css');

  void helloMethod(PulsarEvent event) => setState(() => hello = "Goodbye Pulsar!");
}

Note: If you are using loadFile() keep in mind that the root directory for this function is web/. So every template must be inside the web/ directory. Example: loadFile("components/hello/hello.html").

hello.html

<span>{{hello}}</span>
<button @click="helloMethod">Press Me</button>

main.dart

  import 'package:pulsar_web/pulsar.dart';
  import 'components/hello/hello.dart';

  void main() {
    runApp([Hello()]);
  }

Then execute:

  pulsar serve

Register and insert components using Provider

If you want to insert a component into HTML you have to use a Provider, the ComponentRegistry and the {% insert %} tag.

Structure:

  web/
    ├─ index.html
    ├─ main.dart
    └─ components/
        ├─ app_root/
        │   ├─ app_root.dart
        │   ├─ app_root.html
        │   └─ app_root.css
        ├─ hello/
        │   ├─ hello.dart
        │   ├─ hello.html
        │   └─ hello.css
        └─ component_provider.dart

Example: component_provider.dart

import 'package:pulsar_web/pulsar.dart';
import 'hello/hello.dart';
class ComponentProvider extends Provider {
  @override
  void registerComponents() {
    register("Hello", () => Hello());
  }
}

Note: This structure is optional. Every component can have its own provider if you want.

Define a root component to insert the child.

app_root.dart

import 'package:pulsar_web/pulsar.dart';

class AppRoot extends Component {
  @override
  Future<String> template() async =>
      await loadFile('components/app_root/app_root.html');

  @override
  Future<String> style() async => await loadFile('components/app_root/app_root.css');

  @override
  Map<String, dynamic> props() => {};
}

Then use the {% insert "Hello" %} syntax to import the component in the app_root.html and we can insert it the times we want. Remember that you can use Jinja tags into the HTML like {% if condition %}, {% for item in list %} if you want.

app_root.html

  <h1>Welcome to App Root</h1>
  <hr/>
  {% insert "Hello" %}

Finally import the provider and pass it to the runApp() function.

main.dart

  import 'package:pulsar_web/pulsar.dart';
  import 'components/component_provider.dart';
  import 'components/app_root/app_root.dart';

  void main() {
    runApp([AppRoot()], componentProvider: ComponentProvider());
  }