hmpl

The main object of the entire module. It includes all the properties and methods that help you work with the server.

This object does not need to be imported. It is assigned to the entire document, so you can immediately use it in your code.

compile

The compile function takes as its first argument a string that represents the extended HTML syntax with the request objects passed to it (more simply, the hmpl syntax), and as its second argument it takes the HMPLCompileOptions options object.

const templateFn = hmpl.compile(
  `{ 
     {
       "src":"/api/test" 
     } 
   }`,
  {
    memo: true,
    autoBody: {
      formData: true,
    },
  }
);

Options

Sets options for all request objects coming from the HMPLTemplateFunction generated by the current compile function.

memo

Specifies memoization for all request objects that match the condition described in the request memo.

{
  memo: true,
}

By default, the value is false.

autoBody

Specifies a value for automatic generation of the request body for all request objects. Can be a Boolean value and an options object of type HMPLAutoBodyOptions. Associated with autoBody for the request object.

{
  autoBody: true,
}

or

{
  autoBody: {
    formData: true;
  }
}

By default, the value is false.

RequestInit

compile returns a template function that takes as arguments an object of type HMPLRequestInit, which initializes a dictionary with request options, or an array of objects of type HMPLIdentificationRequestInit, which is essentially the same dictionary, but with an id for binding to specific requests or the HMPLRequestInitFunction function.

const elementObj = templateFn({
  mode: "cors",
  cache: "no-cache",
  credentials: "same-origin",
  headers: {
    "Content-Type": "text/html",
  },
  redirect: "follow",
  get: (prop, value) => {},
  referrerPolicy: "no-referrer",
  body: JSON.stringify(data),
  signal: new AbortController().signal,
  integrity: "...",
  window: null,
  refferer: "about:client",
});

Identification RequestInit

const elementObj = templateFn([
  {
    id: "1",
    value: {
      mode: "cors",
      cache: "no-cache",
      credentials: "same-origin",
      headers: {
        "Content-Type": "text/html",
      },
      redirect: "follow",
      get: (prop, value) => {},
      referrerPolicy: "no-referrer",
      body: JSON.stringify(data),
    },
  },
]);

It is worth considering that if an array is passed, then if the initId property is not specified, the request will be sent without a options object

The id value of each options identification object is unique. The property value is a string or a number.

The function returns an object that depends on the template string to determine the number of properties. If there are 2 or more request objects in the template string, then the requests property is added, which has the value of an array of objects for each request object. Their properties are copied as if there was one request object in the template string.

const templateFn = hmpl.compile(
  `{ 
     {
       "src":"/api/test" 
     } 
   }`
);
const elementObj = templateFn();

result:

{
  status: 200,
  response: template
}

or

const templateFn = hmpl.compile(
  `<div>
   {
     {
       "src":"/api/test"
     }
   }
   {
     {
       "src":"/api/test"
     }
   }
</div>`
);
const elementObj = templateFn();

result:

{
  response: div,
  requests: [
    {
      status: 200,
      response: template,
    },
    {
      status: 200,
      response: template,
    },
  ],
};

The response that is generated for the element will not contain a template tag, but an array with ChildNode's, because these nodes have already been rendered into the DOM from the template string.

Values are dynamically assigned to the object depending on the server response.

The status changes depending on the server response. But, the most important thing is that it is not assigned several times if it is the same. When working with Proxy or Object.defineProperty or get or something like that, this will not give the object unnecessary updates!

get

The get property takes the value of a function that fires every time one of the properties is updated.

const elementObj = templateFn({
  get: (prop, value, requestObject) => {
    switch (prop) {
      case "response":
        if (!requestObject) console.log(requestObject);
        console.log("Response:");
        console.log(value);
        break;
      case "status":
        console.log("Status:");
        console.log(value);
        break;
    }
  },
});

It is worth noting that the requests property is not called when the value changes, because the function is called when the values ​​in this property change only for array elements. This is a debatable thing, but it may not be necessary to call this function when a specific property of an object is called.

RequestInit function

In order to work with the context, the new version introduced the HMPLRequestInitFunction function. It takes as an argument the HMPLInstanceContext object. Returns HMPLRequestInit.

const elementObj = templateFn(({
  request: { event }
})=>{
  {
      mode: "cors",
      cache: "no-cache",
      credentials: "same-origin",
      headers: {
        "Content-Type": "text/html",
      },
      redirect: "follow",
      get: (prop, value) => {},
      referrerPolicy: "no-referrer",
      body: new FormatData(event.target, event.submitter),
    }
});

Also, the function value can be used as a value for the identification RequestInit.

stringify

This function accepts an object of type HMPLRequestInfo with request data and returns a string request object.

const request = hmpl.stringify({
  src: "/api/test",
});
const templateFn = hmpl.compile(`{${request}}`);

It is based on JSON.stringify.

Concept of context

In hmpl, the concept of context is introduced for transferring data in instances. In itself, it represents a certain environment with data from which you can get, but not yet write, a value.

So far, one context has been introduced - this is the instance context. Its type is HMPLInstanceContext. It includes the request context HMPLRequestContext, which is generated when sending a request to the server.

<div>
  <button id="getHTML">Get HTML!</button>
  {{ "src":"/api/getHTML", method:"POST", after:"click:#getHTML" }}
</div>

/**
 * ctx = {
 *   request: {
 *     event: PointerEvent,
 *   },
 * };
 */

const initFn = (ctx) => {
  const event = ctx.request.event;
  const text = event.target.textContent;
  return {
    body: text,
  };
};
const elementObj = templateFn(initFn);

In this example, thanks to the context, we get an event that is triggered when the button is clicked. This is a very useful feature, because for things like FormData, or value for input, you can now generate a custom HMPLRequestInit.