README

Finally a fully-functional, complete and clean port of the Jade language to PHP

— Abraham Lincoln

The Tale Jade Template Engine brings the popular and powerful Templating-Language Jade for Node.js to PHP!

Tale Jade is the first complete and most powerful Jade implementation in PHP.

Update Time!

Tale Jade is receiving a larger update at this time which will bring in more stability, extensibility and better integration possibilities. I'm pretty busy right now, that's why it will take quite a while until it is finished.

If you're starting a larger project right now, be assured that there will be API changes from 1.4 to 1.5. Your Jade files will render just as they did before, but if you add own filters or extend Tale Jade in another way, things might break with the update.

If you know you've extended Tale Jade in 1.4 you might as well just stick to 1.4 (It's pretty stable and functional).

If you want to take a look at what we're up to, check out the compiler-enhancements branch. It contains the latest updates (It's not a working version yet, though!)

If you want to help out, send PRs.

Getting Started

Install with Composer

Download Composer

The composer package for Tale Jade is called talesoft/tale-jade

If you want to get started right now, hook up composer and run

$ composer require "talesoft/tale-jade:*"
$ composer install

or add it to your composer.json by yourself

{
    "require": {
        "talesoft/tale-jade": "*"
    }
}

Install by downloading the sources

You can also download the sources by yourself.

Tale Jade is compatible with the PSR-0 and PSR-4 autoloading standards.

Put the sources inside your a Tale/Jade subfolder inside your autoloading directories, e.g. library/Tale/Jade and you're ready to go!

The easiest way might be to just put a clone of the repository there, that way you can update it easier

$ git clone git@github.com:Talesoft/tale-jade.git library/Tale/Jade

or as a sub-module if you're using git for your project as well

$ git submodule add git@github.com:Talesoft/tale-jade.git library/Tale/Jade

Rendering a Jade Template

Include the vendor/autoload.php file of composer in your PHP script and get started with Tale Jade!


use Tale\Jade;

//Include the vendor/autoload.php if you're using composer!
include('vendor/autoload.php');

$renderer = new Jade\Renderer();

echo $renderer->render('your-jade-file');

This way, the renderer will search for your-jade-file.jade in your get_include_path()-paths. Notice that the path passed to render should be relative. You can give it absolute paths, but it will make caching harder.

We show you how to add alternative search paths further in the Basic configuration section below.

When the Jade-file gets rendered, a ./cache/views-directory is created automatically and the compiled PHTML will be stored in that directory.

To change this directory, use the cachePath-option


$renderer = new Jade\Renderer([
    'cachePath' => '/your/absolute/cache/path'
]);

The Jade-file will now be rendered to that directory on each call.

To enable a cache that won't render the files on each call, use the lifeTime option of the file-adapter


$renderer = new Jade\Renderer([
    'lifeTime' => 3600 //Will cache the file for 3600 seconds (one hour)
]);

Basic configuration

To enable formatting of the PHTML-output, use the pretty-option


$renderer = new Jade\Renderer([
    'pretty' => true
]);

If you don't want to use the get_include_path()-paths (which could actually harbor a security risk in some cases), pass your own search paths to the Renderer. Rendered and included Jade-files will be searched in those paths and not in the get_include_path()-paths anymore.


//Either with
$renderer = new Jade\Renderer([
    'paths' => [__DIR__.'/views']
]);

//or with
$renderer->addPath(__DIR__.'/views');

As soon as you pass any path, the loading from the get_include_path()-paths will be disabled and you always load from your passed directory/ies.

To pass variables to your Jade-file, use the second argument of the render-method


echo $renderer->render('index', [
    'title' => 'Jade is awesome!',
    'content' => 'Oh yeah, it is.'
]);

These can be used inside Jade as normal variables

h1= $title

+content-block($content)

Supported features

We support every single feature the original Jade implementation supports! This always has been and will always be our main target.

But why stop there? PHP has it's own features that are surely different from JavaScript's. By utilizing those features we aim to bring in more, compatible features into the language to make the fastest template development ever possible!

You can try features and see a bunch of examples on our sandbox site

Supported official Node.js Jade Features

Supported Tale Jade Features

Other cool features

Automatic isset-checks for simple variables with ?-flag to disable the behavior
Inbuilt Markdown, CoffeeScript, LESS, SCSS/SASS and Stylus support
Escapable text for HTML/-PHP-output
UTF-8 support via PHP's mb_* extension
Indentation detection and support for any indentation kind you like
Hackable and customizable renderer, compiler, parser and lexer
Huge amount of (optional) configuration possibilities
Graceful compiler forgiving many mistakes (e.g. spaces around the code)
Lightning fast and clean compilation
Detailed error handling
Renderer with different adapters
Intelligent expression parsing based on bracket counting
Huge documentation available
Tested well and maintained actively

There's more to come...

Tale Jade is actively used and developed in many projects and is improved constantly.

We don't stick to the Jade-convention, but we'll always provide compatibility to Node.js Jade to help reducing confusion.

We love Jade, we love PHP, we love Node.js and we love the official and original Jade-contributors.

Planned features:

Command line tools
Import Attributes (include some-file(some-var='some-value'))
Helper Libraries (Own custom helper libraries)
Aliases (Like mixins, just smaller)
Website Kit for easy website creation with Tale Jade
Stylus integration
CoffeeScript integration
Markdown integration
Extensions and package manager

Documentation Resources

Tale Jade Live Compiler A compiler for you to play with in your browser as well as a whole bunch of examples to give you a grasp of what Tale Jade is capable of.

The Tale Jade API Docs The documentation of the Tale Jade source code. Generated with phpDocumentor, but is's fairly enlightening.

Official Node.js Jade Documentation The real thing. This is where everything that we do here originates from. The syntax is the same, only the code-expressions are different.

Tale Jade Bootstrap A quick-start project to get you up and running. Fork it, download it, play with it. Don't forget to run composer install before launching (Download Composer)

Development Test Files The example files we tested the engine with. We cover all features somewhere in there, for sure!

Tale Jade Unit Tests The Unit Tests we're using to ensure stability. There will be new tests added constantly and most features are covered here. It's PHP code, though.

Tale Jade in for your favorite framework

You're using a framework with a template engine already, but you really want to try out Jade? Search no further.

Thanks to the Tale Jade Community we got some modules for existing frameworks that allow you to use Tale Jade easily!

Symphony XSLT CMS

(This is not the Symfony PHP Framework)

vdcrea's Jade Editor

Your framework is missing? Send us an e-mail and we'll get a bridge up and running as soon as possible!

A great thanks to the contributors of these modules!

Get in touch

If you find a bug or miss a function, please use the Issues on this page to tell us about it. We will gladly hear you out :)

Don't forget to support our work if you like it!

If you'd like to contribute, fork us, send us pull requests and we'll take a deep look at what you've been working at! We're completely Open Source! You can do anything you like with our code as long as you stick to the MIT-license we've appended.

You can also contact us via E-Mail info@talesoft.io

Thank you for using Tale Jade. Let us spread the Jade-language together!

marihachi / tale-jade

Maintainers

Details