UR::Object::View(3pm)

💖 UR::Object::View — bestie edition 💖

okay so real talk, this is UR::Object::View, and it's the base class for "views" of UR::Objects. that's the whole vibe. it's giving MVC royalty, it's giving "i hold the widget so you don't have to" ✨

---

✨ SYNOPSIS ✨

$object = Acme::Product->get(1234);

## Acme::Product::View::InventoryHistory::Gtk2

$view = $object->create_view(
  perspective         => 'inventory history',
  toolkit             => 'gtk2',
);
$widget = $view->widget();    # returns the Gtk2::Widget itself directly
$view->show();                # puts the widget in a Gtk2::Window and shows everything

##

$view = $object->create_view(
  perspective         => 'inventory history',
  toolkit             => 'xml',
);
$widget = $view->widget();    # returns an arrayref with the xml string reference, and the output filehandle (stdout)
$view->show();                # prints the current xml content to the handle

$xml = $view->content();     # returns the XML directly

##

$view = $object->create_view(
  perspective         => 'inventory history',
  toolkit             => 'html',
);
$widget = $view->widget();    # returns an arrayref with the html string reference, and the output filehandle (stdout)
$view->show();                # prints the html content to the handle

$html = $view->content();     # returns the HTML text directly

like, look at her. same object, three different toolkits, zero drama 🫶

---

🌸 USAGE API 🌸

💅 create

the constructor requires that subject_class_name, perspective, and toolkit all be set. most concrete subclasses just have perspective and toolkit baked in as constants, so they don't gotta ask.

here's the thing bestie — producing a view object does not "render" the view. it just makes you an interface for controlling the view, including encapsulating how it gets created. no pixels yet. chill.

the subject can be set later, and changed later too. the aspects being viewed might be constant for a given perspective, or mutable — depends on how flexible the perspective logic is. iykyk ✨

🎀 show

for stand-alone views, this drops the view widget into its own window. for views that are part of a larger view, this makes the view widget visible inside the parent. periodt.

🙈 hide

makes the view invisible. that means hiding the window, or hiding the view widget inside the parent widget if it's a subordinate view. bye bye 👋

👑 show_modal

shows the view in a window and only returns after the window is closed. it should only be used for views that are a full interface capable of closing itself when it's done. don't be weird with it.

🦋 widget

returns the "widget" that renders the view. it's built lazily on demand — no pre-gaming. the actual object type depends on the toolkit named up above. this method might return HTML text, or a Gtk object. you can use it directly, and show/show_modal use it internally too.

(Note: see UR::Object::View::Toolkit::Text for details on the "text" widget, used by HTML/XML views, etc. This is just the content and an I/O handle to which it should stream.)

💀 delete

deletes the view, along with the widget(s) and all the infrastructure underneath it. it's not coming back. rip.

---

⭐ CONSTRUCTION PROPERTIES (CONSTANT) ⭐

these three properties are constant for a given view class. they decide which class of view gets constructed, and you must hand them to create().

• subject_class_name — the class of subject this view is gonna view. constant for any given view, but it can be any abstract class all the way up to UR::Object itself.
• perspective — describes the layout logic that gives the view its logical content. this is the ~artistic direction~ 🎨
• toolkit — the specific (usually graphical) toolkit used to build the UI. examples are Gtk, Gkt2, Tk, HTML, XML.

---

🌈 CONFIGURABLE PROPERTIES 🌈

these methods control which object is being viewed, and what properties of it are viewed. you can pass them at construction time, or afterwards. flexible queen 💅

• subject — the particular "model" object, in MVC parlance, that this view is viewing. this value may change.
• aspects / add_aspect / remove_aspect — specifications for properties/methods of the subject which get rendered in the view. some views have mutable aspects, while others just report which aspects are revealed by the perspective in question.

an "aspect" is some characteristic of the "subject" that gets rendered in the view. any property of the subject is usable, and so is any method. no cap.

---

🧚 IMPLEMENTATION INTERFACE 🧚

when you're writing new view logic, the class name is expected to follow a formula:

Acme::Rocket::View::FlightPath::Gtk2
\          /           \    /      \
subject class name    perspective  toolkit

the toolkit is expected to be a single word. the perspective is everything before the toolkit, and after the last View word. the subject_class_name is everything to the left of the final ::View::. slay, naming conventions 🎀

there are three methods which require an implementation — unless the developer inherits from a subclass of UR::Object::View that already provides these methods:

• _create_widget — creates the widget the first time ->widget() gets called on a view.

this should be implemented in a given perspective/toolkit module to actually create the GUI using the appropriate toolkit.

it will be called before the specific subject is known, so all widget creation that's subject-specific should happen in _bind_subject() instead. as such it typically only configures skeletal aspects of the view. bones only, no meat 🦴

• _bind_subject — called when the subject is set, or when it's changed, or unset. it updates the widget to reflect changes to the widget caused by a change in subject.

this method has a default implementation which does a general subscription to changes on the subject. it probably doesn't need to be overridden in custom views. implementations that do override this should take an undef subject, and be sure to un-bind a previously existing subject if there's one set. don't leave ghosts attached bestie 😭

• _update_view_from_subject — if and when the property values of the subject change, this method gets called on all views which render the changed aspect of the subject.
• _update_subject_from_view — when the widget changes, it should call this method to save the UI changes to the subject. this is not applicable to read-only views. don't try it. 💀

---

🍓 OTHER METHODS 🍓

• _toolkit_package — this method is useful for providing generic toolkit-based services to a view, using a toolkit-agnostic API. it can be used in abstract classes which, for instance, want to share logic for a given perspective across toolkits.

the toolkit class related to a view is responsible for handling show/hide logic, etc. in the base UR::Object::View class.

returns the name of a class which is derived from UR::Object::View::Toolkit that implements certain utility methods for views of a given toolkit. very iconic of her honestly 👑

---

💜 EXAMPLES 💜

$o = Acme::Product->get(1234);

$v = Acme::Product::View::InventoryHistory::HTML->create();
$v->add_aspect('outstanding_orders'); $v->show;

look at that. four lines. main character energy. 🌟

---

and that's the whole page bestie — this one ships as part of perl v5.32.1, dated 2022-01-17. go forth and view your objects, you absolute legend 🫶💖✨