A User Guide For The Craft CMS Typed Link Field Plugin

Installing the Typed Link Field

Composer Installation

Installing the Typed Link Field plugin via Composer is the recommended method for most Craft CMS users. Composer is the dependency manager for PHP that allows you to bring in packages and plugins through a configuration file. By simply running a couple Composer commands, you can download and install the Typed Link Field plugin automatically without having to manually move any files around.

To install the plugin with Composer, first, make sure you have Composer set up and initialized for your Craft project. This is done by running composer init in your project's root directory to create the composer.json file. Once Composer is ready, you can then run composer require craftcms/typedlinkfield to pull in the Typed Link Field package from Packagist and install it. This will update your composer.json file and download the plugin into the vendor folder.

The benefit of using Composer is that it organizes all your PHP dependencies in one place. When you update Craft CMS or install new plugins, Composer handles all the file movement and organization behind the scenes. It also lets you easily update the Typed Link Field plugin later on, by running composer update craftcms/typedlinkfield when needed. Overall, Composer is the cleanest and simplest way to install the plugin.

Plugin Store Installation

Alternatively, the Typed Link Field plugin can be installed directly through the official Craft Plugin Store. This provides a more manual way of finding and installing plugins without having to use Composer dependencies. To install it this way, first log into your Craft control panel and navigate to Settings > Plugin Store. Search for "Typed Link Field" and select the plugin when it pops up.

On the plugin page, click the "Buy Now" button to purchase it if you haven't already. After purchase, head to Settings > Plugins in your Craft control panel, find Typed Link Field, and click the "Install" button. This will trigger the Plugin Store to download and install the plugin files automatically. While not as seamless as Composer, installing from the Plugin Store gives you a visual way to find and set up plugins from directly within your Craft CMS instance.

Manual Installation

For full control over the files, Typed Link Field can be installed manually by downloading the source files and transferring them via FTP or SSH. First, grab the latest zipped release from the Github repository and unzip it locally. Open your preferred FTP client or SSH into your server, then upload the typedlinkfield folder from the unzipped files into your craft/plugins directory.

With the files uploaded, navigate to your Craft control panel at /admin, go to Settings > Plugins, find Typed Link Field, and click "Install". This will complete the manual installation process. While manual install allows complete control, Composer or the Plugin Store are still preferable for their automation and ease of use. But for those who need it, manual install is a viable option.

Global Configuration

Validation Rules

The Typed Link Field plugin allows setting global validation rules that apply to all typed link fields across your Craft CMS site. This allows enforcing specific validation requirements for your links without having to configure each individual field.

For example, you can require that all typed link fields must have a title by enabling the setting "Validate field has title" under Typed Link Field Settings > Validation. Any typed link fields without a title set will then show a validation error.

Other handy global validation settings include requiring a URL, custom ID, link text, and link target. You can also validate that fields are not empty and enable "Propagate validation errors to the link field" to surface errors on the actual field.

By default, no global validation rules are set so each field behaves independently. But the global options allow setting sitewide validation standards for consistency and reducing errors on your links.

Field Propagation

When using Typed Link Field across multiple sites with Craft CMS multisite and locales in a Craft CMS installation, the global propagation settings control how field data is synced.

The default propagation mode is "Save locally, propogate globally" which updates the current site's fields while syncing those changes to all other sites. This ensures all sites share the same typed link data.

Alternatively, you can change propagation to "Save locally only" to isolate each site's field data. Then each locale will have its own independent typed links.

There is also a "Save globally" mode that skips the current site and only updates the global fields directly. This forces all sites to share identical content.

The propagation config can be tweaked as needed for your specific multi-site implementation. For most users, keeping the default propagation enabled is recommended to maintain the same links across sites while still allowing localized field changes.

Invalid Link Handling

When links become invalid due to URL typos or deleted pages, the plugin's global error handling settings determine how those bad links are dealt with in Craft CMS.

By default, invalid links will show a validation error on the front-end but won't break the whole page. You can change this to log errors instead, throw full errors, or force revalidate links on every page load.

For the frontend error message displayed, you can customize the error text and HTML class applied to give invalid links your own styling.

You can also enable "Propagate link errors to the field" to show errors on the field itself in the control panel when editing invalid links.

With these options, you can configure error handling that makes sense for your use case - whether allowing invalid links with warnings or fully breaking on bad links. Proper error handling ensures your site remains stable if bad links sneak in.

Creating Typed Link Fields

Field Settings

When creating a new typed link field in your Craft CMS control panel, you have several configuration options and settings to shape the field's behavior.

To start, every field needs a unique handle and name. The handle is the reference variable for the field while the name displays in the control panel.

You can set additional field options like:

• Instructions - Usage instructions displayed above the field

• Required - Makes the field mandatory

• Translation Method - Allows the field to be translated

• Default Value - Sets a default link

The "Validation Rules" tab allows setting field-specific rules like requiring a title or custom ID. This complements the global validation rules.

Other options like display format, column type, and more give full control over the field output and settings.

Overall, the extensive settings empower you to customize your typed links' behavior directly in the field definition.

Choosing Field Type

A key decision when creating typed link fields is choosing the allowed link types. The options include:

• Entries - Links to other entry pages

• Assets - Links to uploaded media assets

• Categories - Links to category archive pages

• Users - Links to user profile pages

• External - Links to outside URLs

• Email - Links to mailto: email addresses

• Tel - Links to tel: phone numbers

• Custom - Links to custom entry IDs

You can allow a single type like Entries, or multiple via the checkbox list. This determines what can be linked.

