#S:EXTERNAL=rust=hello_me.rs

Hello Me

Welcome back to another tutorial in the Core Concepts series.

The app we have built so far returns a constant value however for more complex applications it would be useful to be able to store some data.
Today you will learn how to do this by adding an entry type to your zome. Remember an entry is a piece of data in your source chain that has been validated.

We will add the following:

Add a person entry type that stores information about a person.
Expose the public function create_person for your UI to create and store a person entry.
Expose a public function retrieve_person for your UI to retrieve a person entry.
Add the UI components to interact with these functions.

This tutorial builds on the previous tutorial so go back and complete that if you haven't already.

Test first

Start by writing a test so it's easy to see when your app is working:

Open up cc_tuts/test/index.js.

This is how we left the testing scenario in the Hello Test tutorial:

#S:MODE=test #S:EXTERNAL=javascript=hello_me.js=test #S:SKIP

diorama.registerScenario("Test hello holo", async (s, t, { alice }) => {
  // Make a call to the `hello_holo` Zome function
  // passing no arguments.
  const result = await alice.call("hello", "hello_holo", {});
  // Make sure the result is ok.
  t.ok(result.Ok);

  // Check that the result matches what you expected.
  t.deepEqual(result, { Ok: 'Hello Holo' })
  
  // <---- Put your new tests here
})

#S:INCLUDE,HIDE

diorama.registerScenario("Test hello holo", async (s, t, { alice }) => {
  // Make a call to the `hello_holo` Zome function
  // passing no arguments.
  const result = await alice.call("hello", "hello_holo", {});
  // Make sure the result is ok.
  t.ok(result.Ok);

  // Check that the result matches what you expected.
  t.deepEqual(result, { Ok: 'Hello Holo' })

The new tests go below t.deepEqual(result, { Ok: 'Hello Holo' }).

The following test will create an entry with the name "Alice", retrieve the same entry and check that it has the name "Alice".

Add a call to the create_person function with a person whose name is Alice:

  const create_result = await alice.call("hello", "create_person", {"person": { "name" : "Alice" }});

Check that the result of the call is Ok:

  t.ok(create_result.Ok);

Add a call to the retrieve_person function with the address from the last call:

  const retrieve_result = await alice.call("hello", "retrieve_person", {"address": create_result.Ok});

Check that this call is Ok as well:

  t.ok(retrieve_result.Ok);

This is the actual result we want at the end of the test. Check that the entry at the address is indeed named Alice:

  t.deepEqual(retrieve_result, { Ok: {"name": "Alice"} })

#S:HIDE


})

diorama.run()

Running the test

Your test should now look like this:

#S:CHECK=javascript=test

Obviously these tests will fail right now. Can you guess what the first failure will be? Let's have a look.

Enter the nix-shell if you don't have it open already:

nix-shell https://holochain.love

Run the test:

!!! note "Run in nix-shell" bash hc test

!!! failure "The test fails on the create_person function because it doesn't exist yet:" "Holochain Instance Error: Zome function 'create_person' not found in Zome 'hello'"

Note that this test might actually get stuck because we haven't put in the required functions yet. Press ctrl-c to exit a stuck test.

Add the entry

Open up your zomes/hello/code/src/lib.rs file.
To add an entry into your source chain start by telling Holochain what kinds of entry exist.
First we'll create a struct to define the shape of the data.

In a moment we will add a Person struct, but this is where to put it:

#S:SKIP

// <---- Add the person struct here.

#[zome]
mod hello_zome {

Add the following lines.

Allow this struct to be easily converted to and from JSON:

#S:INCLUDE

#[derive(Serialize, Deserialize, Debug, DefaultJson, Clone)]

Represent a person as a struct:

pub struct Person {

Represent their name as a String:

    name: String,
}

Look for the following lines inside the hello_zome mod.

#[zome]
mod hello_zome {

#S:HIDE

    #[init]
    fn init() {
        Ok(())
    }

    #[validate_agent]
    pub fn validate_agent(validation_data: EntryValidationData<AgentId>) {
        Ok(())
    }

  /* --- Lines omitted -- */
  #[zome_fn("hc_public")]
  fn hello_holo() -> ZomeApiResult<String> {
      Ok("Hello Holo".into())
  }

  // <---- Add the following lines here.

Add the person_entry_def function, which tells Holochain about the person entry type:

    #[entry_def]
    fn person_entry_def() -> ValidatingEntryType {

Add the entry! macro that lets you easily create a ValidatingEntryType:

        entry!(

Give it the same name as the Person struct, just to be consistent. Entry types are usually in lowercase.

Add the name and description of the entry:

            name: "person",
            description: "Person to say hello to",

Entries of this type are just for this agent's eyes only, so set the entry sharing to private:

            sharing: Sharing::Private,

Add the validation_package function that says what is needed to validate this entry:

            validation_package: || {
                hdk::ValidationPackageDefinition::Entry
            },

Add the validation function that validates this entry.

It returns that this entry is always Ok as long as it fits the shape of the Person struct:

            validation: | _validation_data: hdk::EntryValidationData<Person>| {
                Ok(())
            }
        )
    }

Now you can create actual person entries and store them on your source chain.

A note on validation: Validation is very important. It is the "rules of the game" for your Holochain app. It is meaningful to emphasize that although we are returning Ok(()) that we are still validating that the data type checks as a Person with a name property containing a String. Essentially this rule says the person entry must be in this format.

Add some `use` statements

In the above code we have used a few types and macros that are not mentioned anywhere else. So the Rust compiler doesn't know where to find them yet.

Add the following use statements:

#![feature(proc_macro_hygiene)]
+#[macro_use]
extern crate hdk;
extern crate hdk_proc_macros;
extern crate serde;
#[macro_use]
extern crate serde_derive;
extern crate serde_json;
+#[macro_use]
extern crate holochain_json_derive;

use hdk::{
+    entry_definition::ValidatingEntryType,
    error::ZomeApiResult,
};

+use hdk::holochain_core_types::{
+    entry::Entry,
+    dna::entry_types::Sharing,
+};
+
+use hdk::holochain_json_api::{
+    json::JsonString,
+    error::JsonError,
+};
+
+  use hdk::holochain_persistence_api::{
+    cas::content::Address
+};

use hdk_proc_macros::zome;

#S:EXTRA

#S:CHECK=rust

Create a person

Now you need a way for your UI to actually create a person entry. Holochain has a concept called hc_public which is a way of telling the runtime make this function available to call from outside this zome.

Add the following lines below the previous person_entry_def function.

Add a public function that takes a Person and returns a result with an Address:

#S:INCLUDE

    #[zome_fn("hc_public")]
    pub fn create_person(person: Person) -> ZomeApiResult<Address> {

Create an entry from the person argument:

        let entry = Entry::App("person".into(), person.into());

Commit the entry to your local source chain:

        let address = hdk::commit_entry(&entry)?;

Return the Ok result with the new person entry's address:

        Ok(address)
    }

Compile

#S:EXTRA

#S:CHECK=rust

Check for compile errors again:

!!! note "Run in nix-shell" bash hc package

Retrieve person

Lastly you need a way for your UI to get a person entry back from the source chain.

Add the following lines below the create_person function.

Add a public retrieve_person function that takes an Address and returns a Person:

    #[zome_fn("hc_public")]
    fn retrieve_person(address: Address) -> ZomeApiResult<Person> {

Get the entry from your local storage, asking for it by address, and convert it to a Person type:

        hdk::utils::get_as_type(address)
    }

#S:HIDE,INCLUDE

In Rust the last line is always returned. You do not need to explicitly say return. Just leave off the ;.

Test

#S:CHECK=rust

Instead of directly compiling, you can run the test you wrote at the start (the test always compiles before it runs):

!!! note "Run in nix-shell" bash hc test

!!! success "If everything went smoothly you will see:" ```bash # tests 5 # pass 5

# ok
```

UI

Now that the backend is working you can modify the UI to interact with zome functions you created. First let's do some housekeeping and move the JavaScript from the previous tutorial into its own file.

Go to the GUI project folder that you created in the Hello GUI tutorial:

cd holochain/coreconcepts/gui

Create a new hello.js file, open it in your favorite editor, and open the index.html alongside it.

Move the everything inside the <script> tag into the hello.js:

#S:SKIP,MODE=gui

--- index.html
<script type="text/javascript">
-    var holochain_connection = holochainclient.connect({ url: "ws://localhost:3401"});
-    
-    function hello() {
-      holochain_connection.then(({callZome, close}) => {
-        callZome('test-instance', 'hello', 'hello_holo')({"args": {} }).then((result) => update_span(result))
-      })
-    }
-    function show_output(result) {
-      var span = document.getElementById('output');
-      var output = JSON.parse(result);
-      span.textContent = " " + output.Ok;
-    }
</script>

+++ hello.js
+var holochain_connection = holochainclient.connect({ url: "ws://localhost:3401"});
+
+function hello() {
+  holochain_connection.then(({callZome, close}) => {
+    callZome('test-instance', 'hello', 'hello_holo')({"args": {} }).then((result) => update_span(result))
+  })
+}
+
+function show_output(result) {
+  var span = document.getElementById('output');
+  var output = JSON.parse(result);
+  span.textContent = " " + output.Ok;
+}

Add the src attribute to the <script> tag:

<script type="text/javascript" src="hello.js"></script>

Create person UI widget

In your index.html start by adding the HTML elements to create a person.

Look for the previous 'say hello' elements.

