search

Samagra-Development / templater

Template Manager
2 stars 8 forks source link

readme

📃 Templater

Templater is a REST API service that can store, manage and render templates. A Template is like a well-defined format in which data can be entered. The output generated is according to the format defined in the template. Templater helps us simplify and enhance this process by providing multiple services such as Data transformation, Lambda API, Templater Playground, Support for multiple engines, etc.

Templater provides a common API for all the Templating Engines. This API helps the user manage the Templates across different Templating Engines. Most importantly, Templater allows the user to store, retrive, render and update these templates easily through a common Templater API.

What's a Template?

A Template is a structure or a format which holds some kind of data. Templates can be written in many languages and engines such as HTML, Javascript, Typescript, Razor view, Handlebars etc. But typically Templates that are written combine HTML with special tags. We can use these Templates for many purposes.

For example, we can write a Template to render a list of Employees through a Templating Engine.

<h1> Employees ({{ employees.length }}) </h1>
<ul>
{{ #each students }}
<li>{{ name }} ({joining { year }})</li>
{{ /each }}
</ul>

The data inside a Template is written in the form of JSON Strings and Objects. This data is usually retrieved from a backend or the database of the web application. For example,

{  
    "employee": {  
        "name":       "sonoo",   
        "salary":      56000,   
        "year":        2011  
    }  
}

This data is usually retrieved from a backend or the database of the web application. The Templating Engines renders this data as HTML through Templates. Finally, the output generated is according to the format designed in the template. Templating is used to generate documents, reports and data in a certain format.

Templating Engines

A Templating engine enables you to use static template files in your application. At runtime, the template engine replaces variables in a template file with actual values, and transforms the template into an HTML file sent to the client. This approach makes it easier to design an HTML page. These engines allow you to load data dynamically onto your website Front end. When you build a server-side application with a template engine, the template engine replaces the variables in a template file with actual values, and displays this value to the client. This makes it easier to quickly build our application.

Some Popular Examples of Templating Engines include:

📖 Table of Contents

🏹 Objectives

The objectives of templater are as follows:

👷 Architecture

The Templater Architecture is divided into several components.

This section is under construction

💻 Core Features

Transformer

The Transformer is one of the building blocks of Templater API. It helps us in Data transformation. Before inserting data into a template we can run a Transformer, they are of two types:

  1. OPTIONS:

This transformer replaces the target item with the specified value. These two items are stored in the form of key-value pairs. The key parameter contains the target item while the value paramater consists of new item which will replace the target item. For example:

{
    "type": "OPTIONS",
    "meta" : {
        "options": [
            {
                "key": "Original Text",
                "value": "This is the new text which will be replaced"
            },
            {
                "key": "Jason",
                "value": "Sam"
            }
        ]
    }
}

In the above case, Whenever the text “Original Text” is hit, It will be immediately replaced by the contents of the value parameter "This is the new text which will be replaced". Similarly, when the string “Jason” is found, it will be directly replaced by the string “Sam”.

  1. Cloud Functions:

For a particular key, this transformer can trigger a specific cloud function. Whenever a value is found that matches the key parameter, this Transformer will invoke a cloud function that is specified in the value parameter For example:

{
    path: "data.username",
    type: "options", //enum => options, function
    meta: {
        options: [
            {
                key: 1,
                value: "cloudfunctions.googleapis.com"
            },
            {
                key: 2,
                value: "cloudbuild.googleapis.com"
            }
        ]
    },
    sampleData: {}
}

Here, the integer 1 will trigger the cloud function "cloudfunctions.googleapis.com". Similarly, the integer 2 will trigger another cloud function "cloudbuild.googleapis.com".

Lambda API

This section is under construction

Templater Playground

Templater provides a web based user interface to perform various operations on a template. The playground supports multiple Templating engines like JSTL, Jinja and EJS.

The languages supported for writing templates are Plain text, HTML, Typescript and Javascript. The Playground allows the user to explore and utilize the Templater features easily through its User interface.

Templater playground with an HTML Template

Playground image

Use it

🪜 API Overview

This section is under construction

🔎 Contribution Guidelines

If you are a new developer looking to contribute something to Templater, please take a look and see if there's anything that you'd like to work on in the issue tracker.

The "Good First Issue" label has been added to any tasks that seem like a good way to get started working with the codebase.

Please let us know that you're working on an open issue and let us assign it to you, this ensures that two people aren't working on the same issue, and ensures that all effort is valuable to the project. If an issue hasn't seen activity in a couple of weeks, feel free to ping the assignee to see if they're working on it, or ask a maintainer to reassign the issue to you.

If you can't work on an issue any more, please post another message to let us know.

If it's unclear exactly what needs to be done, or how to do it, please don't hesitate to ask for clarification or help!

Intial Setup (one time)

  1. Fork the Templater repository.

  2. Now let's set up our local repository

    git clone https://github.com/username/templater-docs.git

  3. Next step is to establish an upstream connection with the base repository

    cd templater
git remote add upstream https://github.com/Samarth-HP/templater.git

Making a new pull request

Now if want to make a new change to the code base, we create a new 'feature branch' based off the latest version of the main branch:

git checkout master
git pull upstream master
git checkout -b my-feature-branch 
# make changes here
git push origin HEAD

Dealing with merge conflicts

If changes are made to the Templater repository that conflict with the changes in your pull request in-between creating the feature branch and your changes getting merged into the master repository, it may be necessary to rebase your code:

git checkout master
git pull upstream master
git checkout my-feature-branch # or just "git checkout -" 
git rebase master
# it may be necessary to resolve merge conflicts here
# if you need to update the existing pull request, you should do a 'force' push
git push origin HEAD -f

Dev Setup

Start the database and gql server - 

docker-compose up -d templaterdb gql

Migrate -

prisma migrate dev

Generating docs when you are done - 

npx @compodoc/compodoc -p tsconfig.json -s

Development Environment

Click the button below to start working in a new ready to code development environment

Open in Gitpod

❓FAQs

This section is under construction

Contributors