### JSONX Manual

- Home
- Getting Started
- Using Advanced Props
- External and Custom Components
- Creating React Components and Component Libraries
- JSONX & JXM Spec
- Samples
- Roadmap
- Full API Docs

# Using advanced props

JSONX was created so you can create react elements and components with JSON. Advanced props allow for your components to interact with dynamic data for example:

- referencing stateful properties dynamically
- formatting the output of props
- inserting templates into your JXM Objects

There are five kinds of Advanced Props (Traverse, Evaluation, Format, Display and Utility props):

- 1. Traverse Props - used to traverse data passed into elements or other dynamic/stateful data and assign values as props
  - 1.1 resourceprops/asyncprops - assign dynamic data to props
  - 1.2 windowprops - assign window variables to props
  - 1.3 thisstate - assign stateful data to props
  - 1.4 thiscontext - assign data bound to `this` to props
  - 1.5 thisprops - re-assign prop values
- 2. Evaluation Props - used to create function properties or component properties and assign values as props
  - 2.1 __dangerouslyEvalProps - evaluate strings as props
  - 2.2 __dangerouslyBindEvalProps - evaluate strings to generate props that are functions bound to `this`
  - 2.3 __dangerouslyEvalAllProps - evaluate all props from a string
  - 2.4 __dangerouslyInsertFunctionComponents - use JSONX to generate a function component as a prop
  - 2.5 __dangerouslyInsertClassComponents - use JSONX to generate a class component as a prop
  - 2.6 __dangerouslyInsertComponents - assign React Elements to props using JSONX
  - 2.7 __dangerouslyInsertReactComponents - assign React Elements to props
  - 2.8 __dangerouslyInsertJSONXComponents - assign React Elements to props
  - 2.9 _children - dynamically override the `children` prop
  - 2.10 __functionProps (legacy) - the old way to assign functions to props
  - 2.11 __windowComponents - assign window components to props
  - 2.12 __windowComponentProps - assign props of window components assign to props
  - 2.13 __spreadComponent - component mapped over `__spread` data
  - 2.14 __spread - data used to generate props from an array (e.g. if you have a list)
- 3. Format Props - used to format children props, for example, converting number formats or formatting dates
  - 3.1 ___stringifyChildren - convert `children` prop to string using JSON.stringify
  - 3.2 ___toStringChildren - convert `children` prop to string using .toString()
  - 3.3 ___toNumeral - format number values as strings assigned to `children` prop using Numeral JS
  - 3.4 ___JSDatetoLuxonString - format date values as strings assigned to `children` prop using Luxon
  - 3.5 ___ISOtoLuxonString - format iso date values as strings assigned to `children` prop using Luxon
  - 3.6 ___FromLuxonTimeZone - format date values as strings assigned to `children` prop using Luxon
- 4. Utility Props - used to perform functional tasks like inserting external JXM references (template support), or sharing props across components
  - 4.1 __template - insert jxm objects from external files
  - 4.2 passprops - pass props from parent to children elements
  - 4.3 debug - output computed advanced props and debugging information to the console
  - 4.4 test - output computed advanced props and debugging information as a string
- 5. Display Props - used to decide whether or not to render elements
  - 5.1 comparisonprops - conditionally render elements based on prop values
  - 5.2 comparisonorprops - conditionally render elements flag to use ‘or’ logic instead of ‘and’ logic
- 6. Applied Props - used to modify other jsonx properties
  - 6.1 useformregister - A flag to insert react hook form register on jsonx component
  - 6.2 useremoveprops - remove props from component, usually used with passprops
  - 6.3 useincludeprops - include only defined props, usually used with passprops

## 1. Traverse Props

(resourceprops/asyncprops, windowprops, thisprops, thisstate, thiscontext)

