Skip to content

api.md

Latest commit

 

History

History
344 lines (283 loc) · 11.9 KB

api.md

File metadata and controls

344 lines (283 loc) · 11.9 KB

Modules

Asset

Render the asset file and provide a download link

FileLogo

Render a file Icon

Image

Render the avatar, banner or other asset of a profile.

Link

Wrapper that links to a Profile or custom href.

MediaIcon

Render a social media icon

Pages

A custom router component that manages the rendering of index page and subpages.

SafeHtml

Render a generic container with a given HTML string inserted into it.

Functions

useLoadProfileBody(profile) ⇒ bool

Create a React state-effect combo to trigger the initialization of a profile so that all of its data can be accessed via the at() method.

useGetProfile(profileType, contentId) ⇒ Profile | false

Create a React state-effect combo to trigger the initialization of a profile so that all of its data can be accessed via the at() method. It is different from useLoadProfileBody() in that it takes a profileType and contentId as parameters instead of a profile object.

useLinkedProfileFilterState(profile, profileType, sectionName, fieldName) ⇒ Array

Get a list of project profiles linked to a given profile and a function to update the filter and sorting state of the list.

Asset

Render the asset file and provide a download link

module.exports() ⇒ function ⏏

Create a card-styled component that displays a preview of the asset file, along with the title, description, and a download link.

Kind: Exported function
Returns: function - A react component.
Component: Asset
Properties

Name Type Default Description
profile Profile The target profile.
value string The value of the asset file.
[withDownload] string | bool true true for 'rounded-full' or a specific class name.

Example

function MyComponent() {
  return (
      <Asset profile={profile} value="xxx" withDownload />
  );
}

FileLogo

Render a file Icon

module.exports() ⇒ function ⏏

Return a Icon based on the filename.

Kind: Exported function
Returns: function - A react component.
Component: FileLogo
Properties

Name Type Description
filename string The file name.
size string The size of the icon.

Example

function MyComponent() {
  return (
      <FileLogo profile={profile} value="xxx" withDownload />
  );
}

Image

Render the avatar, banner or other asset of a profile.

module.exports() ⇒ function ⏏

Create a image with given profile and type.

Kind: Exported function
Returns: function - A react component.
Component: Asset
Properties

Name Type Default Description
profile Profile The target profile.
type string One of the following: 'avatar', 'banner' or 'image'.
size string One of the following: 'xs', 'sm', 'md', 'lg'.
[rounded] string | bool false true for 'rounded-full' or a specific class name.
className string Additional tailwind class names.
value string The value of the asset when type is not 'avatar' or 'banner'.
alt string The alt of the asset when type is not 'avatar' or 'banner'.

Example

function MyComponent() {
  return (
      <Image profile={profile} type="banner" size="sm" rounded className="hover:cursor-pointer">
			{label}
		 </Image>
  );
}

Link

Wrapper that links to a Profile or custom href.

module.exports() ⇒ function ⏏

Create a React DOM router Link that wraps content that functions as a link to a given target page.

Kind: Exported function
Returns: function - A Link component.
Component: Link
Properties

Name Type Description
profile Profile The target profile if the link points to a profile.
[options] Object Options to control the destination on a profile.
options.tab string The target tab of a profile.
options.mode string The target mode of a profile. Defaults to 'view'.
options.searchParams string Extra arguments for the profile HREF.
[target] string A target attribute for the anchor element.
title string A title attribute for the anchor element.
style string | Profile A style attribute for the anchor element.
className string A className attribute for the anchor element.
to string An href attribute for the anchor element.
ariaLabel string An ARIA label for the anchor element.
children ReactNode | ReactNodeArray The contents for the Link container.

Example

function MyComponent() {
  return (
     <Link to='https:...' className='xxx'>
         <span>A link</span>
     </Link>
  );
}

MediaIcon

Render a social media icon

module.exports() ⇒ function ⏏

Return a Icon based on the social media type.

