DOCSEARCHbyAlgolia
Submit Docs

LiquidScript API Reference

website·Indexed 30 days ago

https://jg-rp.github.io/liquidscript/

API documentation for LiquidScript, featuring details on variables such as toLiquid, toHTMLSafeString, and slice, as well as type aliases like TokenKind, TemplateSource, and EnvironmentOptions. Includes references for tags such as TableRowTag, WithTag, and IncludeTag, and documentation on extra tags like extends and block.

Tokens
57.7K
Snippets
479
Records
669
Agent score
74%

What's inside LiquidScript

  1. Overview of Liquid template loaders

    A template loader is responsible for finding template source text given a name or identifier. Loaders are invoked when calling Environment.getTemplate(), Environment.getTemplateSync(), or using tags like {% render %} and {% include %}. Every Liquid environment has exactly one loader; the default is an empty MapLoader, which causes template lookups to throw errors. If a template cannot be found, the system throws a TemplateNotFoundError (no diagnostic info) or a NoSuchTemplateError (includes diagnostic info about the parent template).

  2. Overview of ReadOnlyChainMap

    ReadOnlyChainMap groups multiple records into a single read-only view that implements the Record<string, unknown> interface. It uses a stack-based approach for property resolution: properties are searched from the top of the stack to the bottom, meaning records at the top mask properties in records below them.

    Key behaviors include:

    • Missing Properties: If a property does not exist in the chain, it resolves to [Nothing] (a specific symbol) rather than undefined or a falsy value.
    • Live Views: It does not copy or freeze records; changes to the original records are immediately reflected in the composite view.
    • Nesting: Since ReadOnlyChainMap is itself a Record<string, unknown>, chain maps can be nested within other chain maps.

  4. Access loop metadata using the forloop object

    Inside every for tag block, a forloop object is available to provide metadata about the current iteration.

    PropertyDescriptionType
    nameThe loop variable name and target identifier, separated by a hyphenstring
    lengthThe length of the sequence being iteratedinteger
    indexThe 1-base index of the current iterationinteger
    index0The 0-base index of the current iterationinteger
    rindexThe 1-base index of the current iteration counting from the endinteger
    rindex0The 0-base index of the current iteration counting from the endinteger
    firsttrue if the current iteration is the first, false otherwisebool
    lasttrue if the current iteration is the last, false otherwisebool
    parentloopthe forloop object of an enclosing for loopforloop
    {% for product in collection.products %}
    {% if forloop.first %}
      <b>{{ product.title }}</b> - {{ forloop.index0 }}
    {% else %}
      {{ product.title }} - {{ forloop.index0 }}
    {% endif %}
{% endfor %}

  6. Create an ArgumentError

    The ArgumentError class is used to represent errors occurring with arguments. It extends DetailedLiquidError and requires specific context about the error location and the template being processed.
    const error = new ArgumentError(
  "Error message", 
  span,        // Token object representing the location
  "source code", // The source string of the template
  "templateName" // Name of the template file
);

  7. Use ObjectLoader to load templates from a JavaScript object

    The ObjectLoader is a template loader that uses a JavaScript object (a record of strings) to store template source text. It extends TemplateLoader and is useful for embedding templates directly in code rather than loading them from the file system.
    // Example usage: Initialize ObjectLoader with an object mapping template names to source text
const loader = new ObjectLoader({
  'home': 'Hello {{ user.name }}!',
  'footer': 'Copyright {{ "now" | date: "%Y" }}'
});

  8. Reference the Diagnostic interface properties

    The Diagnostic interface (defined in src/errors.ts) provides metadata about a diagnostic error in liquidscript. It contains the following properties:

    • source: A string representing the source code where the diagnostic occurred.
    • span: A Token object indicating the specific range/location of the diagnostic within the source.
    • templateName: A string identifying the name of the template associated with the diagnostic.

  9. Use ChoiceLoader to implement fallback template loading

    The ChoiceLoader is a template loader that accepts an array of other loaders. It attempts to find a template by iterating through the provided loaders in order. If a template is found by any loader, it is returned; otherwise, if none of the loaders can find the template, a TemplateNotFoundError is thrown. It extends the TemplateLoader class.

  11. Use TemplateInheritanceError for template inheritance issues

    The TemplateInheritanceError class is used to represent errors that occur during template inheritance in liquidscript. It extends DetailedLiquidError and provides specific context about the template causing the error.
    // Constructor signature
new TemplateInheritanceError(message: string, span: Token, source: string, templateName: string): TemplateInheritanceError

  12. Implement the Markup interface for custom tags

    All tags and output statements in LiquidScript template ASTs must implement the Markup interface. While render and renderSync are required for output, several other methods are optional and primarily used to support static analysis (such as variable scope tracking and tree traversal).