A custom component is a small, reusable widget your organization builds once and uses on many pages. Common examples include a staff directory card, a call-to-action banner, an announcement box, or an embedded third-party tool. You build the component with markup, a stylesheet, and a script, and you can add input fields that page authors complete each time they place it.
What It Controls
A custom component includes its markup, styles, script, input fields, name, Rhythm application, and any stylesheets, scripts, or files it needs. After you publish the component, page authors can use it on pages and templates across every site for your organization.
Where to Find It
Open Portals & Microsites › Assets, then open an existing custom component or create a new custom component asset. The component opens in its own tab, with the code column on the left and the settings panel on the right.
Prerequisites
You need permission to design assets before you can open the Asset Explorer and work with custom components.
Writing the Component
The code column has three editors, stacked in this order:
- Markup, where you write the component's HTML. When the markup includes
{{ component.<variable name> }}, Rhythm inserts the value the page author enters for that field. - Stylesheet, where you write the component's own styles.
- Script, where you add any JavaScript the component needs.
Rhythm saves your changes automatically about a second after you stop typing. It does not validate your markup, styles, or script, so broken code is saved exactly as you enter it.
To make an image clickable, wrap its <img> tag in an anchor tag with an href, just as you would on any HTML page. An image does not become a link just because it is near linked text.
Tip
If a page is close to its size limit for embedded images, point an <img> tag to the image's public URL instead of embedding more image content directly. This usually lets you keep adding images without increasing the page size further. If you do not already have a public URL for the image, upload it as a file asset and use that asset's shareable link.
Your script can draw an element, such as a button, only when the rendering code is in the component's Script editor. Container markup in the Markup editor does not make a script-generated element appear by itself, so add the code that builds the element to the Script editor too.
Tip
A custom component is often a good place for a third-party embed, such as a chat widget. Paste the vendor's embed code into the markup or script editor, publish the component, then place it on each page or template where you want the widget to appear. Because you place the component per page or template, you need to add the widget everywhere you want it, including future templates. If a page author expects to add a vendor's script or button directly on a page, that is usually not supported; build it into a custom component first.
Google Tag Manager works the same way, but the vendor splits its snippet in two. Paste the first part into a custom component's markup or script editor and place that component on each page you want to track. Then paste the companion snippet into Site Settings under CSS & Javascript. See Header and Footer Markup, Script Tags, and Stylesheet Tags for that second part.
Naming the Component and Choosing Its Fields
To add an input field:
- In the Fields section, select Add Field.
- Choose a field type: Text, HTML/Content, Number, Page, or Menu.
- Optionally mark the field as required.
- Select Save Changes.
Result
The field appears in the fields list and is available wherever the component is placed.
Warning
Avoid the Choice field type for now. This field type does not currently save, so any choice list you enter is lost.
You can drag fields to reorder them, clone a field to start from a similar one, or remove a field you no longer need. Rhythm does not check whether variable names are unique, so if you clone a field or type one by hand, make sure it does not match another field's variable name.
Tip
If a field's default value is not behaving as expected after the component is placed, removing the field is a reasonable fallback while you investigate. Page authors can still enter the value directly where the field appears, or you can rebuild the field afterward.
Linking Stylesheets, Scripts, and Files
If your component needs a shared stylesheet, script library, or other file wherever it appears, link that asset in the Linked Assets section:
- In the Linked Assets section, select the + beside Stylesheets, Javascript files, or Other files, depending on the kind of asset you want to link.
- Choose one or more assets from the list and confirm.
Result
The assets appear in the list in load order. You can drag them to reorder them, or remove one with its trash icon.
Linked assets are referenced by identifier. If you later delete an asset that a component links to, the component keeps pointing to that asset, so do not delete a stylesheet, script, or file while any component still links to it.
Tip
A linked stylesheet can also hide part of a built-in component you cannot otherwise edit. For example, a CSS rule that targets the preferred-address element has been used to hide the full address block on the membership overview page. Treat this as a workaround rather than a supported setting, because it depends on the page's current markup and may need adjustment if that markup changes.
Previewing and Publishing
Use Preview to see the component rendered with sample field values on a site you choose. Preview shows the component's working copy, so it may differ from the version that is currently published. Visitors do not see your changes until you select Publish Changes, which makes the saved working copy the version every site can use. Revert to Published Version discards unpublished changes and restores the last published version.
Built-In Components
Alongside your organization's custom components, the designer's Inject Components helper lists ready-made components provided by other Rhythm applications. When you choose one from that list, Rhythm copies its markup to your clipboard so you can paste it into another component's markup. If nothing appears on your clipboard after you make a selection, try choosing the component again before assuming it is broken.
Your organization cannot edit built-in components. A built-in component can only show the data it was already built to expose, so adding a related record it does not already show, or rearranging its built-in layout, usually requires a product change or engineering work instead of an HTML edit. Some built-in controls also include labels or helper text that do not come from your custom field setup; changing that wording requires Rhythm to update the control itself.
The table below lists built-in components with known limitations:
| Component | What You Cannot Change |
|---|---|
| Membership Overview | The task menu order, the "What Would You Like to Do" links, and the Chapter Management link position are built into the component. Some installations have also found no way to remove an individual section, such as Digital Library. Because every organization shares this component instead of receiving a separately built version, layout change requests go to product for evaluation rather than to web design. |
| My Financial Overview | The layout and fields are hard-coded, so a site or template editor cannot directly change the component's underlying code. |
| My Credits | The component shows a fixed set of credit and certification fields, with no setting to choose different ones. |
| Registrant Directory | Its search control, including the search button, is built into the component. You cannot move the button or add a second one. |
| Directory Entry | Some related-record fields, such as parent organization or organization type, have been available only as an ID, without a matching display-name merge field. |
| Directory messaging (contact-the-member form) | Its fields are fixed, so you cannot add fields such as a sender name or email address. |
| Contact Profile | Merge fields may not expose every related record. Membership type, membership expiration, and chapter, for example, are currently available through the Membership Overview component, not through Contact Profile's own merge fields. |
| My Certification | The certification route uses a built-in Rhythm component that is not exposed in Portals & Microsites, so you cannot add fields to it from here. |
| Award view | Some wording on the award screen is part of the component itself, not a setting you can change. |
| Work Experience | The Areas of Practice field has been required for every Nature of Work selection, including values such as Related or Other. |
| Print Membership ID Card | This option is a built-in action of the standard Membership Overview component, not an ordinary link, so you cannot recreate it by hand in a custom version of the dashboard's action area. To keep it, leave the standard Membership Overview component on the page and place any custom links or actions in a separate component beside it, rather than replacing the standard one. |
The Communication Preferences component does not support a separate description under each option. If people need more context than an option's title provides, make the title more descriptive or add shared explanatory text in the component's Header & Text HTML section.
Some ready-made components still need a setting chosen by hand after you place them. The View Order component, for example, has a setting for whether contacts or organizations can access it. Rhythm does not choose a default because the right option depends on your organization's setup, so choose it yourself when you place the component. If you need to change wording on a request-form page, check whether the page uses the Submission Center component before assuming it is a custom template; the component's own settings may control the text you want to change.
Some components are configured from their own page instead of from here. To change the pricing-column labels shown by the Registration Pricing & Deadlines component, open the event microsite's own page in the page designer, update that pricing component's settings, then save and publish the page if the change needs to go live.
Your site's visible footer text, including the displayed year, usually lives in the Main Footer component. Open it under Assets › Components and edit its markup there. This is different from the header and footer markup in Site Settings, which adds separate markup to every page; editing the Main Footer component changes the footer content itself.
Tip
If a built-in form or component cannot be customized the way you need, add instructions on the page around it instead. For example, place a text block above a directory or contact form asking visitors to include specific details, such as their contact information, directly in the message they submit.
If the built-in Membership Overview component's fixed layout does not work for your organization, you can build a custom component and place it on the Membership Overview page instead of the standard one. Test it on a separate page first, then swap it in once you are satisfied with it. Keep in mind that the built-in component's Helpful Links area adjusts its options automatically. A custom replacement only shows the links you build into it, so you need to maintain them by hand. If only part of the membership experience needs to be custom, you can also keep the standard built-in membership page on a separate portal page and link to it from your custom page instead of rebuilding every feature yourself.
Permissions
You need permission to design assets to write, save, publish, revert, and preview a custom component. You also need that permission to add, edit, or remove its fields and linked assets.