Traverse Props are used to assign props values from different objects. For example, if you wanted to set the alt text of an image tag from the URL of the window. Because JXM objects are derived from JSON it’s impossible to get the dynamic value `window.location.href` and assign it to the alt prop without using advanced props.

    //assume window.location.href = http://example.com

    const JXM = {
      component:'img',
      props:{
        src:'path/to/some/image',
        alt: // ??? http://example.com
      }
    };

Attempting to access `window.location.href` is where traverse props are useful. Conceptually you are traversing the `window` property and assign the `href` property from `window.location` to the `JXM.props.alt` property.

Traversing the `window` object is possible by using the `window props` traverse prop. The other traverse props are:

- resourceprops - traverse asynchronous properties passed to components when using JSONX programmatically
- asyncprops - an alias for `resourceprops`
- windowprops - traverse properties on `window`
- thisprops - traverse properties on `this.props`
- thisstate - traverse properties on `this.state`
- thiscontext - traverse properties on `this`

To properly reference `window.location.href` the following JXM Object would work

    const JXM = {
     component:'img',
     props:{
       src:'path/to/some/image',
     },
     windowprops:{
       alt:['location','href']
     }
    }

Traverse props assign properties to `JXM.props` object by defining what property you want to set on `JXM.props` as the traverse prop property name and passing an array to the property value you want. So for a window’s location (`window.location.href`), the property value is accessed by an array to the href `['location', 'href']` where you omit the transverse object from the array path.

Some sample use cases are:

- Resourceprops transverse an object that is manually passed (usually as a result of an asynchronous fetch all - hence the name asyncprops).
- Thisprops transverses anything bound to `this.props`, a good example would be if you’re storing and passing a user object on `this.props.username`, pulling the username would be where you would use thisprops.
- Thisstate transverses anything bound to `this.state`, for example, if you’re updating the state of a component based on user input from a text field `this.state.value`, pulling the value would be where you would use thisstate.
- Thiscontext transverses anything bound to `this`, a good example is if you’re using JSONX programmatically and you want to bind functionality to the render methods.
- And like the previous example windowprops transverse anything on the global window object, like the current page location `window.location.href`.

    // programmatic example
    import * as jsonx from "jsonx";

    async function main() {
      const response = await fetch("/path/to/userdata");
      const asyncUserData = await response.json();
      /*
      asyncUserData = {
        user: {
          name: 'jsonx',
          description: 'react without javascript',
        },
        stats: {
          logins: 102,
          comments: 3,
        },
        authentication: 'OAuth2',
      };
      */
      const JXM = {
        component: "div",
        props: {
          id: "generatedJSONX",
          className: "jsonx"
        },
        resourceprops: {
          auth: ["authentication"],
          username: ["user", "name"]
        },
        children: [
          {
            component: "p",
            props: {
              style: {
                color: "red",
                fontWeight: "bold"
              }
            },
            asyncprops: {
              title: ["user", "description"]
            },
            children: "hello world"
          }
        ]
      };

      //render something silly
      jsonx.jsonxRender(JXM, asyncUserData);
      /*
      Renders this JXM Object:
      JXM = {
        component: 'div',
        props: {
          id: 'generatedJSONX',
          className:'jsonx',
          auth: 'OAuth2',
          username: 'jsonx',
        },
        children: [
          {
            component: 'p',
            props: {
              style: {
                color: 'red',
                fontWeight:'bold',
              },
              title:'react without javascript',
            },
            children:'hello world',
          },
        ],
      };
      */
    }

    main();

### Example Traverse Props

## 2. Evaluation Props

(__dangerouslyEvalProps, __dangerouslyBindEvalProps, __dangerouslyEvalAllProps, __dangerouslyInsertFunctionComponents, __dangerouslyInsertClassComponents, __dangerouslyInsertComponents, __dangerouslyInsertReactComponents, __dangerouslyInsertJSONXComponents, _children, __functionProps (legacy), __windowComponents , __windowComponentProps, __spreadComponent, __spread)

Evaluation Props are properties that are computed and resolve values onto the `JXM.props` property. They are helpful because, to interact with dynamic data and stateful information, they provide a way to describe declaratively how to assign properties onto the `JXM.props` property.

