Module iota::display

Defines a Display struct which defines the way an Object should be displayed. The intention is to keep data as independent from its display as possible, protecting the development process and keeping it separate from the ecosystem agreements.

Each of the fields of the Display object should allow for pattern substitution and filling-in the pieces using the data from the object T.

More entry functions might be added in the future depending on the use cases.

use iota::address;
use iota::event;
use iota::hex;
use iota::object;
use iota::package;
use iota::transfer;
use iota::tx_context;
use iota::types;
use iota::vec_map;
use std::address;
use std::ascii;
use std::bcs;
use std::option;
use std::string;
use std::type_name;
use std::vector;

Module Functions

pub is_authorized

Authorization check; can be performed externally to implement protection rules for Display.

public fun is_authorized<T: key>(pub: &iota:📦:Publisher): bool

Implementation

public fun is_authorized<T: key>(pub: &Publisher): bool {
    pub.from_package<T>()
}

pub new

Create an empty Display object. It can either be shared empty or filled with data right away via cheaper set_owned method.

public fun new<T: key>(pub: &iota:📦:Publisher, ctx: &mut iota::tx_context::TxContext): iota::display::Display<T>

Implementation

public fun new<T: key>(pub: &Publisher, ctx: &mut TxContext): Display<T> {
    assert!(is_authorized<T>(pub), ENotOwner);
    create_internal(ctx)
}

pub new_with_fields

Create a new Display<T> object with a set of fields.

public fun new_with_fields<T: key>(pub: &iota:📦:Publisher, fields: vector<std::string::String>, values: vector<std::string::String>, ctx: &mut iota::tx_context::TxContext): iota::display::Display<T>

Implementation

public fun new_with_fields<T: key>(
    pub: &Publisher,
    fields: vector<String>,
    values: vector<String>,
    ctx: &mut TxContext,
): Display<T> {
    let len = fields.length();
    assert!(len == values.length(), EVecLengthMismatch);
    let mut i = 0;
    let mut display = new<T>(pub, ctx);
    while (i < len) {
        display.add_internal(fields[i], values[i]);
        i = i + 1;
    };
    display
}

pub entry create_and_keep

Create a new empty Display<T> object and keep it.

public entry fun create_and_keep<T: key>(pub: &iota:📦:Publisher, ctx: &mut iota::tx_context::TxContext)

Implementation

public entry fun create_and_keep<T: key>(pub: &Publisher, ctx: &mut TxContext) {
    transfer::public_transfer(new<T>(pub, ctx), ctx.sender())
}

prv create_internal

Internal function to create a new Display<T>.

fun create_internal<T: key>(ctx: &mut iota::tx_context::TxContext): iota::display::Display<T>

Implementation

fun create_internal<T: key>(ctx: &mut TxContext): Display<T> {
    let uid = object::new(ctx);
    event::emit(DisplayCreated<T> {
        id: uid.to_inner(),
    });
    Display {
        id: uid,
        fields: vec_map::empty(),
        version: 0,
    }
}

Structs

struct Display

The Display<T> object. Defines the way a T instance should be displayed. Display object can only be created and modified with a PublisherCap, making sure that the rules are set by the owner of the type.

Each of the display properties should support patterns outside of the system, making it simpler to customize Display based on the property values of an Object.

// Example of a display object
Display<0x107A::nft::Nft> {
fields:
<name, "IOTEST Nft">
<link, "https://iotestnft.com/nft/{ id }">
<image, "https://api.iotestnft.com/nft/{ id }/svg">
<description, "One of many Iotest Nfts">
}

Uses only String type due to external-facing nature of the object, the property names have a priority over their types.

public struct Display<phantom T: key> has key, store

Fields

id: iota::object::UID

fields: iota::vec_map::VecMap<std::string::String, std::string::String>

Contains fields for display. Currently supported fields are: name, link, image and description.

version: u16

Version that can only be updated manually by the Publisher.

pub fields

Read the fields field.

public fun fields<T: key>(d: &iota::display::Display<T>): &iota::vec_map::VecMap<std::string::String, std::string::String>

Implementation

public fun fields<T: key>(d: &Display<T>): &VecMap {
    &d.fields
}

pub version

Read the version field.

public fun version<T: key>(d: &iota::display::Display<T>): u16

Implementation

public fun version<T: key>(d: &Display<T>): u16 {
    d.version
}

pub entry add

Sets a custom name field with the value.

public entry fun add<T: key>(self: &mut iota::display::Display<T>, name: std::string::String, value: std::string::String)

Implementation

public entry fun add<T: key>(self: &mut Display<T>, name: String, value: String) {
    self.add_internal(name, value)
}

pub entry add_multiple

Sets multiple fields with values.

public entry fun add_multiple<T: key>(self: &mut iota::display::Display<T>, fields: vector<std::string::String>, values: vector<std::string::String>)

Implementation

public entry fun add_multiple<T: key>(
    self: &mut Display<T>,
    fields: vector<String>,
    values: vector<String>,
) {
    let len = fields.length();
    assert!(len == values.length(), EVecLengthMismatch);
    let mut i = 0;
    while (i < len) {
        self.add_internal(fields[i], values[i]);
        i = i + 1;
    };
}

pub entry edit

Change the value of the field. TODO (long run): version changes;

public entry fun edit<T: key>(self: &mut iota::display::Display<T>, name: std::string::String, value: std::string::String)

Implementation

public entry fun edit<T: key>(self: &mut Display<T>, name: String, value: String) {
    let (_, _) = self.fields.remove(&name);
    self.add_internal(name, value)
}

pub entry remove

Remove the key from the Display.

public entry fun remove<T: key>(self: &mut iota::display::Display<T>, name: std::string::String)

Implementation

public entry fun remove<T: key>(self: &mut Display<T>, name: String) {
    self.fields.remove(&name);
}

pub entry update_version

Manually bump the version and emit an event with the updated version's contents.

public entry fun update_version<T: key>(display: &mut iota::display::Display<T>)

Implementation

public entry fun update_version<T: key>(display: &mut Display<T>) {
    display.version = display.version + 1;
    event::emit(VersionUpdated<T> {
        version: display.version,
        fields: *&display.fields,
        id: display.id.to_inner(),
    })
}

prv add_internal

Private method for inserting fields without security checks.

fun add_internal<T: key>(display: &mut iota::display::Display<T>, name: std::string::String, value: std::string::String)

Implementation

fun add_internal<T: key>(display: &mut Display<T>, name: String, value: String) {
    display.fields.insert(name, value)
}

struct DisplayCreated

Event: emitted when a new Display object has been created for type T. Type signature of the event corresponds to the type while id serves for the discovery.

Since IOTA RPC supports querying events by type, finding a Display for the T would be as simple as looking for the first event with Display<T>.

public struct DisplayCreated<phantom T: key> has copy, drop

Fields

id: iota::object::ID

struct VersionUpdated

Version of Display got updated -

public struct VersionUpdated<phantom T: key> has copy, drop

Fields

id: iota::object::ID

version: u16

fields: iota::vec_map::VecMap<std::string::String, std::string::String>

Constants

err ENotOwner

For when T does not belong to the package Publisher.

const ENotOwner: u64 = 0;

err EVecLengthMismatch

For when vectors passed into one of the multiple insert functions don't match in their lengths.

const EVecLengthMismatch: u64 = 1;