Kind: Exported function
Returns: function - A react component.
Component: MediaIcon
Properties

Name Type Description
type string The media type.
size string The size of the icon.
className string Additional tailwind className.

Example

function MyComponent() {
  return (
      <MediaIcon type={'facebook'} size="10" />
  );
}

Pages

A custom router component that manages the rendering of index page and subpages.

module.exports(list, renderIndex, renderSubpage) ⇒ JSX.Element ⏏

Custom Router Component

This component acts as a router to manage the rendering of pages and subpages within the website. It accepts an array of data objects (list prop) representing different content and two render props (renderIndex and renderSubpage) to customize how the content is displayed.

Kind: Exported function
Returns: JSX.Element - - Returns the JSX element for the custom router component.
Component:

Param Type Description
list Array.<Object> An array of data objects representing subpages.
renderIndex function A render prop function to display a summarized view of all subpages.
renderSubpage function A render prop function to render the content of a specific subpage.

Example

// Define an array of data objects representing subpages
const profiles = [
  { ...profile_1 },
  { ...profile_2 },
  { ...profile_3 },
  ...
];

// Example usage of the Custom Router Component
<Pages
  list={profiles}
  renderIndex={(profiles) => {
    // Render a summarized view of all subpages (e.g., a list of profiles)
    return (
      <ul>
        {profiles.map((profile) => (
          <li key={profile.key}>{profile.title}</li>
        ))}
      </ul>
    );
  }}
  renderSubpage={(key, profile) => {
    // Render the content of a specific subpage based on the provided data
    return (
      <div key={key}>
        <h1>{profile.title}</h1>
        <p>{profile.description}</p>
      </div>
    );
  }}
/>

SafeHtml

Render a generic container with a given HTML string inserted into it.

module.exports() ⇒ function | null ⏏

In React, dangerouslySetInnerHTML is provided to directly insert HTML into a React element. As the name implies, it's not generally recommended because it can expose your application to cross-site scripting (XSS) attacks if misused. If you're fully aware of the danger and confident that the HTML to use is safe, and you still need to inject HTML directly into a React component, this wrapper component is a simple way to use dangerouslySetInnerHTML.

As an extra precaution, the given HTML is sanitized with DOMPurify to ensure it's safe to inject into the page.

Kind: Exported function
Returns: function | null - A react component if value is a string and null otherwise.
Component: SafeHtml
Properties

Name Type Description
value string The HTML code to insert.
as string The element type.

Example

<SafeHtml value="<strong>Hello world!</strong>" as="span" className="my-class" />

useLoadProfileBody(profile) ⇒ bool

Create a React state-effect combo to trigger the initialization of a profile so that all of its data can be accessed via the at() method.

Kind: global function

Param Type
profile Profile

useGetProfile(profileType, contentId) ⇒ Profile | false

Create a React state-effect combo to trigger the initialization of a profile so that all of its data can be accessed via the at() method. It is different from useLoadProfileBody() in that it takes a profileType and contentId as parameters instead of a profile object.

Kind: global function
Returns: Profile | false - Returns the profile object once it is in a complete (ready) state. Returns false while the profile data is being fetched.

Param Type Description
profileType string A profile object or a profile type string.
contentId int | string The ID of the profile if profileOrType is a string. Otherwise, it must be empty.

useLinkedProfileFilterState(profile, profileType, sectionName, fieldName) ⇒ Array

Get a list of project profiles linked to a given profile and a function to update the filter and sorting state of the list.

Kind: global function
Returns: Array - - A 2D array with the current filter state and a function to update the state. The state is an Object with several properties. The filtered property of the state is an array of Profile objects with the ordered list of profiles to render.

Param Type Description
profile Profile The source profile.
profileType string The profile type of the linked profiles to return.
sectionName string | null The section name in the source profile that has the list of linked profiles.
fieldName string | null The field name in sectionName that stores the target linked-profile reference.