placecode.json

The placecode.json file is the cornerstone of placecode, serving as the central configuration file for creating dynamic templates. This file contains all the necessary information about the dynamic features and their respective categories, guiding the template generation process. To ensure proper functionality, the placecode.json file must always be placed in the root directory of your project.

This file is a vital component of placecode, and its correct placement enables seamless interaction with the CLI tool and the placecode.io web app.

Default placecode.json

Upon initialization, placecode creates a default placecode.json file with sample data to simplify the template creation process. Below is an example of the default placecode.json file:

[
  {
    label: "category1",
    description: "Description of category 1",
    required: true,
    features: [
      {
        label: "feature1",
        description: "Description of feature 1",
        depend_features: [],
        depend_categories: ["category2"],
        enabled: false,
      },
      {
        label: "feature2",
        description: "Description of feature 2",
        depend_features: [],
        depend_categories: [],
        enabled: true,
      },
      {
        label: "feature3",
        description: "Description of feature 3",
        depend_features: [],
        depend_categories: [],
        enabled: true,
      },
    ],
  },
  {
    label: "category2",
    description: "Description of category 2",
    multi: true,
    features: [
      {
        label: "feature4",
        description: "Description of feature 4",
        depend_features: [],
        depend_categories: [],
        enabled: true,
      },
      {
        label: "feature5",
        description: "Description of feature 5",
        depend_features: [],
        depend_categories: [],
        enabled: true,
      },
    ],
  },
]

Overview of placecode.json

The placecode.json file is an array of objects, with each object representing a category. Categories are used to group related features, such as frontend frameworks or libraries.

As an example: Python, Java, Golang can be categorized into backend languages

category

Within each category object, the following attributes are defined:

label

A unique identifier for the category. This label is essential for referencing the category in dynamic templates and must not contain special characters except for '_' and '-'. Categories are only used for categorizing features and will not include in the template generation process.

description

A description providing information about the category or its features, helping users understand the purpose of the category.

required

This is optional. A boolean value (true or false) indicating whether the category is required when generating a template from this dynamic template. If false, users can skip selecting features from this category, and no features from this category will be included in the final generated template.

multi

This is optional. A boolean value (true or false) indicating whether the category allows multiple features to be selected. If true, users can select multiple features from this category, and all selected features will be included in the final generated template. If false or property not included, users can only select one feature from this category, and only the selected feature will be included in the final generated template.

features

An array containing objects representing the individual features belonging to the category.

Feature

Each feature object contains the following attributes:

label

A unique identifier for the feature, similar to the category label. This label is crucial for annotating code blocks in your project files and folders, indicating which code belongs to specific features.

description

A brief description of the feature, providing users with context and details about what the feature.

depend_features

An array of strings listing all other features that this feature depends on. A user can only select this feature if all the features listed in depend_features are also selected during the template generation process.

depend_categories

An array of strings listing all other categories that this feature depends on. A user can only select this feature if at least one feature from each category listed in depend_categories is also selected during the template generation process.

enabled

A boolean value (true or false) indicating whether the feature should be enabled (selected) in the template creation process. Users can toggle the selection of this feature based on their requirements. This is to test the features manually with placecode run.

Validating placecode.json

Creating a valid placecode.json file is essential to ensure seamless template generation and compatibility with placecode.io. To help users validate their placecode.json file, we provide a validator tool on placecode.io. Users can paste their placecode.json contents into the validator, which will check adherence to the following rules:

Validation Rules

1. The schema (structure) of the JSON file should precisely match the default schema.

2. All category and feature labels must be unique and non-empty, with no special characters except for '_' and '-'.

3. In the depend_features array, a feature cannot depend on another feature within the same category. Multiple dependencies from different categories are allowed, but only one feature from a specific category.

4. The labels used in depend_features and depend_categories must correspond to valid category and feature labels that exist in the placecode.json file.

The validator tool will identify any mistakes or invalid configurations, helping creators resolve issues and ensure compliance with the placecode.json standards.

Using placecode.json

The placecode.json file is instrumental in communicating information about your template to placecode.io for generating dynamic templates. When creating comment markers in your project files and folders, ensure you use the same feature labels as defined in placecode.json to indicate which code blocks belong to specific features.

By following the guidelines and rules set by placecode.json, you can harness the full potential of placecode to create powerful and customizable dynamic templates for your projects.