Skip to content

Latest commit

 

History

History
122 lines (103 loc) · 4.31 KB

README.md

File metadata and controls

122 lines (103 loc) · 4.31 KB
Raw

Rare Earth

Rare Earth is a package for making React tables with ease. This library is browser native so does not require any build step.

Table of Contents

  • Installation
  • Usage

Installation

npm install rare-earth

Usage

Include the source in your html

<script defer type="text/babel" src="{% static 'path/to/rare-earth.js' %}"></script>

In your React functions

App();
function App(){
  const container = document.getElementById('react-container');
  const root = ReactDOM.createRoot(container);

  // Might include classes for styles, like Bootstrap
  const tableClasses = ['table', 'table-dark', 'table-striped'];

  // Example Columns
  const columns = {
    index: false,
    order: [
      'example_column_key_1',
      'example_column_key_2',
      'example_column_key_3'
    ],
    attributes: {
      'example_column_key_1': {
        name: 'Example Column Name 1',
        type: 'string',
        allow_null: true,
      },
      'example_column_key_2': {
        name: 'Example Column Name 2',
        type: 'number',
        allow_null: true,
      },
      'example_column_key_3': {
        name: 'Functional Example Concat',
        type: 'string',
        allow_null: true,
        valueFunc: function(record){
          return ((record['example_column_key_1'] == null) || (record['example_column_key_2'] == null)) ? null : record['example_column_key_1'] + record['example_column_key_2'];
        },
        displayFunc: function(record, value){
          return (<button onClick={(event) => console.log("The value is: " + value)}>{((record['example_column_key_1'] == null) || (record['example_column_key_2'] == null)) ? null : record['example_column_key_1'] + record['example_column_key_2']}</button>);
        }
      }
    }
  };

  // Example Records
  records: [
    {
      'example_column_key_1': 'abc',
      'example_column_key_2': 456
    },
    {
      'example_column_key_1': 'abc',
      'example_column_key_2': 123
    }
  ];

  root.render(
    <RareEarth.Table tableClasses={tableClasses} display={display} columns={columns} records={records}/>
  );
}
export default App;

Props

columns

The columns prop is a javascript object with attributes:

  • index
  • order
  • attributes

The index is currently unused but will be a boolean that represent whether an unamed index column will be prepended to the leftmost column.

The order is an array of strings where each string is unique and must match one of the column keys (defined in the attributes attribute). This is the order (left to right) in which the columns will appear. The user will have the ability to manually swap the order of columns by dragging and dropping the column headers.

The attribues attribute is where the columns are defined. The attribues attribute must be an object of key value pairs where each key is a unique string representing the column identifier and the value is another object with the following attributes:

  • name
  • type
  • allow_null
  • valueFunc (optional)
  • displayFunc (optional)
  • compareFunc (optional)
columns.attributes

The name attribute is a string that is the human readable display name of the column. Future: Allow for functions that return react components as headers - to allow for images etc

The type attribute is the expected type of the values for the column.

The allow_null attribute is a boolean indicating whether the column is allowed to have null values.

The valueFunc attribute is a function that can take a record (a record is an object that represents a row) and returns a value of type type. In the event that valueFunc is not defined (or null), the result will be to use record[column_key]. The value is what will determine sorting ordering. () => ... (record) => ...

The displayFunc attribute is a function that can take a record and a value (the value generated by valueFunc or the default) and returns a react_component/dom_element/string/number etc that will serve as the display in the column cell. In the event that displayFunc is not defined (or null), the result will be the value. () => ... (record) => ... (record, value) => ...

The compareFunc attribute is a function that takes two values from the column (each from differing rows) and compares them in sorting. See Array.sort compareFunction.