View Source V1 (Fullstack) Guide
Note
This guide still is WIP and is temporary! It is likely that many things will be very brief and not explained fully. I am planning to revise the whole documentation in the V1 release.
This guide will help you make a fullstack app (specifically the front-end part) using Tamnoon.
Components
In Tamnoon, the webpage is comprised of several Tamnoon HEEx components. To define a component, make either a module that implements the Tamnoon.Component
behaviour, or a HEEx file (a file ending with .html.heex) in the lib/components directory.
To use a component inside of another component, you can use the following syntax (where component is either a component module or the file name of a HEEx file component):
<%= r.([component]) %>
See Tamnoon.Compiler.render_component_dyn/1
for more info.
Note that EEx blocks inside components are static, meaning that from when the component is rendered on the page, they don't change. To make components that can dynamically change (such as a list of components), you should make a variable that contains the component and set it to the inner HTML of a div (for example). See the following section for more info on how to do that.
Tamnoon HEEx
Tamnoon HEEx is an extension of HEEx that adds support for listening to and triggering Tamnoon events. Any valid HEEx code is valid Tamnoon HEEx code. To listen to an event, assign some HTML attribute (or the inner HTML) of an element to @ and a variable name. That is, if you want a <p> tag to display the value of a variable named "myvar", and be hidden when a variable named "hidep" is true, you would write it as such:
<p hidden=@hidep>@myvar</p>
Any time the server sends a map with a key named "myvar", the inner HTML (meaning script injections ARE a possibility) of the <p> will update to display it. Same goes for "hidep". Note that the attributes set to a Tamnoon variable get removed from it in the final HTML, so you can set default values like so:
<p hidden=@hidep hidden="true">@myvar</p>
To emit events, define an element with an event listener (such as "onclick") and set it to the name of a Tamnoon method you have defined. When that event fires, the server will receive a message containing the following keys: "val" containing the value of the element, and "element" containing the outer HTML of the element. This is how you would define a text input that triggers a method named setval
when it changes:
<input oninput=@setval />
Making the app component
By default, the root layout embeds in itself a component in a file named "app.html.heex". To make your web app, create a components directory inside lib, and write your Tamnoon HEEx code in it. For example:
<p>1 + 1 = <%= 1 + 1 %></p>
<p>@val</p>
<input oninput=@setval />
<%= r.(["mycomponent.html.heex, %{assigned_variable: "Hello, World!"}]) %>
Add a :val
variable and a :setval
Tamnoon method to set the value of val. You should now be able to see val update dynamically as you type.
Make a component named "mycomponent.html.heex" and see how it is shown on the page as well. You can also use the @assigned_variable inside EEx blocks in it!