### _children

The `_children` evaluation property is used to override the value of `JXM.children` and is usually only used when you want to dynamically set the value of the `children` property from an advanced property.

    //current URL: http://example.com
    const JXMWindowLocation = {
      component: "p",
      windowprops: {
        _children: ["location", "href"]
      }
    };
    // computes: { component:'p', children:'http://example.com', }

### __dangerouslyEvalProps, __dangerouslyBindEvalProps ,and __dangerouslyEvalAllProps

The evaluation properties `__dangerouslyEvalProps`, `__dangerouslyBindEvalProps` and `__dangerouslyEvalAllProps` are properties used to evaluate strings and set the value the property value on a JXM Object.

`__dangerouslyEvalAllProps` will evaluate a string as a function and assign the returned value of the function to the `props` property of a JXM object. Note: If passing the value as a string, remember this value has to be an expression, so either a `(({jsonx})=>({}))` or `(function({jsonx}){})`. There is one parameter passed into the function, it’s the current value of the JXM Object on the jsonx property

`__dangerouslyEvalProps` is used to evaluate the string value and assign it to the JXM.props value, the string must be a valid javascript expression (Tip, if evaluating an object remember to wrap it ({some:‘obj’, }) ). If `__dangerouslyEvalProps` is a function, it will assign the value of the function called with one parameter `{jsonx}`.

`__dangerouslyBindEvalProps` is used to assign functions to JXM object props values. This is usually for onClick and onChange functions. Each property of `__dangerouslyBindEvalProps` has to be a function because it attempts to assign the value as a function with `this` bound to it.

These functions exist because there are instances where JSONX is delivered via JSON and JavaScript functions are not valid JSON values. Evaluation props are typically used sparingly when JXM is sent server-side. In practice, there are many ways to pass functions as values (especially if they are bound to JSONX, then you can always reference functions by access properties off of `this` by using `thiscontext`).

### Example Evaluation Props

### __spreadComponent and __spread

The `__spreadComponent` advanced prop is a component that maps over the `JXM.__spread` prop. Typically `__spreadComponent` used to render the same a component mapped to data from an array. Each element of the `JXM.__spread` array is passed into the child `__spreadComponent` as `JXM.__item` . `JXM.__spread` is usually set using a traverse prop to assign the property.

    const JXM = {
      component: 'ul',
      props:{
        __spread: [
          {
            name:'bob smith',
            email:'bob.smith@email.com'
          },
          {
            name:'jane doe',
            email:'jane.doe@email.com'
          },
          {
            name:'billy bob',
            email:'billy.bob@email.com'
          },
        ],
      },
      __spreadComponent:{
        component:'li',
        thisprops:{
          _children:['__item','name']
        }
      },
    };
    /* => {
      component:'ul', children: [
        {
          component:'li', children:'bob smith',
        },
        {
          component:'li', children:'jane doe',
        },
        {
          component:'li', children:'billy bob',
        }
      ]
    };*/

### Example Evaluation Props

### __dangerouslyInsertFunctionComponents, __dangerouslyInsertClassComponents, __dangerouslyInsertComponents, __dangerouslyInsertReactComponents, __dangerouslyInsertJSONXComponents, __windowComponents, __windowComponentProps,

The component evaluation props all assign React Elements to props. This pattern is very common in charting libraries when you need to customize labels. Typically you would assign a custom component to a prop and the component you are using would insert the customized component appropriately.

The most common pattern is a Function component as a prop. Using function components or class components as props require understanding how to create components with JSONX. Read Creating React Components and Component Libraries for more information.

### Example Evaluation Props

### __functionProps (legacy)

The evaluation prop `__functionProps` is another way to assign a function value to a property in `JXM.props`. There are two ways of using `__functionProps`, one way for predefined functions and another way for dynamic functions. Using `__functionProps` may be deprecated in the future.

