Module sui::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.

• Struct Display
• Struct DisplayCreated
• Struct VersionUpdated
• Constants
• Function new
• Function new_with_fields
• Function create_and_keep
• Function update_version
• Function add
• Function add_multiple
• Function edit
• Function remove
• Function is_authorized
• Function version
• Function fields
• Function create_internal
• Function add_internal

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

Struct `Display`

The Display 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<0x...::capy::Capy> {
fields:
<name, "Capy { genes }">
<link, "https://capy.art/capy/{ id }">
<image, "https://api.capy.art/capy/{ id }/svg">
<description, "Lovely Capy, one of many">
}

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: sui::object::UID

fields: sui::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.

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 Sui 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: sui::object::ID

Struct `VersionUpdated`

Version of Display got updated -

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

Fields

id: sui::object::ID

version: u16

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

Constants

For when T does not belong to the package Publisher.

const ENotOwner: u64 = 0;

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

const EVecLengthMismatch: u64 = 1;

Function `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: &sui::package::Publisher, ctx: &mut sui::tx_context::TxContext): sui::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)
}

Function `new_with_fields`

Create a new Display object with a set of fields.

public fun new_with_fields<T: key>(pub: &sui::package::Publisher, fields: vector<std::string::String>, values: vector<std::string::String>, ctx: &mut sui::tx_context::TxContext): sui::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 display = new<T>(pub, ctx);
    fields.zip_do!(values, |field, value| display.add_internal(field, value));
    display
}

Function `create_and_keep`

Create a new empty Display object and keep it.

public entry fun create_and_keep<T: key>(pub: &sui::package::Publisher, ctx: &mut sui::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())
}

Function `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 sui::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(),
    })
}

Function `add`

Sets a custom name field with the value.

public entry fun add<T: key>(self: &mut sui::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)
}

Function `add_multiple`

Sets multiple fields with values.

public entry fun add_multiple<T: key>(self: &mut sui::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);
    fields.zip_do!(values, |field, value| self.add_internal(field, value));
}

Function `edit`

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

public entry fun edit<T: key>(self: &mut sui::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)
}

Function `remove`

Remove the key from the Display.

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

Implementation

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

Function `is_authorized`

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

public fun is_authorized<T: key>(pub: &sui::package::Publisher): bool

Implementation

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

Function `version`

Read the version field.

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

Implementation

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

Function `fields`

Read the fields field.

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

Implementation

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

Function `create_internal`

Internal function to create a new Display<T>.

fun create_internal<T: key>(ctx: &mut sui::tx_context::TxContext): sui::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,
    }
}

Function `add_internal`

Private method for inserting fields without security checks.

fun add_internal<T: key>(display: &mut sui::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)
}