template_cache 0.1.1

  • README.md
  • Installing
  • Versions
  • 30

Template Cache for Dart

Templates in Dart can be implemented in different ways:

1. Parsing at runtime

This approach is the most straightforward approach, requiring no special compiling. This can be bad for performance, though. To counterweight that, templating languages implemented in this way can end up lacking in features instead.

2. Static precompilation

For static pages, all templates can be rendered ahead of time. This is great for performance since all the complexity is handled at build time. However, this means that logic cannot be computed at runtime.

3. Precompilation into Dart

The third way to do it is to precompile the templates into native Dart code, which will be super fast at runtime, and can be built into the main code base using Dart2JS for production. This can be confusing, though, because Dart files must be imported in the source code.

Usage

This library simplifies option 3 from above. Here's how to use it:

Consider this project.

├── bin
│   └── server.dart
├── templates
│   └── my_template.some_ext
├── tool
│   └── compile_templates.dart
└── web
    ├── index.html
    └── index.dart

In this example, we keep the templates in a templates directory.

To compile our templates, we run dart tool/compile_templates.dart:

import 'package:template_cache/cache.dart';
import 'package:SOME_PACKAGE_THAT_GIVES_US_A_COMPILER';

final cache = new Cache([
  new SomeThirdPartyCompiler() // <-- This compiler compiles ".some_ext" files
]);

main() async {
  await cache.compile('templates/my_template.some_ext');
}

Now, to render the template, in both the web/main.dart or bin/server.dart files, we can simply use the render function:

import 'package:template_cache/render.dart';

main() {
  var view = render('templates/my_template.some_ext');
}

The render function returns a Stream<String>, so that compilers can incorporate asynchrony in the most performant way.

If the compiler supports it, render has a named locals parameter, accepting variables into the template. The locals are supplied as Map<Symbol, dynamic>.

render('my_template.hbs', locals: {
  #someVariable: "some value"
});

Note: Using symbols rather than strings as keys allows the template code to access locals directly without using mirrors. This is explained below.

Compilers

A compiler must satisfy a simple contract, and can take configuration in its constructor, since that will be exposed to the consumer (as shown above).

The compile method in the contract returns a special GeneratedTemplateCode data object, containing the generated code as two strings. The first one contains imports for the generated script. The second contains the main render method body, in a async* context.

import 'dart:async';

import 'package:template_cache/cache.dart';

class MyCompiler implements Compiler {
  final ContentType contentType = ContentType.HTML; // Supplied for use with servers
  final Iterable<String> extensions = ['.my_ext', '.my_other_ext'];

  Future<GeneratedTemplateCode> compile(Uri file, Stream<String> source) async {
    // Use the [file] and [source] arguments to generate the code

    return new GeneratedTemplateCode(
      '''
        import "some_specific_import_that_the_template_will_require" as package;
      ''',

      r'''
        yield r"A line!\n";

        yield someLocal + r'\n';

        package.someImportedMethod();

        if (someBooleanLocal) {
          yield r"A conditional line!\n";
        }
      '''
    );
  }
}

Using the above MyCompiler, the workflow would be something like this:

Build time

final cache = new Cache([
  new MyCompiler()
]);

cache.compile('some_template.my_ext');

Runtime

render('some_template.my_ext', {
  #someLocal: 'Hello, World!',
  #someBooleanLocal: true
});

Output

A line!
Hello, World!
A conditional line!

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  template_cache: "^0.1.1"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or flutter packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


      import 'package:template_cache/cache.dart';

      import 'package:template_cache/html_compiler.dart';

      import 'package:template_cache/plain_text_compiler.dart';

      import 'package:template_cache/render.dart';
  
Version Uploaded Documentation Archive
0.1.1 Sep 16, 2016 Go to the documentation of template_cache 0.1.1 Download template_cache 0.1.1 archive

Analysis

We analyzed this package on Jun 19, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.0.0-dev.63.0
  • pana: 0.11.3

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
0 / 100
Health:
Code health derived from static analysis. [more]
84 / 100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
24 / 100
Overall score:
Weighted score of the above. [more]
30
Learn more about scoring.

Platforms

Detected platforms: Flutter, other

Platform components identified in package: io, isolate.

Suggestions

  • Fix analysis and formatting issues.

    Analysis or formatting checks reported 2 errors 19 hints.

    Strong-mode analysis of lib/src/cache_io.dart failed with the following error:

    line: 18 col: 12
    The return type 'Completer' isn't a 'Future<Null>', as defined by the method 'write'.

    Run dartfmt to format lib/cache.dart.

    Similar analysis of the following files failed:

    • lib/html_compiler.dart (hint)
    • lib/plain_text_compiler.dart (hint)
    • lib/src/_gen/templates.dart (hint)
    • lib/src/cache.dart (hint)
    • lib/src/codegen_contract.dart (hint)
    • lib/src/render.dart (hint)
    • lib/src/simple_compiler_base.dart (hint)
    • lib/src/uid.dart (hint)
  • Package is getting outdated.

    The package was released 91 weeks ago.

  • Package is pre-v1 release.

    While there is nothing inherently wrong with versions of 0.*.*, it usually means that the author is still experimenting with the general direction API.

  • Maintain an example.

    Create a short demo in the example/ directory to show how to use this package. Common file name patterns include: main.dart, example.dart or you could also use template_cache.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
current_script >=0.0.3 <0.1.0 0.0.3
glob >=1.1.1 <2.0.0 1.1.5
path >=1.3.9 <2.0.0 1.6.1
Transitive dependencies
async 2.0.7
charcode 1.1.1
collection 1.14.10
source_span 1.4.0
stack_trace 1.9.2
string_scanner 1.0.2
Dev dependencies
quark any
test any