#### predefined functions (legacy)

`__functionProps` can assign values from functions that exist on `this.props` (e.g. using something like react-router and accessing this.props.reduxRouter.push) or functions that exist on the `window` object (like window.console.log).

Properties are assigned by using the value of the function by access the property as a string, prefixed with “func:”. Function props merge onto `jsonx.props` after evaluating each function string.

    const JXM = {
      component: "button",
      props: {
        name: "test"
      },
      __functionProps: {
        onclick: "func:this.props.onClick", // if there's already a defined onClick Function
        printPage: "func:window.print",
        nav: "func:this.props.reduxRouter.push"
      }
    };

#### inline functions (legacy)

`__functionProps` can also generate functions from a string in a much less elegant way than using `__dangerouslyEvalProps` or `__dangerouslyBindEvalProps`. It’s very cumbersome but you define the string of the function body `JXM.__inline[name-of-func]` and reference the function on `__functionProps` by prefixing the function with `func:inline` (e.g. `JXM.__functionProps[func:inline[name-of-function]]`). You can also use the `__functionargs` advanced props to bind `JXM.prop` properties to parameters of the inline function.

    const JXM = {
      component: "button",
      props: {
        name: "test"
      },
      __functionargs: {
        onClick: ["name"]
      },
      __inline: {
        onClick: ` window.alert("the name of this component from the prop is:" +arguments[0])`
      },
      __functionProps: {
        onClick: "func:inline.onClick"
      }
    };

### Example Evaluation Props __functionProps

## 3. Format Props

(___stringifyChildren, ___toStringChildren, ___toNumeral, ____JSDatetoLuxonString, ___ISOtoLuxonString, ___FromLuxonTimeZone)

Format Props are properties that are used to convert JXM.children values to strings. Format Props are used because the `children` parameter of `React.createElement` can only be a string or an array of React Elements.

### ___stringifyChildren

The `___stringifyChildren` format property converts the `JXM.children` property to a string by using `JSON.stringify`.

    const JXM = {
      component: "div",
      children: { "some-non-string": "data" },
      ___stringifyChildren: true
    }; // => { component:'div', children: '{"some-non-string":"data"}' };

### ___toStringChildren

The `___toStringChildren` format property converts the `JXM.children` property to a string by calling `toString()`.

    const JXM = {
      component: "div",
      children: [1, 2, 3, 4],
      ___toStringChildren: true
    }; // => { component:'div', children: '1,2,3,4' };

### ___toNumeral

The `___toNumeral` format property converts the `JXM.children` property to a string by calling `numeral(JXM.children).format(JXM.___toNumeral)`. See numeral formatting options on numeraljs.com.

    const JXM = {
      component: "div",
      children: 15204.39084,
      ___toNumeral: "0,0.00"
    }; // => { component:'div', children: '15,204.39' };

### ___JSDatetoLuxonString

The `___JSDatetoLuxonString` format property converts the `JXM.children` property to a string by calling `Luxon.DateTime.fromJSDate(JXM.children).toFormat(JXM.___JSDatetoLuxonString)`. See luxon formatting options from the luxon formatting docs.

    const JXM = {
      component: "div",
      children: new Date("2020-03-03"),
      ___JSDatetoLuxonString: "LLL d, yyyy"
    }; // => { component:'div', children: 'Mar 3, 2020' };

### ___ISOtoLuxonString & ___FromLuxonTimeZone

The `___ISOtoLuxonString` format property converts the `JXM.children` property to a string by calling `Luxon.DateTime.fromISO(JXM.children).toFormat(JXM.___ISOtoLuxonString)`. You can set the timezone of the ISO string by using the `___FromLuxonTimeZone` format Prop. See luxon formatting options from the luxon formatting docs.

    const JXM_NY = {
      component: "div",
      children: "2020-03-03T14:30:00.000Z",
      ___ISOtoLuxonString: "ff",
      ___FromLuxonTimeZone: "America/New_York"
    }; // => { component:'div', children: 'Mar 3, 2020, 9:30 AM' };

    const JXM_LA = {
      component: "div",
      children: "2020-03-03T14:30:00.000Z",
      ___ISOtoLuxonString: "ff",
      ___FromLuxonTimeZone: "America/Los_Angeles"
    }; // => { component:'div', children: 'Mar 3, 2020, 6:30 AM' };