    <button onclick="hello()" type="button">Say Hello</button>
    <div>Response:</span><span id="output"></div>
    <!-- Put the following lines here -->

Below them, give the section a heading:

    <h3>Create a person</h3>

Add a text box so the user can enter their name:

    <input type="text" id="name" placeholder="Enter your name :)">

Add a button that calls a (yet to be written) JavaScript function called create_person:

    <button onclick="create_person()" type="button">Submit Name</button>

Add a span with the id address_output so you can render the result of this call:

    <div>Address: <span id="address_output"></span></div>

??? question "Check your index.html:" ```html <!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="utf-8" />

    <title>Hello GUI</title>
    <meta name="description" content="GUI for a Holochain app" />
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/gh/kognise/water.css@latest/dist/dark.min.css"
    />
  </head>

  <body>
    <button onclick="hello()" type="button">Say Hello</button>
    <div>Response: <span id="output"></span></div>
    <h3>Create a person</h3>
    <input type="text" id="name" placeholder="Enter your name :)" />
    <button onclick="create_person()" type="button">Submit Name</button>
    <div>Address: <span id="address_output"></span></div>
    <script
      type="text/javascript"
      src="hc-web-client/hc-web-client-0.5.1.browser.min.js"
    ></script>
    <script type="text/javascript" src="hello.js"></script>
  </body>
</html>
```

Switch to your `hello.js` file

Let's write the create_person function that will call your zome.

Add the create_person function:

function create_person() {

Get the text box by its ID name and save the current text value into the name variable:

  const name = document.getElementById('name').value;

Wait for the connection and then make a zome call:

  holochain_connection.then(({callZome, close}) => {

Call create_person in your hello zome and pass in the name variable as part of a person structure, then write the result to the console:

    callZome('test-instance', 'hello', 'create_person')({
      person: {name: name},
    }).then(result => console.log(result));
  });
}

??? question "Check your hello.js:" ```javascript // Connect var holochain_connection = holochainclient.connect({ url: 'ws://localhost:3401', });

// Render functions
function show_output(result) {
  var span = document.getElementById('output');
  var output = JSON.parse(result);
  span.textContent = ' ' + output.Ok;
}

// Zome calls

function hello() {
  holochain_connection.then(({callZome, close}) => {
    callZome('test-instance', 'hello', 'hello_holo')({args: {}}).then(result =>
      show_output(result),
    );
  });
}

function create_person() {
  const name = document.getElementById('name').value;
  holochain_connection.then(({callZome, close}) => {
    callZome('test-instance', 'hello', 'create_person')({
      person: {name: name},
    }).then(result => console.log(result));
  });
}
```

Run the server and open a browser

Go ahead and test your first call.

Open a new terminal window and enter the nix-shell:

cd holochain/coreconcepts/gui
nix-shell https://holochain.love

Run the server:

!!! note "Run in nix-shell" bash python -m SimpleHTTPServer

In your other terminal window (the one with your backend code) package and run your zome:

!!! note "Run in nix-shell" bash hc package bash hc run -p 3401

Now that both your UI server and your Holochain conductor server are running, open up a browser and go to 0.0.0.0:8000. You should see the HTML elements you created:

Open the developer console, enter your name, and press the "Submit Name" button. You should something similar to this:

The address you see will probably be different, because you typed in your own name.

Show the new entry's address

Now we're going to show the address on the page rather than the developer console.

But first, a bit of refactoring. If you make the show_ouput function more generic, then you can reuse it for each element that shows the output for a zome function.

Pass in the element's ID so that the function can be reused:

-function show_output(result) {
+function show_output(result, id) {
-  var span = document.getElementById('output');
+  var el = document.getElementById(id);
  var output = JSON.parse(result);
-  span.textContent = ' ' + output.Ok;
+  el.textContent = ' ' + output.Ok;
}

function hello() {
  holochain_connection.then(({callZome, close}) => {
    callZome('test-instance', 'hello', 'hello_holo')({args: {}}).then(result =>
-      show_output(result),
+      show_output(result, id),
    );
  });
}

function create_person() {
  const name = document.getElementById('name').value;
  holochain_connection.then(({callZome, close}) => {
    callZome('test-instance', 'hello', 'create_person')({
      person: {name: name},
-    }).then(result => console.log(result));
+    }).then(result => show_output(result, id));
  });
}

Enter the browser

Go back to your browser and refresh the page. This time when you enter your name and press Submit Name, you will see the address show up:

Retrieve a person entry and show it in the UI

Back in the index.html file now and under the create person section, add a new header:

