React
In this guide, you learn how to integrate and use AgileTs in a React Project. I promise you, it's pretty easy ๐. We recommend proceeding from top to bottom because some sections build on each other.
#
๐ฝ InstallationTo properly use AgileTs in a React Application, we have to install two packages. On the one side, the core
package and an AgileTs Integration for React on the other site.
@agile-ts/core
#
๐ - npm
- Yarn
Let's begin with the core
package, which acts as the brain of AgileTs
and manages all our States,
Collections, ..
It is the only essential package for using AgileTs.
@agile-ts/react
#
๐ - npm
- Yarn
Besides the core
package, we install a React Integration.
It is like an interface to React and provides useful Functions
like useAgile
to bind our States to a React Component.
create-react-app
#
๐ - Javascript
- Typescript
In case you start your project from scratch, feel free to use the react-template
for AgileTs. This template will automatically
generate a fully functional react-app with AgileTs installed.
#
๐ก Create first State#
โ What is a StateStates hold information we need to remember at a later point in time.
Such information might be the current theme or the logged-in user.
In AgileTs a State gets created with the help
of an instantiated Agile Instance often called App
.
After a successful instantiation of our State, we can dynamically and easily manipulate its value.
#
๐ด Live ExampleIn the following snippet we will create our first AgileTs State which has the initial
value Hello World
. Next to the Hello World
output, we have provided a button that incrementally raises a number and attaches
it to the Hello World
State. In case you have any further questions, take a look into the Important Code Snippets Section, or join our awesome Community Discord
Hello World
To find out more about States, checkout our State docs.
#
๐ป Important Code SnippetsBefore we can create any State, we have to instantiate an AgileTs Instance. Such an Instance holds and manages all our States, Collections, .. Be aware that you should avoid having multiple Agile Instances in one application!
With the help of our previously instantiate AgileTs Instance, we can create our first State. Our State got the initial value 'Hello World'
, which we passed as first property.
useAgile
is React Hook to bind our State to a specific React
Component. This binding is necessary to rerender the Component whenever our State mutates. For instance, if its value changes.
useAgile
returns the current output
of the State, so in our case 'Hello World'. Be aware that React Hooks can only be used in React Components!
For class component users we have created the AgileHOC.
To bring some life into our small application, we update the State with the help of the set
function and pass our desired new
value as first property.
#
๐ก Create first Collection#
โ What is a CollectionA Collection is like an array of object-shaped data following the same pattern. A use case might be to store a flexible todo list or the messages of a chat. It gets created with the help of an
instantiated Agile Instance often called App
.
After a successful instantiation of our Collection, we can dynamically and easily manipulate its value.
Be aware that each collected data has to be in object shape and needs a unique primary key like an id
. Each collected data is automatically
transformed into a new State, representing the value it was collected as. A so-called Item has the same
functionalities as a normal State.
Besides Items, a Collection consists primarily of Groups, which allows us to split the Collection into multiple individual sections without
losing redundant behavior. Each Item will be added to the default
Group, which represents the default Collection pattern. But a Group doesn't store the Item itself. It only holds the primary keys of the data it represents.
#
๐ด Live ExampleIn the code snippet below, we create a basic Todo Collection. To
feet it with new todos, we have a text input and an add
button in the UI layer.
Next to each singe todo, you can find a remove
button,
which removes the todo from our Collection. In case you have any further questions,
take a look into the Important Code Snippets Section, or join our awesome Community Discord
Simple TODOS
To find out more about Collections, checkout our Collection docs.
#
๐ป Important Code SnippetsTo create our first Collection, we need the previously instantiated Instance of AgileTs. Then we can bring our
first Collection to life, which got the initial Item {id: 1, name: "Clean Bathroom"}
. Besides the creation, we store the
Collection in the localStorage
with the help of the persist
function.
Here we use the useAgile
React Hook to bind our Collection to the
React Component. In the case of a Collection, it returns the default
Group value in array shape.
To add new Data to our Collection, we use the collect
function.
In our case the currentInput with a random Id as primaryKey.
In case we have done a todo, of course, we want to remove it.
The remove
function helps us to reach this goal.
The everywhere()
tag means that the Item will be removed from the whole Collection.
#
๐ MoreAgileTs got your attention, and you want to learn more. Don't hesitate to check out the docs below.