### Example Format Props

## 4. Utility Props

(__template, passprops, debug, test)

Utility props generally do not mutate `JXM.props` but are used to augment the expected behavior of JSONX.

### debug

The debug flag outputs the value of the `JXM` object where `JXM.debug === true` and the value of all of the computed advanced props as well.

    const JXM = {
        component: 'div',
        children: 'Debug JXM Data',
        __dangerouslyEvalAllProps:`(
          ()=>({ style:{ color:"blue" } })
        )`,
        debug:true,
    };

    //outputs to console:
    /* {
      jsonx: {
        component: "div",
        children: "Debug JXM Data",
        __dangerouslyEvalAllProps: "(()=>({ style:{ color:"blue" } }))"
        debug: true
      },
      {
        computedProps: {
          style: {color: "blue"}
        }
      }
    }*/

### test

The test flag outputs the value of the `JXM` object where `JXM.test === true` as a string.

    const JXM = {
        component: 'div',
        children: 'Test JXM Data',
        test:true,
    };

    //outputs as a string component:
    /* {
      element: "div",
      children: "Debug JXM Data",
      test: true
    }*/

### passprops

The passprops flag passess the props from the parent `JXM` object to each `JXM.children` JXM Object except for the `JXM.props.style` property.

    const JXM = {
      component: 'div',
      props:{
        type:'radio',
        size:'large',
        extraOne:'ok',
        title:'my radio',
        style:{
          background:'red'
        }
      },
      passprops:true,
      children:[
        {
          component:'input',
        }
      ]
    };

    /* computes:
    const JXM = {
      component: 'div',
      props:{
        type:'radio',
        size:'large',
        extraOne:'ok',
        title:'my radio',
        style:{
          background:'red'
        }
      },
      passprops:true,
      children:[
        {
          component:'input',
          props:{
            type:'radio',
            size:'large',
            extraOne:'ok',
            title:'my radio',
          },
        }
      ]
    };
    */

You can also pass a select number of props by specifying which props to pass

    const JXM = {
      component: 'div',
      props:{
        type:'radio',
        size:'large',
        title:'my radio',
        style:{
          background:'red'
        }
      },
      passprops:['type','title'],
      children:[
        {
          component:'input',
        }
      ]
    };

    /* computes:
    const JXM = {
      component: 'div',
      props:{
        type:'radio',
        size:'large',
        extraOne:'ok',
        title:'my radio',
        style:{
          background:'red'
        }
      },
      passprops:['type','title'],
      children:[
        {
          component:'input',
          props:{
            type:'radio',
            title:'my radio',
          },
        }
      ]
    };
    */

### ___template

The `___template` advanced prop (should really only be used server-side but works in the browser too) will load JXM objects from an external file (or URL client side - note in the browser this is a synchronous request).

    const JXM = {
      component:'div',
      ___template:'path/to/some/jxm/json/file'
    }
    // path/to/some/jxm/json/file = { component: "section", children: "from external template"}
    /* computes:
    {
      component:'div',
      children:[{ component: "section", children: "from external template"}]
    }
    */

### Example Utility Props

## 5. Display Props

(comparisonprops, comparisonorprops)

Display Props are properties that are used to determine if a React Element rendered from a JXM Object should be rendered. Display props enable conditional logic based on the value of props to determine if an element should be shown.

### comparisonprops and comparisonorprops

The display prop `comparisionprops` is used to conditionally show elements if all of the comparisons are truthy. `comparisonprops` works by comparing an array of left and right side values, if they are all true, the component is rendered. If `JXM.comparisonorprops` is set to true then only one condition needs to be true to render the component.