    <h3>Retrieve Person</h3>

Add a text box so the user can enter the address that is returned from the create_person function:

    <input type="text" id="address_in" placeholder="Enter the entry address">

Add a button that calls the (yet to be written) retrieve_person JavaScript function:

    <button onclick="retrieve_person()" type="button">Get Person</button>

Add a span with the ID person_output to display the person that is returned from the retrieve_person function:

    <div>Person: <span id="person_output"></span></div>

Go to your `hello.js` file

Add the retrieve_person function to call the zome function of the same name and show its response:

function retrieve_person() {

Get the value from the address_in text box:

  var address = document.getElementById('address_in').value;

Wait for the connection and then make a zome call:

  holochain_connection.then(({callZome, close}) => {

Call the retrieve_person public zome function, passing in the address. Then pass the result to show_person:

    callZome('test-instance', 'hello', 'retrieve_person')({
      address: address,
    }).then(result => show_person(result, 'person_output'));
  });
}

Add the show_person function. It is very similar to show_output except that you need to show the name.

function show_person(result) {
  var person = document.getElementById('person_output');
  var output = JSON.parse(result);
  person.textContent = ' ' + output.Ok.name;
}

Enter the browser

Finally go and test this out at 0.0.0.0:8000.
You should see somehting like this:

Well done! You have stored and retrieved data from a private source chain all using a GUI.

freesig

2019/09/13 06:57:53

This tutorial is quiet long I think this would be a good place to break it in half (Edited)

Paul d'Aoust

2019/09/18 21:05:28

I wonder if we could assign the value of `Ok` to a var called `address` to show that we expect this function to return an entry address. (Edited)

2019/09/18 21:07:31

What about having `retrieve_person` return the inner value of the `App` entry? Because the zome functions create a public API of sorts, it feels like it's the zome function's job to abstract away implementation details. (Edited)

2019/09/18 21:12:54

(looks like you can make this really readable by using `Option<T>::map()`. Actually, I don't know how readable that is... (Edited)

2019/09/18 21:14:45

I like the technique of asking the reader to reason about what sort of error they might see. Is it possible to put the error output down here so they can compare once they guess and run the test? Or does the test always hang when calling a non-existent zome function, as implied here? (Edited)

2019/09/18 21:18:48

I moved this down from its original spot, because once you create the struct you can only manipulate it internally -- it's only after HC knows about it by calling the function marked `#[entry_def]` that you can create and store entries of this type. (Edited)

2019/09/18 21:22:25

Because we introduce public zome functions in the previous tutorial, maybe we should introduce the `hc_public` concept there instead? (Edited)

2019/09/18 21:24:42

See above re: suggestion of giving back the entry content rather than JSONifying the whole `Entry::App` enum variant. (Edited)

2019/09/19 00:41:59

yeh it seems to always hang (Edited)

2019/09/19 14:49:16

This screencast modifies line 30 from `update_span` to `update_element`, but line 30 previously reads `console.log`. (Edited)

2019/09/19 17:31:17

see above re: suggestion to unwrap the content from the `Entry::App` enum variant. (Edited)

Hello Me

Test first

Running the test

Add the entry

Add some use statements

Create a person

Compile

Retrieve person

Test

UI

Create person UI widget

Switch to your hello.js file

Run the server and open a browser

Show the new entry's address

Enter the browser

Retrieve a person entry and show it in the UI

Go to your hello.js file

Enter the browser

Add some `use` statements

Switch to your `hello.js` file

Go to your `hello.js` file