ElementBrowser

The ElementBrowser is a component in the Kyub frontend that is utilized to show a number of cards, each representing one element in Kyub. These elements can range from cards representing users, over their models to lasercutters and materials.

UserCard

The UserCard component is used when a user is to be shown. It is not as customizable as the ProjectCard, however, it also doesn't have to cover as many different use cases as the ProjectCard does.

ProjectCard

The ProjectCard component is used whenever any element that's not a user is to be shown in the ElementBrowser. The card has a number of props that can be set in order to automatically modify its look.

Avatar

Some cards look different than the regular picture - title- subtitle card. They have a small picture cropped as a circle on the left side of the split between card image and content and show bold text above their title.

These cards are using the Avatar. It is usually used to show the creator of some object (check out workshops and their members where, instead of the user card, one model of the user is often shown & the users themselves are only indicated by this avatar section). Other uses are possible though, such as showing the current owner of a sheet of material.

The avatar is highly customizable by passing up to four (4) generator functions to the ElementBrowser where they are resolved for each individual ProjectCard.

1. avatarSettings - this function is needed to define
   a. the type of object the avatar is for (currently only user or tool)
   b. the kind of placeholder image to display if the avatar image is not retrievable/does not exist (see PlaceholderType in FilePreview.vue)
   c. Whether to show the avatar name (bold text) at all d. Whether to show the avatar picture - in addition to the boolean true/false options, you may specify the strings "ifAvailable" or "ifNotCurrentUser" for this field
   Example ts private _avatarSettings( element: IProjectCardData, setting: "type" | "placeholder" | "showName" | "showPicture", ) { switch (setting) { case "type": return "user"; // the type of avatar is user, e.g. for the creator of some object case "placeholder": return "user"; // the image placeholder is the standard user profile pic placeholder case "showName": return true; // always show the avatar name case "showPicture": return "ifNotCurrentUser"; // show avatar picture only if user is not the one currently logged in } } The default is that neither the avatar name nor the image are shown.
2. avatarLinkDefinitionGenerator - this function needs to return an object that can be passed to the router in order to create a link to some other Kyub page. Currently, only users are ever linked, but other objects being linked is possible. Returning null will indicate that no link should be created (i.e. the avatar name & image are not clickable).
   This is only called if either the avatar name or picture are actually being shown for a project card.
   Example ts private _avatarLinkGenerator( element: IOwnedObjectExample, ): { name: string; params: { [key: string]: string } } | null { const owner = element.currentOwner; if (!owner) return null; // if there is no owner, don't create any link // if there is a owner, create a link to their profile return { name: "User Profile", params: { userName: owner.userName } }; } The default is that a link to the object's creator (if set) is created.
3. avatarNameGenerator - this function returns the string to be displayed as the avatar name (the bold text). If null is returned, the avatar name is not shown. This is only called if the avatar name is supposed to be shown for a project card.
   Example ts private _avatarNameGenerator(element: IProjectCardData): string | null { const creator = element.creator; if (!creator) return "Unknown user"; // if the creator is not known, put this as placeholder name return creator.username; // return creator username otherwise } The default behavior is returning the creator's name & surname (preferred) or their username. If no creator is identified, returns null - so no avatar text is shown in that case.
4. avatarPictureGenerator - this function is meant to return the picture to show for the avatar. It does not need to resolve any fallback/placeholder images, this is done at a different point in the code if this function returns null and the image is set to always being shown.
   This is only called if the avatar image is supposed to be shown for a project card. (includes the ifAvailable & ifNotCurrentUser cases)
   Example ts private _avatarImageGenerator(element: IProjectCardData): IPublicFile | null { const creator = element.creator; if (!creator) return null; // no other image to fetch if the creator has none and we want to show them return creator.profilePicture ?? null; // make sure to return null even in the case of undefined image } The default behavior is returning the creator's profile picture.

As you see - if you want to simply show the creator of some element on its card, you only need to define & pass one of these four functions, the avatarSettings, as all others are seeded with defaults assuming that the element's creator is shown as the avatar on the card.

Halo

If you are displaying the avatar picture on a project card you have the option to add a halo (a colored circle with text in it around the avatar picture) to it, drawing focus to the card and enabling you to convey a short message to the user. E.g., you may want to tell the user to "try this out" or show them that a sheet of material is "in possession of this user".

This halo has three different elements that can be modified: the text shown in the upper half, the text shown in the lower half and the color of the halo.

You modify these elements by passing another generator function to the ElementBrowser, where it is again executed and the resulting configuration object passed to its corresponding ProjectCard.

Example

private _generateHaloContent(
  element: IProjectCardData,
): { upper: string | null; lower: string | null; bgColor: string | null } | null {
  let toReturn = null;
  if (element.elementType === "model") {
    toReturn = {
      upper: "Model created by",
      lower: element.creator?.userName ?? "Unknown",
      bgColor: null,
    };
  }
  return toReturn;
}

This example would lead to a halo being shown for all elements of type "model". The halo would have the default color, an amber (#ffb300). The upper half text is "Model created by" & the lower half displays the creator's username. If no creator is known, the lower half text is set the "Unknown". If it were to be set to null instead, the lower half of the halo would simply be empty.