Skip to main content

Local API Overview

Unlock the full potential of your web development with our Local API. Designed for developers looking to create highly customizable and dynamic web experiences, our platform allows you to load content directly via JavaScript and tailor it to your specific needs.

Ideal for Developers

The Local API is best suited for developers with a solid understanding of JavaScript.

How It Works​

Our platform includes a built-in function that checks for a header named x-local-api. If this header is present, the platform will return data as JSON instead of rendering HTML. This means that all variables for the selected page will be returned in JSON format, allowing for dynamic content manipulation.

Pre-Built JavaScript Functions

We provide pre-built JavaScript functions that simplify fetching and saving data dynamically. We recommend utilizing these functions for optimal performance and ease of use.

Fetching Data​

Important Restrictions​

danger

Cross-Site Fetching: You cannot fetch data from other websites using our platform. Fetching is limited to the website you are currently on, and cross-fetching between different sites is not permitted.

Including the Required JavaScript File​

danger

Your template must include the following script to use the Local API:

<script src="{{ setting.cdn.default_assets_url }}/js/local-api-v2.js?v={{ "now"|date("c") }}"></script>

This script should be placed in your base.html file, either within the <head> tag or just before {% block javascript %}{% endblock %}.

Example: Fetching Data​

Fetching data using our local-api-v2.js is straightforward. Below is an example using our Counter-Strike 2 leaderboards integration. It's recommended not to place this in base.html but in a more specific file, such as home.html.

{% block javascript %}
<script>
    const bansPromise = localApi('/punishments');
   if (typeof bansPromise !== 'undefined' && bansPromise instanceof Promise) {
   bansPromise
       .then(banInfo => {
           
       })
       .catch(error => {
           console.error("Punishments Error:", error);
       });
   }
</script>
{% endblock %}
Example Information

This example demonstrates the basic usage of our Local API. You can use it to fetch data from any page on your site.

Header Requirement for JSON Response​

If you choose not to use our pre-built local-api-v2.js or ajax-form-handler.js, you must ensure that the x-local-api header is set to true in your request. This header is crucial for receiving a JSON response from the Local API.

Important Header Note

While it is possible to manually set the x-local-api header, we strongly recommend using our local-api-v2.js and ajax-form-handler.js scripts. These scripts simplify the process of working with the Local API and handle many of the complexities for you.

By using local-api-v2.js and ajax-form-handler.js, you can ensure that your requests are properly formatted and that the responses are handled efficiently. However, if you choose to handle requests manually, always remember to include the x-local-api header to receive the correct response format.

Handling HTML Response​

HTML Response Handling

If you need to return HTML instead of JSON, simplify the page by removing unnecessary blocks and use the response as HTML. You can then place it wherever you need in your document.

Saving Data​

Our platform also supports saving form data dynamically through the Local API. Follow these steps to ensure proper functionality:

Steps to Save Data​

  1. Include the Required JavaScript File:

    Ensure your base.html includes the following script:

     <script src="{{ setting.cdn.default_assets_url }}/js/ajax-form-handler.js"></script>

  2. Form Requirements:

    • Your <form> element must have an id.
    • The save button should have:
      • The class ajax-handler.
      • The attribute data-form-id="your-form-id".

Example: Using Pre-Built Twig Macro​

You can use our pre-built Twig macro to display the save button. First, import the macro at the top of your file:

{% from "includes/macros.html" import displaySaveButtonajaxFormHandler as displaySaveButtonajaxFormHandler %}

Then, use the macro like this:

{{ displaySaveButtonajaxFormHandler('basic', 'Save Button Text') }}
  • First argument: The id of the form.
  • Second argument: The text for the button.

Example: Custom Button Implementation​

If you prefer a custom button, ensure it has the following attributes:

  1. Class: ajax-handler
  2. Data Attribute: data-form-id set to the corresponding form id.

Example:

{{ csrf_token | raw }}
<button class="btn btn-block btn-secondary ajax-handler"
    data-form-id="basic"
    type="button">
    <i class="fa fa-save"></i> 
    {{ translate("Save") }}
</button>

Using the Ajax Form Handler Object​

The ajaxFormHandler JavaScript object provides flexibility in handling form submissions. Here's an example of using it:

    ajaxFormHandler.onSuccess(function (response, buttonData) {
        if (ajaxFormHandler.getCurrentId() !== 'basic') return;
        // Process the response as needed.
    });

For more details, view the full ajax-form-handler.js on our GitHub page:
Ajax Form Handler.

Caution​

Overuse Warning

Using the Local API extensively without proper management can overload your website, potentially leading to downtime. Ensure you understand the implications before implementing it.

jQuery Usage​

Our platform uses jQuery, and it's perfectly acceptable to use it alongside built-in JavaScript functions like fetch. Both methods are supported and can be used interchangeably.

Local API Not Working?​

Known Limitations​

info

Some pages may not yet support the Local API. We are continually updating our platform to include this feature across more pages. If you encounter a page that does not support the Local API, please contact us.

Pages Without Local API Support​

danger

Certain pages, such as the Payment Process, may never include Local API support due to their critical nature.