Skip to main content

Why Templates Are Plain Files

Two ideas shape how CodeBaker templates work, and three shorter principles follow them. Working the other way round, from code that already works, has a page of its own.

1. Templates ARE Code​

Your templates are regular code files, not a special template format.

At its simplest, a template is just a folder with files: a file tree that CodeBaker copies into the folder you generate into, keeping the relative paths. On top of that comes the dynamic part that template engines usually offer: placeholders are replaced with your real values, and the file contents can use conditions, loops and other logic.

Besides the files that become your code, a template folder holds a mandatory configuration file, codebaker.config.json5, that describes the template: its name, its variables and other details. An optional mapping file, codebaker.advanced.json5, describes the more complex and advanced things, such as renaming files, generating them several times or updating existing files. Neither file is copied into your project.

  • Write templates in native file formats (.php, .ts, .java, .kt, etc.)
  • Your IDE highlights and inspects them like any other file
  • By default, a template can use the native syntax of the Pebble Template Engine (variables, filters, conditions, loops and more) to power its files
  • Work with templates just like you work with regular code

A template file with regular syntax​

// ❌ Native Pebble/Twig tags in the same positions - the IDE cannot parse this as PHP
class {{ className }} extends {{ baseClass }}
{
  protected ${{ propertyName }};
}
  • Syntax errors: PHP does not allow braces in a class name or a variable name

This sample will do the job: CodeBaker generates a dynamic file, replacing the placeholders with real values (see Template Basics).

The main downside is that, depending on the type of file or language, your IDE may mark the placeholders and other template syntax in red, because it does not understand them. That makes working with such a template a nightmare.

CodeBaker provides two basic approaches to solve this: custom placeholders that fit the programming language, and placing the dynamic instructions behind comments.

A template file that stays IDE-friendly​

// ✅ A CodeBaker template - valid PHP code
class ___ClassName___ extends ___BaseClass___ {
    protected $___propertyName___;

    public function get___PropertyName___()
    {
        return $this->___propertyName___;
    }
}

What your IDE gives you​

Because templates are normal files with normal extensions, you get the usual editor features:

  • Syntax highlighting for the file type
  • Code completion and navigation as far as the IDE can follow the code
  • Inspections and error highlighting (placeholders that are valid identifiers do not trigger errors)
  • Find in Files and ordinary refactoring tools, with the limits described on the Known Limitations page

2. IDE-First Design​

Templates are written so that your IDE can keep working on them.

Template tools tend to trade one thing for another:

  • Tags such as {{ name }} written directly in source files give you full template logic, but the file stops being valid code and editor support suffers.
  • Plain text substitution keeps files valid, but gives you no conditionals or loops.

CodeBaker's approach:

  • Values use Pebble's {{ varName }}, or placeholders such as ___varName___ that are valid identifiers in most languages. You can define custom placeholders for the cases where neither suits the language
  • Logic (conditionals, loops) goes in comments that start with CodeBaker:, so the template tags are hidden from the IDE
  • Real values (a color, a unit) can stay in the file, with the substitution described in a comment; see Inline & Block Replace

The cost is a few known limitations: in some positions a placeholder or directive still needs a workaround.

Same workflow as regular development​

  • Open and edit template files like any other file in the project
  • Search and replace across templates with Find in Files and Replace in Files
  • Review template changes in Git like any other change

More principles​

  • Git-centric: templates live in the .CodeBaker/ folder and are versioned with your code (see the Introduction).
  • Review before writing: the preview and diff show what will change, and you can edit generated content before it is written. Existing files are overwritten when you finish, after a confirmation, except files marked write-once with type: "seed" (see Advanced Templates).
  • No reformatting: CodeBaker does not reformat generated code. The output is your template rendered as is, so format the template the way you want the result to look.

Next Steps​