The comparison values can either be literal values or the value can be a reference to any `JXM.props` value. References to values in `JXM.props` are accessed in the same way you would use traverse props, where the prop being traversed is `JXM.props`.

    //and conditions
    jsonx = {
      component: "div",
      children: "evals to false, so it will not render",
      comparisonprops: [
        {
          left: ["bigNum"],
          operation: "lte",
          right: ["smallNum"]
        }, // false (10000 <= 100)
        {
          left: ["smallNum"],
          operation: "<=",
          right: ["bigNum"]
        } // true (100 <= 10000)
      ] // false and true === false, so it won't render
    };
    //or conditions
    jsonx = {
      component: "div",
      children: "evals to true, so this will render",
      comparisonorprops: true,
      comparisonprops: [
        {
          left: ["truthy"],
          operation: "eq",
          right: ["falsey"]
        }, // = false
        {
          left: ["smallNum"],
          operation: "eq",
          right: ["smallNum"]
        } // true
      ] // false or true === true, so render element
    };

    // All comparison operations
    switch (opscompares.operation) {
      case "eq":
      case "==":
        return opscompares.left == opscompares.right;
      case "dneq":
      case "!=":
      case "!":
        return opscompares.left !== opscompares.right;
      case "dnseq":
      case "!==":
        return opscompares.left !== opscompares.right;
      case "seq":
      case "===":
        return opscompares.left === opscompares.right;
      case "lt":
      case "<":
        return opscompares.left < opscompares.right;
      case "lte":
      case "<=":
        return opscompares.left <= opscompares.right;
      case "gt":
      case ">":
        return opscompares.left > opscompares.right;
      case "gte":
      case ">=":
        return opscompares.left >= opscompares.right;
      case "dne":
      case "undefined":
      case "null":
        return opscompares.left === undefined || opscompares.left === null;
      case "!null":
      case "!undefined":
      case "exists":
      default:
        //'exists'
        return opscompares.left !== undefined && opscompares.left !== null;
    }

### Example Display Props

## 6. applied Props

(useformregister, useremoveprops, useincludeprops)

Applied Props are properties that are helper properties that are used modify other jsonx properties.

### useformregister

The applied prop `useformregister` is a prop that passes a React Hook Form register to a component. It is a short cut for having to added the reference to the form reference manually.

    jsonx = {
      component: "input",
      props:{
        name:'firstName',
      },
      useformregister: true,
    };

    // is equivalent to
    jsonx = {
      component: "input",
      props:{
        name:'firstName',
      },
      thiscontext:{
        ref: ['reactHookForm', 'register']
      },
    };

### useremoveprops

The applied prop `useremoveprops` is a prop that removes a list of props from the JXM Object. It is usually used in conjunction with passprops when you want to remove extra passed props.

    jsonx = {
      component: "input",
      props:{
        name:'firstName',
        removeThis:true,
        extraProp:'remove me',
      },
      useremoveprops: ['removeThis','extraProp'],
    };

    // is equivalent to
    jsonx = {
      component: "input",
      props:{
        name:'firstName',
      },
    };

### useincludeprops

The applied prop `useincludeprops` is a prop that removes all props from the JXM Object except for a list specified props. It is usually used in conjunction with passprops when you want to remove extra passed props.

    jsonx = {
      component: "input",
      props:{
        name:'firstName',
        removeThis:true,
        extraProp:'remove me',
        keepMe:'just this prop',
      },
      useincludeprops: ['keepMe'],
    };

    // is equivalent to
    jsonx = {
      component: "input",
      props:{
        keepMe:'just this prop',
      },
    };

## Next: External and Custom Components

### JSONX Manual

- Home
- Getting Started
- Using Advanced Props
- External and Custom Components
- Creating React Components and Component Libraries
- JSONX & JXM Spec
- Samples
- Roadmap
- Full API Docs