Positional Markup Language - Simple markup for describing the position of components within a string.
npm install poml``html`
This is <0>PoML.
It stands for <0><1>Positional <1>Markup <1>Language.
Use it to <2>interpolate components or tags into a string and back.
Install
React
For React, just install the poml-react module:
`
yarn add poml-react
Core
For the core package, just install poml
`
yarn add poml
Usage
`typescript`
console.log(parsePOML('Hello <0>world!'))
// [
// { type: 'TextNode', value: 'Hello ' },
// {
// type: 'ComponentNode',
// position: 0,
// children: [{ type: 'TextNode', value: 'world!' }],
// },
// ]
React
`tsx`
// prettier-ignore
Components={[
({ children }) => {children}
,
({ children }) => {children}
]}
/>
- API
- Motivation
- Specification
This module is split up into the core parser logic and individual implementations like React.
#### API - parsePOML(markup: string): MarkupNode[]
Parses a POML string returning the AST.
Returns: MarkupNode[]
`typescript
export type TextNode = {
type: 'TextNode'
id: string
value: string
}
export type ComponentNode = {
type: 'ComponentNode'
id: string
position: number
children: MarkupNode[]
}
export type MarkupNode = TextNode | ComponentNode
`
_For examples, checkout src/poml.test.ts_
#### API -
The component memoizes and parses of source input and applies your components to the AST. You must supply the source PoML string. If your PoML contains Component tags (which it should otherwise its just a regular ol' string), then you should provide an array of components via the Components props. The component at index 0 will interpolate into tag <0> from the string.
Example
`tsx
Components={[
({ children }) => {children}
{/ Result /}
<>
Hello, world!
This is cool! great!
`
_For more examples, checkout src/poml-react.test.ts_
String externalization is the process of taking hard-coded strings out of your code and into some other repository (whether that be a CMS or a JSON file). It's typically a pre-requisite of internationalizing a piece of software. A common mistake during this process is known as _string concatenation_.
Suppose you have some HTML that looks like this:
`html`
Clone this repository
When externalizing this string, one might be tempted pull this out into two strings:
- clone_this: 'Clone this'
-
And then recombine them in the template:
`handlebars`
{{t "clone_this"}} {{t "repository"}}
This is effectively concatenating _three strings together!_ First the clone_this string, then a single space, then the repository string. Anybody looking at the two externalized strings in isolation will not fully understand the context. "Clone this". Clone this what? Clone this sheep? Spider? Depending on the context, the translated content may very flip the ordering of the words around. Or maybe in some regions a phrase like "Clone this repository" has been colloquially known as a single word and there you are adding on a bunch of nonsense in their language.
One way to get around this is to directly embed the HTML into your string and pass that along for translation. But what if you need to change the template? Further, we're mixing concerns. Translated text and functional markup.
A better solution is to interpolate your markup into an externalized string.
`
Clone this <0>respository
This way, the translator still gets the full context and the actual implemtnation still lives in your source code. Granted, this does create an even larger dependency on the externalized string and the call-site.
_NOTE: This section is not yet complete._