ENDOC-312 Document the list of widgets included with Entando to help demonstrate what is available out of the box #677
Conversation
| | Legacy Navigation Menu | Navigation | Configurable via expression list parameters. A user with admin privileges can easily change its layout. | | ||
| | Login | System | The Keycloak-powered log in / log out component for the web app | | ||
| | Logo | Page | The default Entando logo. It can be used on other projects by changing its fragment reference. | | ||
| | Navigation Menu | Navigation | An OOTB widget based on IBM Carbon FE. It is configurable via expression list parameters but cannot be modified, even by a user with admin privileges. | |
There was a problem hiding this comment.
IBM Carbon FE doesn't sound quite right, maybe it should be just Carbon Design System. You could link it https://carbondesignsystem.com/ but I'm not sure it's useful/necessary here to provide that detail.
I would also drop the "but cannot be modified, even by a user with admin privileges." That's true but it's true of many things included in the platform and it is configurable.
| | Login | System | The Keycloak-powered log in / log out component for the web app | | ||
| | Logo | Page | The default Entando logo. It can be used on other projects by changing its fragment reference. | | ||
| | Navigation Menu | Navigation | An OOTB widget based on IBM Carbon FE. It is configurable via expression list parameters but cannot be modified, even by a user with admin privileges. | | ||
| | Search Form | CMS | Can be placed on any page | |
There was a problem hiding this comment.
This doesn't look like a description. Maybe "A basic search form"
There was a problem hiding this comment.
...i think this is a casualty of copy/paste when i alphabetized. sorry!
| # Preinstalled Widgets | ||
|
|
||
|
|
||
| The Entando Platform includes a number of useful components to accelerate application development. These consist of widgets, page templates, content templates and content types. This page introduces the CMS, navigation, page, SEO and system widgets that are available out of the box. |
There was a problem hiding this comment.
2nd sentence: comma after content templates>>
These consist of widgets, page templates, content templates, and content types.
it is not a hard and fast rule but the last comma is recommended in a long list of items, especially when the items are multi-word things.
Last sentence: the list of widget types is confusing since we just ended the previous sentence with a list of components types so the reader is wondering what are the new types as opposed to the last set. Since it's an intro, would round out the paragraph with a more general summation>> This page introduces the various types of widgets that are available out of the box.
There was a problem hiding this comment.
i'll unpack the last sentence to take the onus off the reader
no objection to adding a comma; i usually don't unless the sentence is confusing without one
|
|
||
| ## Widget Attributes | ||
|
|
||
| All widgets are required to have the following attributes. These are mandatory regardless of whether a widget is preinstalled, user-created, or inside a bundle. |
There was a problem hiding this comment.
do these requirements apply to all MFEs?
thought this page was only for pre-installed
There was a problem hiding this comment.
yes to both. this is a bit tricky because we don't have a page in docs dedicated to widgets in general. i put this info here rather than overload and break structure within the bundle component details page. these attributes are described for other entities and we need a place for this to land... the follow-up ticket where we add examples might generalize this page a bit more, which is another option (which i might prefer); we could rename this page more generally and then discuss preinstalled widgets as a subsection. for now we have kind of an interim solution
| - `Group`: A group for which the user has "create" permissions | ||
| - `Icon`: Visually represents the widget via either an uploaded icon (SVG file) or one chosen from the icon library | ||
| - `Custom UI`: HTML code that constructs the visual layout of the widget | ||
| - `Config UI`: A JSON structure that informs the widget's configuration. It requires two properties: |
There was a problem hiding this comment.
the descriptions for the list seems to change format along the way, where the first few start with verbs but gradually changes sentence format. Might make it more consistent
There was a problem hiding this comment.
agreed; these are direct from notion and initially i believed that consistency would be at the expense of direct and simplified descriptions, but i'll work with it
| - `resources`: An array listing the source location of the custom element files for the widget configuration | ||
| ## Widget Descriptions | ||
|
|
||
| The following tables list the notable preinstalled widgets of an Entando instance. They can be accessed from the left menu of the App Builder by selecting `Components` → `MFE & Widgets`. |
There was a problem hiding this comment.
tables>> table
thinking there's only one table
There was a problem hiding this comment.
you are correct! originally there were like 5... the format has changed like 10 times and now it's mostly only a handful of descriptions i can't further interpret/clarify...
| | APIs | System | The only mechanism with which developers can communicate with the Entando core | | ||
| | Content List | CMS | Renders a list of contents, each one displaying information from a template | | ||
| | Content Search Query | CMS | Publishes a list of contents based on different settings | | ||
| | Content SEO Meta-description | SEO | The SEO parameters specified when pages are created or modified | |
There was a problem hiding this comment.
the verb tenses change in the description
There was a problem hiding this comment.
yes. same as above
| | Content Search Query | CMS | Publishes a list of contents based on different settings | | ||
| | Content SEO Meta-description | SEO | The SEO parameters specified when pages are created or modified | | ||
| | Internal Servlet | System | Legacy implementation to create server-side widgets using Struts 2. Available for backwards compatibility with older projects. | | ||
| | Legacy Login Form | System | A non-Keycloak form component for log in | |
There was a problem hiding this comment.
log in >> think it should be either logging in or login
There was a problem hiding this comment.
strictly speaking log in is correct but i don't like it either. logging in ftw
| | Content SEO Meta-description | SEO | The SEO parameters specified when pages are created or modified | | ||
| | Internal Servlet | System | Legacy implementation to create server-side widgets using Struts 2. Available for backwards compatibility with older projects. | | ||
| | Legacy Login Form | System | A non-Keycloak form component for log in | | ||
| | Legacy Navigation Menu | Navigation | Configurable via expression list parameters. A user with admin privileges can easily change its layout. | |
There was a problem hiding this comment.
the description does not describe what it is, only what can be done with it; unsure if this is important since navigation menu is what it is but the legacy part bothers me.
There was a problem hiding this comment.
i'm not totally comfortable fleshing out these descriptions ...i cannot further resolve or describe some of these. since the widget name is self-explanatory i'm not sure how to describe it in other, meaningful terms
| | Internal Servlet | System | Legacy implementation to create server-side widgets using Struts 2. Available for backwards compatibility with older projects. | | ||
| | Legacy Login Form | System | A non-Keycloak form component for log in | | ||
| | Legacy Navigation Menu | Navigation | Configurable via expression list parameters. A user with admin privileges can easily change its layout. | | ||
| | Login | System | The Keycloak-powered log in / log out component for the web app | |
There was a problem hiding this comment.
log in/log out component>> login/logout
think it's being used as nouns here to describe component, whereas log in is a verb form >> The login component is such and such...
'The log in component is such and such...' seems wrong
There was a problem hiding this comment.
agreed! it's actually used to modify a noun so i wasn't sure where we stood with that. the modifier is describing an action, so the verb usage seems like it should apply, but it doesn't hit right
| The Entando Platform includes a number of useful components to accelerate application development. These consist of widgets, page templates, content templates and content types. This page introduces the CMS, navigation, page, SEO and system widgets that are available out of the box. | ||
| The Entando Platform includes a number of useful components to accelerate application development. These consist of widgets, page templates, content templates, and content types. | ||
|
|
||
| This page introduces the widgets that are available out of the box with an Entando 7 installation. These widgets are categorized by type, implementing CMS, navigation, page, SEO or system functionality. |
There was a problem hiding this comment.
'implementing' is confusing and awkward. After categorized by type, you're expecting nouns, not a verb so it reads strangely. Like is 'implementing cms' a type
There was a problem hiding this comment.
it would need to be "type:" to read that way. but i can see that right now after "type," you're expecting additional details about widgets instead of about widget types, like "the widgets are categorized by type, use x, look like y..." like more verbs of the same tense to describe additional characteristics.
No description provided.