Drupal How-To: Links

Table of Contents:

1. Types of Links

2. Linking in a WYSIWYG

a. Adding a Text Link

b. Adding an Image Link

c. Linking to Internal Content (Pages and Documents)

d. Linking to External Content

e. Opening a Link in a New Window/Tab

f. Styling a Text Link

3. Linking in Structured Fields

a. Linking to Internal Pages

b. Linking to Internal Documents

c. Linking to External Content

d. Opening a Structured Link in a New Window/Tab

4. Appendix: Screenshots

1. Types of Links

Links can point three different kinds of content:

• Internal pages – content that is hosted on the GC Drupal site

• Internal documents – PDFs or other documents in the Drupal media library

• External content - sites or pages that are hosted elsewhere on the web

Links can be added to freeform text content in a WYSIWYG, or in structured link/URL fields as part of a

component or template.

2. Linking in a WYSIWYG

Adding a Text Link

Most links added in WYSIWYG fields will be text links. Any piece of text in a WYSIWYG field can be

turned into a link, and can optionally be formatted with one of our preset link styles (as a button, for

example).

To add a text link (See appendix for screenshots):

1. In a WYSIWYG field, either insert or highlight the text you would like to turn into a link

2. Click the “insert link” icon in the text editor toolbar

3. Enter the destination of your link in the “URL” field (note that there are different formatting

guidelines for internal vs external links – see below for details)

4. Enter a brief description of the page or document you are linking to in the “Title” field – this is

important for accessibility and SEO

5. Click “Save” to apply the link.

Adding an Image Link

In addition to text links, you can also turn an inline image into a clickable link. The image must already

be placed within your text content in order to add a link.

To add an image link (See appendix for screenshot):

1. Click on the image within your text content to select it – the image will be outlined in blue when

selected

2. Follow steps 2-5 in the instructions above for adding a text link.

Note that we do not recommend using images to link to external content, as our template will

automatically add an external link icon next to the linked image, which in most cases will not display

cleanly. This is an area we are looking to improve in future development, but in the meantime please

limit your use of image links to internal pages and documents.

Linking to Internal Content (Pages and Documents)

Any webpage (including news items, events, and profiles) or media item that is hosted by the GC

Drupal site is considered internal content.

Drupal provides extra functionality for linking to internal content, which allows you to search for and

select your desired page or document to create a dynamic link. Dynamic links are tied to the unique ID

number associated with the page or document, rather than the direct URL that you would type into

your browser, and will not break if the page or document URL changes in the future. (This can happen

if a page is renamed or moved, or if a document file in the media library is replaced with a new

version.)

To link to internal content (see appendix for screenshots):

1. In step 3 of the instructions for adding a text link, begin typing the title of the page you would

link to link to in the “URL” field.

2. Drupal will look for any page and documents with matching titles and display them in a list

below the field. Click on the content item in the list to select it.

a. Pages will be listed under the “Content” heading, and documents will be listed under

the “Media” heading. Content will always be displayed first, followed by Media.

b. Note that if there are many matches you may need to scroll to find your desired content

item.

3. The URL field will populate with the dynamic link

a. For pages, this will be formatted as “/node/###” where ### is the unique ID number of

the page.

b. For documents, this will be formatted as “/media/###” where ### is the unique ID

number of the document

4. Continue with steps 4 and 5 above to finish adding your link.

Please note that this process works only for pages and document file types – the URL field will not

include images or other types of media assets.

Tips and Tricks:

For pages:

• Many pages on the GC site have similar or identical titles - for instance, nearly every program

has a page titled “Courses”. Refer to the administrative title (the terms in parentheses after the

page title in the autocomplete list) to help identify the specific page you would like to link to.

• If the list of matches in the autocomplete list is very long, or if you are having a hard time

finding the page you want to link to, you can use the following trick:

o In a separate tab or window, navigate to the page you want to link to on the GC site.

o Copy the page URL from the address bar in your browser, excluding the domain up to

.edu (for example, if the page URL is https://www.gc.cuny.edu/admissions-aid/how-

apply, copy only /admissions-aid/how-apply). Be sure to include the forward slash

immediately after “.edu”.

o Paste this partial URL into the “URL” field when inserting a text link – Drupal will find the

exact page it is associated with, allowing you to select it and generate the dynamic link.

For documents:

• The Drupal media library contains an enormous number of documents and finding the one you

want to link to in the autocomplete list can be challenging. You can improve the process by:

o Naming any documents you plan to upload to the media library so that they are easily

identifiable – avoid unnecessary abbreviations, and special characters use complete

words/terms that align with the document’s title, and use dashes or underscores to

separate individual words (NOT spaces)

 Example: Syllabus-History-72800-20th-Century-American-Foundations-2021.pdf

(good) vs Revised-Preliminary-Syllabus_12-30-20_ISBNs-added-

copy_history_syllabus.pdf (bad)

o Making sure that the file name and the media name (which you must enter upon

uploading the file to Drupal) match – it may be helpful to replace dashes/underscores

with spaces and remove the file extension.

o Being specific and complete when typing in the file name you are looking for in the URL

field – for example, if the filename for your document is “fall-2022-linguistics-

courses.pdf”, you will have better success by typing in “Fall 2022 Linguistics Courses”

rather than just “Courses” or even “Linguistics Courses”.

• If you are still unable to find the document you are looking for, you can use the following trick:

o Open the media library in a separate tab or window and use the search and filter

options to find your file

o Copy and paste the media name (NOT the file name) into the URL field. Drupal will find

the exact document it is associated with, allowing you to select it and generate the

relative link. (see appendix for screenshot)

Linking to External Content

Any site, page or document not hosted by the GC Drupal site is considered external content (including

anything hosted on other GC or CUNY hosting platforms, such as GC Website Services or the CUNY

Academic Commons).

For these links you should always include the full URL of the page or document you are linking to in the

“URL” field.

Note that our template will automatically add the external link icon (as in the External Link or External

Button style) to all links pointing to external content.

Opening a Link in a New Window/Tab

Be default, all links are set to open in the same window. Recommended best practice is to set external

links and links to documents/file downloads to open in a new window or tab, so that the GC site

remains active even if a visitor clicks on a link pointing elsewhere on the web.

To set a link to open in a new window (see appendix for screenshots):

• Follow the instructions to insert a text link through step 4.

• Before saving, click “Advanced” to expand the pane and display additional options.

• Check the box for “Open in new window/tab”

• Click “Save” to add your link.

Styling a Text Link

For text links only, you can choose to apply one of our preset styles using the “Styles” dropdown menu

in the text editor toolbar. (see appendix for samples)

• Text + Icon styles – add an icon to the right of the linked

text

o Download Link – for links to PDFs or other

downloadable media assets

o External Link – for links to external

webpages/sites

• Button styles –a blue button with a gray

mouseover/hover effect

o Button – the basic button style with no special

alignment; can be used inline in running

text/body copy

o Centered Button – a basic button, centered on

its own line

o Right Button – a basic button, aligned to the

right of the content area on its own line

o Download Button – adds the same download icon as the Download Link style

o External Button – adds the same external arrow icon as the External link style

3. Linking in Structured Fields

Many content templates and on-page components make use of standalone fields to insert

preformatted links in preset locations. In these fields you will enter the destination URL and, in some

cases, the desired link text, and all other styling and functionality will be determined by the template.

Examples of structured link fields include, but are not limited to:

• Content Templates

o Books – button link

o Profiles – personal website links under contact information

o Department Details/landing pages – social media links

• On-Page Components

o Checkerboard – button link

o Listing – text links below description

o Testimonial – text link below credit information

(See appendix for samples)

These fields are similar to the URL fields when inserting a link in a WYSIWYG, but have some additional

limitations when linking to internal content. See below for guidelines for using these fields properly.

Note that internal links in structured fields are an area we are looking to improve in future

development.

Linking to Internal Pages

For internal pages, much like the URL fields in a WYSIWYG, you can type or copy/paste the name of a

general page, news item, event, or profile, and Drupal will display a list of matches. Selecting a page

from this list will generate the dynamic link, formatted as “/node/###”.

However, unlike the field in a WYSIWYG, the structured link URL field will only display a maximum of

ten matching pages (see screenshot). This means that if there are more than ten pages on our site with

the same title, you may not see your desired match in the displayed list.

In these cases you will not be able to use the dynamic link, and will need to manually retrieve the

appropriate URL.

1. In a separate tab or window, navigate to the page you want to link to on the GC site.

2. Copy the page URL from the address bar in your browser

3. Paste this URL into the “URL” field.

Note that although not as secure as dynamic links, direct links are still somewhat insured against future

breakage, as Drupal automatically create an alias (a form of redirect) if the page URL changes. This

allows the page to remain reachable at its old URL. However, because these aliases can still break due

to accidental edits or removal, we recommend using the dynamic link format as much as possible.

Linking to Internal Documents

Unlike in a WYSIWYG, the URL field in structured links will not include documents in the autocomplete

list (see screenshot).

To link to document from one of these fields, you will need to manually retrieve the direct URL from

the media library (see screenshots):

1. Open the Drupal Media Library in a separate tab or window (hover over “Content” in the

toolbar, then click “Media Library”)

2. Use the search and/or filter options to find the document you would like to link to. (see our

Media Library guide for tips on finding media assets in the library)

3. Click on the document name to open the edit screen for the document

4. Right click on the filename in the middle of the screen and select Copy Link to copy the

document URL

5. Paste this URL into the “URL” field

Note that this link will not automatically update if the document is renamed or replaced with a

different version. You will need to manually update the link with the new document URL in these cases.

Linking to External Content

Links to external content in structured link fields should be entered the same way as in a WYSIWYG,

using the full direct URL of the site, page or document you are linking to.

Opening a Structured Link in a New Window/Tab

To set a link in a structure field to open in a new window/tab (see screenshot):

1. Click “Attributes” to expand the pane and display additional options

2. In the “Target” dropdown, select “New Window (_blank)”

4. Appendix: Screenshots

Adding a text link in a WYSIWYG field

Adding an image link in a WYSIWYG field

WYSIWYG Links - Link Pop-Up

WYSIWYG Links – Internal Content

Content (pages) vs. Media in the autocomplete list

Finding an internal document/media file

WYSIWYG Links - External Content

Opening a link in a new tab/window

WYSIWYG Links - Text Link Style Samples

Structured Links - Field Examples

Checkerboard Component

Listing Component

Social Media Links (Department Template, Profile Template)

Structured Links – Autocomplete URL Fields

Structured Links – Linking to Internal Documents

Structured Links – External Links

Opening a link in a new window/tab