The default is External links for basic URLs. But unlocking Entries, Assets, and more enables rich internal linking between site content.

Be purposeful when picking allowed types based on the field's intended use case and link behavior needed.

Additional Field Options

Beyond the core settings, typed link fields support additional options useful for advanced use cases:

• Limit allowed targets - Refine valid links like limiting to a single Entry section

• Show field type icon - Displays the link type's icon marker

• Restrict allowed link types - Set validity based on other field values

• Custom font icon - Add a custom icon next to the field

• Minimum/maximum links - Limit how many links can be added

You can also create multiple link fields as a field group for relationships between entities like Users and Assets.

These advanced options extend what's possible when creating typed links in Craft CMS. Use them to tweak field behaviour and capabilities above the basics.

With the control over settings, types, and configurations - typed link fields can be tailored to any needed use case or content modelling requirements.

Working with Typed Link Fields

Editing Links

Once typed link fields have been created, editing the links inside the fields is done directly in the Craft CMS control panel.

To edit a link, navigate to the entry or content that contains the typed link field. Click on the field to open the link selection modal. Here you can change the link URL, link text, title, target, and other attributes.

For links to Assets, Entries, etc - click the "Find" button to open a browser modal to re-select that link target. For example, choosing a new Entry or Asset to link to.

You can also delete the entire link or add multiple links within a single field. New links can be created from scratch or by clicking the "Autofill" button to auto-populate based on existing content.

Overall, editing typed links is very intuitive from right inside the publish fields. Changes are saved automatically with no need to submit the form.

Displaying Fields

To output typed link fields in Twig templates in Craft CMS, use the {{ fieldHandle }} variable. For example:

<a href="{{ articleLink }}">{{ articleLink.title }}</a>

This will output the link URL in the href and link title as the text. You can also output properties like articleLink.url, articleLink.text, articleLink.target, etc.

If multiple links exist, loop through them:

{% for link in articleLinks %}

<a href="{{ link.url }}">{{ link.title }}</a>

{% endfor %}

You can also check if fields are required, validate values, and handle errors in Twig. Overall, typed links can be output just like any other field.

Field Validation

Typed link fields can be validated in the control panel when editing entries and content. Any required fields or validation rules set on the field will show errors if not met.

On the front end, validation errors will be returned when accessing the fields in Twig templates. You can also explicitly validate fields using:

{% set valid = articleLinkField.validate() %}

{% if not valid %}

<span class="error">Invalid link!</span>

{% endif %}

Validating at render-time ensures links remain valid.

The global plugin settings also allow controlling validation at a global level - enforcing validation rules across all fields site-wide.

Proper validation will catch any issues with malformed links or incorrect data entered into the typed link fields themselves.

Field Type Options

Common Field Types

The Typed Link Field plugin comes with a robust set of common field types that cover most standard website linking needs:

• Entries - Link to other entry pages on the site. Handy for cross-linking related content.

• Assets - Link to uploaded media like images and PDFs. Allows attaching downloads.

• Categories - Link to category archive pages. Useful for site navigation menus.

• Users - Link to user profile pages for attribution.

• External - Link to outside URLs. Covers basic links to other websites.

These give all the core field types you'd expect for linking around a Craft CMS site and off to external sites. They provide the flexibility to reference all kinds of content, pages, and resources.

Users & Emails

In addition to the standard options, Typed Link Field also supports:

• Users - Link to internal user profile pages based on username.

• Email - Link to mailto: email addresses for contacting users.

The user links are great for attributing content to authors. The email links enable adding "Contact Us" links that open the email client.

These specialized field types expand the options for internal linking focused on users and messaging.

Custom Field Types

For advanced customization, developers can create their own field types beyond what's included out-of-the-box.

This is done by hooking into the craft.typedlinkfield.types config setting and registering custom field classes.

Some ideas for custom types:

• Tags - Links that pull from a tag taxonomy

• Products - Links to internal product pages for ecommerce

• Custom Entries - Links limited to specific sections or entry types

The possibilities are endless when defining your own field types. Unique use cases and workflows can be addressed by leveraging customization.

So while the built-in options cover common needs, the plugin architecture allows expanding capabilities even further through custom field types.

Overall, the flexible options and extensibility create an adaptable linking solution for all kinds of requirements when building a website in Craft CMS.

Example Implementations

Linking Entries

A common use case for typed link fields is connecting related entries across sections in a Craft CMS site.

For example, you may have a "Blog" section with "Article" entries that should link to related "Case Study" entries in a different section.

By creating an "Related Articles" typed link field on the Article entries limited to the Case Study section, editors can easily build those connections across content.

The links are bi-directional so the Case Study can also link back to Articles. This creates an intuitive cross-linking experience between sections.

Linking Assets

Another handy implementation is linking to Assets like PDFs and images. An "Instruction Manual" typed link field on product pages could connect them to downloadable PDF manuals.

On blog posts, a "Featured Image" asset link field can pull in photos from the media library to display. The asset browser within typed link fields makes this linking process simple for editors.

You can also display Asset properties in templates like {{ manual.title }} and {{ featuredImage.url }} for additional utility when leveraging asset links.

Linking Products

For ecommerce sites, typed links can connect products by creating a custom "Products" field type.

This is done by registering a new field class that grabs products from a custom table. Then limit the field to only allow selecting between those product options.

This enables 关系 like linking product pages to related products for recommendations. Or creating links between product variants.

The customization potential really shines through on unique use cases like tailored product linking that extends beyond the out-of-the-box options.

As shown by these examples, typed link fields provide endless utility through their flexibility and extensibility - from standard to highly custom implementations.