Georgia Tech Drupal Handbook

Georgia Tech Drupal Handbook

This is the new and improved Georgia Tech Drupal Handbook that combines the old Drupal Editors Handbook and Drupal Developers Handbook into a single handbook with a hopefully more intuitive hierarchy.  This is a work in progress and will be undergoing further refinement over the next few months.

If you are looking for a specific topic, the site search tool should help.

Before editing or adding content, please review our editorial guide so that your contributions will mesh nicely with our existing articles.


Handbook Sections

klp Thu, 02/25/2016 - 17:20

Accessibility Requirements and Resources

Accessibility Requirements and Resources
Category
klp Mon, 02/24/2014 - 14:01
Drupal Version

Accessibility in short is the process of making websites and website content percievable and usable by people with disabilities.

With Georgia Tech receiving federal funding, all colleges, schools, research centers and other departments and divisions of the institute are legally required to adhere to the official accessibility standards defined in Section 508 of the Workforce Rehabilitaion Act.  These standards define how information is to be presented in websites and other online materials so that users with disabilities can still properly access that information.

As a good starting point for anyone creating web content, the Ivan Allen College has provided a short fifteen minute Accessibility Primer that addresses the most common problems and how to prevent or correct them.  It covers accessibility issues with images, headings, lists, page layouts, navigational aides, and handling audio and video content.  In addition, the WebAIM organization provides simple explanations of the general principles of accessibility.

For general resources, please see the Accessibility page on the Resources for Webmasters website.


Drupal Specific Resources

Make Your Pages Readable for People Who Are Blind

Make Your Pages Readable for People Who Are Blind
Category
afrank30 Wed, 12/11/2013 - 08:41
Drupal Version

TWO simple things you can do, which make your web pages easier to use for people who are losing their eyesight or are blind.

Eyes vs. Software

People who cannot see your actual page often use software called screen readers, which reads that page read aloud. This software reads pages differently than one might visually. But TWO simple changes in the way we edit web pages can make that difference easier to manage.

If you'd like to get a better understanding of how someone experiences the web when using screen reader software, watch the YouTube video below. Otherwise, you can skip to the first tip for making your pages more accessible.

[VIDEO::http://www.youtube.com/watch?v=VvWCnFjAGgo]

Describe Each Image With "Alternative Text"

Because the software cannot read images, any pictures or graphics on your website are big blobs of meaninglessness.

But don't worry, there's a way to add text to those images: "Alternative Text"!

When you are following the instructions on how to add an image to your page with the GT Editor, one of the final steps is to type descriptive words into the "Alternative Text" area of the image popup box. By describing what each image is supposed to communicate, you make it accessible. This is especially crucial when your image contains actual words (which, because they are part of an image, cannot be read as text by the screen reader).

How long should my Alt Text be?

While there is no official length restriction on the length of alt text, many experts recommend 125 characters or fewer because of restrictions within the JAWS screen reader. In addition, Google will stop reading alt text after 16 words.

Add Real Headings to Your Pages

Another way that people visually use your page is to quickly scan it to see what it is about. This is especially important on pages that have a lot of content!

To make it possible for screen readers to do the same thing and quickly skim your page's content, you need to provide an outline of your page using headings.

Headings are not just visual clues, but have special code behind the scenes. This means you cannot make text bold and have it work as a heading.

To make a real heading, first, highlight a line of text on your page that indicates another section or division of content on the page. Then, in your GT Editor toolbar, select the "Styles" option in the toolbar.

A list drops down underneath "Styles" and offers you a number of options, but the most important for your outline are these four:

  • Heading
  • Subheading 1
  • Subheading 2
  • Subheading 3

By choosing one of these headings, you are allowing the software to quickly scan the page for its users and read just the headings to them, so they can skim a page's contents just as one might do visually. Unless your pages are very long, you will probably only use the "Heading" and "Subheading 1" options with any regularity.

Resources for Drupal Site Editors and Content Managers

Resources for Drupal Site Editors and Content Managers

Step-by-step tutorials explain how YOU can can quickly update pages on any Georgia Tech Drupal Website without knowing any HTML. 

Learn to embed videos, share your news and events with the rest of campus, and more on your Georgia Tech Drupal-powered website!

For Drupal Express sites, please see the Drupal Express Handbook.


Site Editor and Content Manager Topics

root Mon, 03/11/2013 - 12:11

Logging Into Your Site

Logging Into Your Site
Category
jtomasino3 Mon, 03/09/2015 - 16:33
Drupal Version

Get Permission to Edit

To add or edit content on a Drupal site, the site's administrator has to give you special permissions, so send an email asking for this permission first.  The administrator may want to offer you some training first, or they might refer you to our community training pages.

Off-campus Changes Require VPN

If you are OFF CAMPUS, you will need to connect to the VPN before you can make changes if your website is hosted on OIT Web Hosting.  Because of the security system that OIT uses, you may be able to log in to your site without going through the VPN, but you often cannot save any changes you try to make.

Using Your GT Account Username to Log In

Many campus Drupal sites (and all Drupal Express sites) are configured so that authorized editors can log in with their usual GT account username (e.g. gburdell3).  Sites configured this way will either log you in automatically (if you are already logged into your GT account username in your current browser session), or send you to the central campus login page.  If you are shown a login prompt that isn't the standard central campus login page, contact your website's administrator to find out how to access your unit's website.

Web Addresses for Logging In

If you need to log in to your site after its initial installation, go to either:

  • http://yoursite.gatech.edu/user
  • http://yoursite.gatech.edu/?q=user

Of course, be sure to replace 'yoursite.gatech.edu' with the actual hostname for your website.

Alternatively, if your site is a Drupal Express site, you can look for a Login link in the gold Georgia Tech footer bar at the bottom of any page.

Creating and Managing Pages

Creating and Managing Pages
Category
afrank30 Wed, 09/03/2014 - 14:59
Drupal Version

This section contains guides to creating and managing content pages in Drupal.  Please see the Editing Page Content section for details on how to create and edit page content using CKEditor, the popular What You See Is What You Get (WYSIWYG) text editor, which on some sites is packaged as the GT Editor.  Additional content editing topics can be found in our All About Blocks section and our Photos and Videos section.

Whenever you create content, please be sure to follow proper accessibility practices.  The Ivan Allen College of Liberal Arts has posted a helpful Accessibility Online Course and a Web Accessibility Primer for quick reference.


Drupal Page Creation and Management Sub-Topics

Page Layouts and Content Types

Page Layouts and Content Types
Category
root Mon, 03/11/2013 - 13:07
Drupal Version

Basic Content Types (Built Into Drupal)

Basic Page

A web page has unique content that should usually have a link from the main menu (the top, gold menu in the new design). A page may contain documents, images, or just regular text. Use basic pages for your static content, such as an 'About us' page.

Block

A block usually looks like a box, contains text or images, and can be shown on one or many pages. You often see a block floating on either the right or left side of a page. The GT Theme offers a number of preset block layouts and block styles.

Georgia Tech Custom Page Layouts

If your site is using the GT Theme, and has had the custom GT Content Types page layouts module installed, you will also have three additional ways to organize content on your pages.  Every field (such as a row of blocks) that comes with each of these layouts is optional, so you can pick and choose just what you need for a particular page.

Horizontal landing page

This layout is most often used for homepages.

It allows up to four horizontal rows of blocks to be added below the main body text.

Vertical landing page

This layout is often used to show related content to whatever is at the top of the page.

It creates two vertical columns for blocks that can be added below the main body text.

Multipurpose page

Your Swiss army knife of page layouts, this layout works well for breaking up content-heavy pages into separate sections.

It provides three separate fields for body text, each with:

  • a horizontal block row beneath it, and
  • a sidebar beside it.

Switching Layouts

If you need to change from one layout to another, it is best to engage your website developer / administrator, as this process requires special privileges on many Drupal sites, and even on sites where a content editor can switch layout types, there is a risk of losing your content if you don't do the conversion properly.

Drafts, Publishing, and Revisions

Drafts, Publishing, and Revisions
Category
esembrat3 Mon, 12/17/2012 - 13:00
Drupal Version

About Drafts and Revisions

If your site has Revisioning installed and turned on (a standard feature for Drupal Express sites), then the following concepts will apply:

  • After you have created or edited a page or block, it is saved as a draft.
  • Every time you make a change to a page or block and save it, you create a new revision.
  • In order to see your new content on your website, you must publish it.

The great thing about revisions is that you can compare versions and even revert back to an earlier version.

Viewing, Editing, Comparing, and Deleting Revisions

  1. Navigate to the page you want to publish. Select the "Revisions" tab at the top of the page.
  2. The last version of your page will be the first one on the list. If you have not yet published it, it will be highlighted in pink with the words, "In Draft/Pending Publication" in the "Status" column next to it.
  3. Select the date link to view your draft. Now you can edit the latest version, compare it to the version that is currently published, delete it, or publish it.

Publishing Drafts

  1. Navigate to your draft by following the steps above, OR, if you have just saved your page, the "Publish" button should appear at the top of the page.
  2. Select the "Publish" button.
  3. Select the "Publish" button to confirm that, yes, you really do want to make this revision go live.

Unpublishing Revisions

  1. Select on the "Revisions" tab at the top of the page.
  2. Select on the date of the draft/revision you want to unpublish in the Revision table, which will probably be the most recent revision at the top, and will say, "Current Revision (Published)" in the Status column next to it.
  3. Above the Revision table, select the "Unpublish Current Revision" link
  4. On the next page, select the "Unpublish" button to confirm that you do indeed want to unpublish this page.
  5. Select the save button.

Adding a Page

Adding a Page
Category
jtomasino3 Wed, 03/25/2015 - 22:16
Drupal Version

Process for Adding a Page

  1. After logging in to your website, you will see a black menu bar across the top (if you do not see a black menu bar, contact your site administrator for assistance).
     
  2. Select the Content menu, then Add contentYou will see a list of different types of content that you can add. If your site is using the custom GT Content Types,  and you are adding a top-level (AKA landing) page, we recommend that you choose Multipurpose page, as this will give you the most options for formatting and layout.  If your site is not using GT Content Types, or if you are creating an inside page that doesn't need a lot of special formatting, you should choose Basic page.
     
  3. Type your page title into the Title field.
     
  4. Scroll to the very bottom of the page and select URL Path Settings. If your site has the option, you can either check the "Automatic Alias" box, or type in your own. To create your own, you should use the page title, or some variation of it. This will be used in the page’s URL. Always use lowercase letters and dashes between words. Do not end your alias with a “/”
     
  5. To add breadcrumb links and/or to have the page show up in your website menu, go to Menu Settings. Check the "Provide a Menu Link" box. The Menu Link Title field will automatically populate with your page title. You can change it if you'd like. Next, decide what menu you want this page added to, by selecting it from the "Parent Item" drop-down list. If you want this page to be a main menu item in the gold bar, select, "Main Menu."
     
  6. Select the Save button, and you’re done.

Adding Content to the Page

  • You can now scroll back up the page and start adding content, or you can return to it later, by locating the page in the Content List.
  • Learn how to add content to a Multipurpose page in this tutorial [add link].

Creating and Editing Page Content

Creating and Editing Page Content
Category
root Fri, 07/14/2017 - 17:38
Drupal Version

This section contains guides for creating and editing page content using CKEditor, the popular What You See Is What You Get (WYSIWYG) text editor, which on some sites is packaged as the GT Editor.  Additional related guides can be found in the Creating and Managing Pages section, and additional content editing topics can be found in our All About Blocks section and our Photos and Videos section.

Whenever you create content, please be sure to follow proper accessibility practices.  The Ivan Allen College of Liberal Arts has posted a helpful Accessibility Online Course and a Web Accessibility Primer for quick reference.


Content Editing Sub-Topics

CK Editor / GT Editor Toolbar Control Buttons

CK Editor / GT Editor Toolbar Control Buttons
Category
root Thu, 07/13/2017 - 12:12
Drupal Version

Many campus Drupal websites have either the What You See is What You Get (WYSIWYG) text editor called CKEditor, or the custom built specialized version of CKEditor known as "GT Editor".

The table below describes many of the control buttons you will find on the CKEditor or GT Editor toolbar.  If your control buttons don't look like these, you should ask your site administrator or local web developer to look into upgrading your site to the latest version of CKEditor.

Note: The control name can be seen by hovering over the control, and is what should be heard when working with accessibility technology.

Note: It is possible that your site administrator may have removed or rearranged control buttons or added ones not described below.  In addition, Drupal 8 sites will not have all of the buttons below by default, as Drupal 8 comes with a minimal functionality version of CKEditor.

Control Button Image Control Button Name Additional Notes
Maximize Maximizes the editor in the browser window so you can see more of your content while editing.
Styles Formatting Styles Lets you apply pre-defined combinations of various formatting styles to text.
B Bold  
I Italic  
X2 Superscript  
X2 Subscript  
Insert Special Character  
Insert Teaser Break Creates an invisible break to tell Drupal that everything above the break (and nothing below it) should be shown when this page is shown in a search listing or Views listing.
Insert Horizontal Line  
Insert/Remove Bulleted List  
Insert/Remove Numbered List  
Decrease Indent In a numbered or bulleted list, moves the current item up a level (further to the left)
Increase Indent In a numbered or bulleted list, moves the current item down a sub-level (further to the right)
Table Lets you create and configure a table
Image Lets you insert an image into your content
Link (to content) Link to other pages, uploaded files, other websites, etc.
Unlink Removes a link from text, returning the text to normal text.
Anchor Create a link anchor in your text, which can be used to send users directly to that part of the page.
Paste from Word Tries to preserve formatting and strip unnecessary markup when pasting in content from Microsoft Word
Source Source View and/or edit the HTML source code for your content.

 

GT Theme Content Styles List

GT Theme Content Styles List
Category
afrank30 Thu, 12/19/2013 - 13:40
Drupal Version

If your site is using the official GT Theme and the GT Editor module, then you should have a Styles drop-down option in the toolbar of your WYSIWYG (GUI) text editor (AKA CKEditor) with the following formatting styles.  If you are not using both the official theme and the GT Editor module, then you will not see any of these styles (and may not even see the Styles drop-down option).

"Block" styles

"Block" styles describes HTML elements or containers which do NOT sit next to each other on a line, but "own" the entire page's width for the lines they fill.

Basic HTML Styles

These first options are mainly headings, so you can add visual (and invisible) outlines to your pages and make it easier for people to scan them quickly.

  • Heading <h3>
    • Subheading 1 <h4>
    • Subheading 2 <h5>
    • Subheading 3 <h6>
  • Preserve format <pre>

Image and Media Styles

Mostly, these options style images within your pages. They work best when you place your image on its own line, and not inside a paragraph.

  • Float Left: moves your image to align with the LEFT side of the page and makes other text wrap around your image on the same lines it occupies.
    • Float Left - Simple
    • Float Left 70%
    • Float Left 50%
    • Float Left 30%
  • Float Right: moves your image to align with the RIGHT side of the page and makes other text wrap around your image on the same lines it occupies.
    • Float Right - Simple
    • Float Right 70%
    • Float Right 50%
    • Float Right 30%
  • Clear Floats: forces text to NOT wrap around your image, so that the image has lots of white space on either side of it.
    • Clear Float Left
    • Clear Float Right
  • Embedded Media Wrapper: not currently used, but may one day make videos more responsive on various sizes of device.

For Themers: these apply a <div> with a special class around the selected image or media. That <div> may replace the <p> element if your image is within a paragraph, leading to incorrect styling. This is intentional, as every Float style (except for those ending in "Simple") is designed to provide special styling to any text that accompanies your Floated image.

Paragraphs, Buttons and Links

Add visual enhancements to paragraphs or turn small phrases or a short sentence into a special button or link.

  • Intro Text: makes a paragraph's font size and line spacing larger (designed to be used only for the FIRST paragraph on a page).
  • Yellow Highlight Button
  • Blue Highlight Button
  • Jump Link

For Themers: these apply a <p> with a special class around the selected text.

"Inline" styles

"Inline" styles describes containers which are designed to sit next to each other on the same line and usually occur within a paragraph.

Basic HTML Styles

  • Computer Code <code>
  • Cited Work <cite>
  • Inline Quotation <q>
  • Block Quotation <blockquote>

Pull Quotes

  • Pull-quote - Left: styles a sentence as a large quote on the LEFT side of the page.
  • Pull-quote - Right: similar to above, but on the RIGHT side of the page.

For Themers: these apply a <blockquote> with a special class around the selected text.

File Types

Add icons to your selected text, which show pictures of the related file type.

  • PDF Icon
  • MS Word Icon
  • MS Excel Icon
  • MS PowerPoint Icon
  • Generic File Icon

For Themers: these apply a <span> with a special class around the selected text.

Adding Images to a Page in GT Editor (IMCE)

Adding Images to a Page in GT Editor (IMCE)
Category
root Thu, 07/13/2017 - 13:35
Drupal Version

The following instructions are for adding an image or picture to a page when your site is using GT Editor or otherwise has the IMCE module installed.

Important!  Be sure to properly resize your image file before you upload it to your site.

  1. Place your text editing cursor where you want to be located within your content
    • If you want the image on it's own line, create that blank line and place the cursor on it
    • If you want the image to float left or right of existing text, place your cursor at the beginning of that line of text
  2. Select the Image button in the editor toolbar (it looks like a painting of an outdoor landscape with a mountain and a little sun in the upper-right corner).
  3. In the pop-up control panel, select the Browse Server button to the left of the URL field.
    • If you do not see a Browse Server button, then your site is not configured with the IMCE module, and the following instructions do not apply to your website.
  4. In the next pop-up control panel that appears, navigate to the folder where you want to save your uploaded image or a folder that already contains a file that you wish to use for your link.  To upload a new file to your chosen folder:
    1. Select the Upload toolbar button, and then use the resulting controls to find and select the correct file on your local computer.
    2. Once you have selected a file, select the Upload button that appears below the Create thumbnails option (not the Upload button above in the toolbar).
    3. Your newly uploaded file should appear in the folder file list.
  5. Select your chosen or uploaded file to highlight it, then select the Insert File button from the toolbar.
  6. You will now be returned to the first pop-up control panel, and you should see a filesystem path in the URL field.
  7. If your image is conveying something important to your website users (i.e. the image is not purely decorative, meaning you could remove it and users would still get the same message from the page), then you need to enter a short description of the message conveyed by the image in the Alternative Text field.
  8. If you want your image to float left or right of your existing text, then select the appropriate option for the Alignment field.  You may also need to add a little horizontal or vertical spacing by entering a small numeric value (usually 10 works) for the HSpace and / or VSpace fields.
  9. When you are finished, select the OK button to place your image into the page.

Adding Tables to a Page with GT Editor / CKEditor

Adding Tables to a Page with GT Editor / CKEditor
Category
root Thu, 07/13/2017 - 17:07
Drupal Version

When (and When Not) to Use a Table

Tables should only be used for the display of tabular data (data that is connected to one or more headings).

Do not use tables for any of the following reasons:

  • Displaying a list of items (use an unordered or ordered list instead)
  • Creating a multi-column page layout (use proper page layout tools instead)

If you are not sure about how to present a certain type of information, please check with your communications manager, your website developer, or even the Georgia Tech Drupal Mailing List for assistance.

How to Place and Configure a Table Using GT Editor or CKEditor

  1. Place your cursor where you want the table to appear.
    • If you want the table on it's own line, create that blank line and place the cursor on it
    • If you want the table to float left or right of existing text, place your cursor at the beginning of that line of text
  2. Select the Table button in the toolbar: 
  3. In the pop-up control panel, fill in the fields as appropriate:
    • For Rows and Columns.  (You can adjust this again later if needed.)
    • Leave the Width field blank to allow for automatic sizing of the table, or enter 95% to force a full-width table with a little bit of right-hand spacing
    • Set Headers to something other than None.  All tables must have at least one row or column of headers (if not both) to be compliant with accessibility laws.
    • To float the table to the Left or Right of existing content, select the appropriate option under Alignment
    • Under Summary, enter a short summary of what the table represents and what message you expect your website visitors to get from the data in the table.  This is very important for people with vision disabilities who cannot directly view the table and thus cannot see the visual arrangement of the data.
    • Use the Caption field to give the table a visible title.  If the caption can properly summarize the intent of the table and its data, then you could use it alone and leave Summary blank, but at least one or the other should be used (and you can use both, if that works best for your needs).
  4. Select the OK button and you should see your empty table generated within the content of your page.
  5. Now, you can add content to each cell of the table by clicking on or tabbing to a cell.

How to Modify an Existing Table

You can modify the configuration of an existing table by right-clicking on the table and using the pop-up contextual menu.  Through this menu,  you can add columns, add rows, manipulate individual cells, and adjust the display and formatting settings for the table.

Available table contextual menu options:

  • Paste
  • Cell ->
  • Row ->
  • Column ->
  • Delete Table
  • Table Properties

Creating Links in CKEditor

Creating Links in CKEditor
Category
root Thu, 07/13/2017 - 17:33
Drupal Version
Tags

This page covers the creation of different types of links using the standard CKEditor link tool.  If your website is using the GT Editor or otherwise has the Linkit module installed, then you will have some additional options as described on the Creating Links in GT Editor (Linkit).

Accessibility and Usability of Links

To comply with accessibility law, and good sense usability guidelines, always make the visible text of your link something that clearly indicates what the website visitor is going to be taken to when following that link.  Some examples of improper link text include:

  • Click Here
  • Here
  • Read More
  • More
  • Follow This Link

Wording like these give the user no indication of what you are linking them to, and this is really bad for users with vision disabilities who utilize screen readers.  As a matter of speed and efficiency, these users often have the list of links on a page read aloud without their supporting context.  Hearing "Click Here" ten times makes it impossible for these users to know which link is which, and thus they will be unable to navigate through the links on your page.

While you can make an image into a link, it is best to only make text into links, or to link both an image and an equivalent piece of text together as a link so that you always have some plain text describing the destination of your link.  If you really only want to make an image into a link, then you must set the Alternative Text field of the image to a description of where the link is going to take the user.

Drupal 7

CKEditor in Drupal 7 has a variety of options available.  It is best to only use the ones described below:

Adding a Link

  1. Highlight the text that you want to turn into a link.
  2. Select the Link control button on the toolbar:
  3. Select the type of link you want to add in the Link Type drop-down:
    • URL: Links to another page in the current site, or an external site:
      • Enter the URL into the URL field.  The Protocol field will automatically adjust itself.
      • Enter links to pages on the current website as relative URLs, which do not include the server name:  /undergraduate/minors
      • Enter links to pages on the a different website as fully qualified URLs, which include the server name:  http://mysite.gatech.edu/undergraduate/minors
    • Link to anchor in the text: If you have already placed anchors in the current page, this will let you select one of them and create a jump-link to that anchor point
    • E-mail: This will let you easily create a link that invokes the user's default email program to send an email to a designated email address:
      • Fill in the E-Mail Address, Message Subject, and Message Body fields as desired.  Only the E-Mail Address is required, and bear in mind that the user can easily change the subject and body text in his/her email client - what you provide here is just a suggestion to the user.
  4. Select the Save button and your highlighted text should now be a link.

Please note that you cannot follow a link while in CKEditor.  You must either Preview your page or Save the page and return to View mode to be able to follow any of your links.

Removing a Link

  1. Put your text cursor somewhere within the linked text.
  2. Select the Unlink control button:
  3. The link will now be gone, though the text will remain.

Drupal 8

If you are working with a Dupal 8 site, you will find that it's version of CKEditor has taken a minimalist approach, so the instructions are really simple:

Adding a Link

  1. Highlight the text that you want to turn into a link.
  2. Select the Link control button on the toolbar:
  3. Enter the URL of your link into the URL field of the pop-up contol panel and select the Save button and your highlighted text should now be a link.

Please note that you cannot follow a link while in CKEditor.  You must either Preview your page or Save the page and return to View mode to be able to follow any of your links.

Removing a Link

  1. Put your text cursor somewhere within the linked text.
  2. Select the Unlink control button:
  3. The link will now be gone, though the text will remain.

Creating Links in GT Editor (Linkit)

Creating Links in GT Editor (Linkit)
Category
root Thu, 07/13/2017 - 18:01
Drupal Version
Tags

If your Georgia Tech Drupal website has the GT Editor feature package installed, then it also has the Linkit module, which gives you an enhanced interface for creating links to local content.

Accessibility and Usability of Links

To comply with accessibility law, and good sense usability guidelines, always make the visible text of your link something that clearly indicates what the website visitor is going to be taken to when following that link.  Some examples of improper link text include:

  • Click Here
  • Here
  • Read More
  • More
  • Follow This Link

Wording like these give the user no indication of what you are linking them to, and this is really bad for users with vision disabilities who utilize screen readers.  As a matter of speed and efficiency, these users often have the list of links on a page read aloud without their supporting context.  Hearing "Click Here" ten times makes it impossible for these users to know which link is which, and thus they will be unable to navigate through the links on your page.

While you can make an image into a link, it is best to only make text into links, or to link both an image and an equivalent piece of text together as a link so that you always have some plain text describing the destination of your link.  If you really only want to make an image into a link, then you must set the Alternative Text field of the image to a description of where the link is going to take the user.

Creating Links to Pages Within Your Site

  1. Highlight the text that you want to turn into a link.
  2. Select the Link control button on the toolbar: Image removed.
  3. If your site has Linkit installed, then the pop-up panel should have two fields: Search for content and Link URL along with a Insert Link button.  If your pop-up panel doesn't have these fields and button, then you'll need to follow the instructions for Creating Links in CKEditor.
  4. In the Search for content field, begin typing any word(s) from the title of the page you would like to link to.  As you type, a drop-down box should open up and show you any pages whose titles have the word(s) you have entered.  Simply select the page you want from the list.
  5. As a confirmation, you should see a URL path appear in the Link URL field after you have selected a page.
  6. Select the Insert Link button to create your link.

Creating Links to Pages on Other Sites

  1. Highlight the text that you want to turn into a link.
  2. Select the Link control button on the toolbar: Image removed.
  3. If your site has Linkit installed, then the pop-up panel should have two fields: Search for content and Link URL along with a Insert Link button.  If your pop-up panel doesn't have these fields and button, then you'll need to follow the instructions for Creating Links in CKEditor.
  4. In the Link URL field, type in the fully qualified (starts with "http://" or "https://") URL for the page to which you want to link.
  5. Select the Insert Link button to create your link.

Creating Links to Uploaded Files

Note: A "file" can be anything that can be reasonably opened in a web browser or which your site users would want to download to their own computer: a Word Document, a PDF file, an image file, etc.  For the greatest level of usability, consider turning any kind of office related document into a PDF, as PDFs can be opened on virtually any computer or mobile device without needing any additional software.

Note: These instructions require that your site be running the GT Editor feature package or otherwise have both the Linkit and IMCE modules installed.

  1. Highlight the text that you want to turn into a link.
  2. Select the Link control button on the toolbar: Image removed.
  3. If your site has Linkit installed, then the pop-up panel should have two fields: Search for content and Link URL along with a Insert Link button.  If your pop-up panel doesn't have these fields and button, then you'll need to follow the instructions for Creating Links in CKEditor.
  4. Select the Open file browser button below the Search for content field.
    • If you do not have an Open file browser button, then your Drupal site does not have the IMCE module installed.  Stop and contact your site administrator or developer for further assistance.
  5. In the next pop-up control panel that appears, navigate to the folder where you want to save your uploaded file, or a folder that already contains a file that you wish to use for your link.  To upload a new file to your chosen folder:
    1. select the Upload toolbar button, and then use the resulting controls to find and select the correct file on your local computer.
    2. Once you have selected a file, select the Upload button that appears below the Create thumbnails option (not the Upload button above in the toolbar). 
    3. Your newly uploaded file should now appear in the folder.
  6. Select your chosen or uploaded file to highlight it, then select the Insert File button from the toolbar.
  7. You will now be returned to the first pop-up control panel, and you should see a filesystem path in the Link URL field.
  8. Select the Insert Link button to create your link.

Photos and Videos

Photos and Videos
Category
esembrat3 Mon, 02/18/2013 - 10:34
Drupal Version

The sub topics below provide information on how to make use of images/photos and videos on your Drupal websites.  Of course, the first step to adding photos or videos is obtaining good quality content.  While just about anyone can take high resolution pictures quickly and easily these days with a cell phone, you may wish to look through the Georgia Tech Digital Image Portal, which contains professional quality photographs for which Georgia Tech owns the copyright (Image Portal tutorial videos are available to help you get started.)

Good video content takes a bit more time to produce, but Institute Communications has provided some guides to producing and distributing videos at Georgia Tech.


Photo and Video Sub-Topics

Resizing Images

Resizing Images
Category
root Thu, 06/29/2017 - 18:29
Drupal Version

It is important to resize images to best fit the needs of a particular web page.  When an image is larger than necessary, this results in users wasting time and bandwidth (which they may have to pay for on mobile devices) to download image content that they will never actually see.

These days, photographs straight from a digital camera may be over 4000 pixels wide, which is much too wide for a web page.  Even if you are creating a photo gallery, most desktop monitors can only display around 2000 pixels in width.  So, you need to reduce the size of these images before uploading them to your website.

Image Resizing Guidelines

  • If you try to make a small image larger, it will simply become fuzzy (AKA pixelated), and the larger you make it, the fuzzier it will become.  However, you can easily make a large image smaller when needed.

  • For basic website pages, 400 pixels wide images are a good best-practice. For mobile compatibility, choose a width for your image that is less than 400 pixels.

  • If uploading large images for the press to use, your resolution should not be higher than 300ppi (pixels per inch) and the image should not be more than 3,000 pixels on it's longest side. If these images are not for the press, but are used as full-page-width decorations, you should make them even smaller.

  • If you are uploading an image for a headline / hero image (an image at the top of a main landing page that fills the page left to right), resize your image to no more than 1440 pixels wide.

  • When making an image smaller, don't sacrifice the quality of the image.  Instead, simply change the pixel length/width of the image.

  • Also, be sure to check "Scale proportionally" or "Maintain aspect ratio", so that your picture does not get skewed to where people have extra-wide heads that look strange.

How to Resize Images

Of course, you can use any graphic image editing program that you are comfortable with, such as Adobe PhotoShop, GIMP, etc.  If you are not sure how to resize images in one of these editors, just do a search in your favorite search engine on the editor's name and the phrase "resize image".

Adding Video to a Drupal Page

Adding Video to a Drupal Page
Category
root Thu, 06/29/2017 - 18:43
Drupal Version

The following instructions assume that you have the Video Embed Field module installed on your Drupal 7 site.  This is included on any Drupal Express site, but may not be installed on other Drupal sites found on campus.

Note: For best results, try not to put more than three videos on one page.

Embed a Video from YouTube

  1. Go to the video on YouTube.
  2. Beneath the video, select the "Share" link.
  3. Copy the URL.
  4. On your Drupal site page, type in the following shortcode, replacing your-url-here with the URL you copied from YouTube:

[VIDEO::your-url-here]

Example:

[VIDEO::http://www.youtube.com/embed/98nNpzE6gIs?rel=0"&autohide=1]

Don't forget to save your changes!

All About Blocks

All About Blocks
Category
afrank30 Wed, 09/03/2014 - 15:02
Drupal Version
Tags

The following pages explain how to create and work with different types of Drupal blocks.


Block Sub-Topcs

Block Layouts and Widths

Block Layouts and Widths eh94 Mon, 11/04/2013 - 15:07
Drupal Version
Tags

If you have access to manage blocks on your Drupal site, the following tips and tricks may help you achieve better positioning of your blocks.

Automatic Re-Sizing and Regions

Blocks that are placed within the main content regions of a horizontal, vertical or multipurpose page (only available if you have installed the custom Georgia Tech Content Types package) will automatically resize, based on number of blocks in that region. Regions whose blocks behave this way include:

  • Area ABOVE Main Content (IGNORES sidebar regions)
  • Area ABOVE Main Content (RESPECTS sidebar regions)
  • Main Content
  • Area BELOW Main Content (RESPECTS sidebar regions)
  • Area BELOW Main Content (IGNORES sidebar regions)

Choose your Width

There are also block layout options that you can use to change a block's default width. You'll find these in the Layout drop-down list when you are creating or updating a Block:

  • Full width
  • Three quarter width
  • Two thirds width
  • Half width
  • One third width
  • One quarter width

For instance, you could have four blocks that sit side-by-side, but then apply the "Full width" layout option to the fifth block so that it extends the full width of the region, rather than sitting there like a misplaced element.

Remember: these widths apply to a block WHEREVER it is shown. So, if you need the same content to display differently on different pages, you may need to create a separate block for each look.

Screen Size and Number of Horizontal Blocks

Blocks will have different limits on number shown per row, based on the screen size of the device used to view your site.

  • For a desktop computer view of your site: regions are limited to four blocks next to each other (horizontally), after which additional blocks will break and start a new row.
  • On smaller screen sizes (such as tablets): blocks will stack two or three horizontally.
  • On the smallest viewports (such as smartphones): blocks will stack on top of each other (vertically), instead of next to each other (horizontally).

Clear Floats to Prevent Collisions

There is also a "Clear floats" checkbox available, useful for preventing block collisions due to varying content heights within each block.

An example problem might be a block in a lower row colliding with a block in the row above it, due to the content of the block in the upper row causing it to sit higher than its adjacent blocks. Just apply the clear floats option to the lower block and it will no longer collide with the block above.

Block Regions

Block Regions root Thu, 06/29/2017 - 17:57
Drupal Version
Tags

Block Regions are areas on a Web page where blocks can be placed. Using Block Regions to place blocks on a page is different than adding blocks directly to a Horizontal Landing Page, Vertical Landing Page, or Multipurpose page.

Available Block Regions in the GT Theme

The following regions are available in the GT Theme.  If you are using a different theme, it will likely have a different set of regions.

  • Spotlight area in header typically used for home page carousels
  • Area ABOVE Main Content (IGNORES sidebar regions)
  • Left Side Menu (displays above all other content in Left Sidebar)
  • Left Sidebar
  • Site help content
  • Area ABOVE Main Content (RESPECTS sidebar regions)
  • Main Content
  • Area BELOW Main Content (RESPECTS sidebar regions)
  • Right Sidebar
  • Area BELOW Main Content (IGNORES sidebar regions)

Visual Demonstration of Block Regions in the GT Theme

Addding Design Elements to Blocks with "Styles"

Addding Design Elements to Blocks with "Styles" afrank30 Fri, 01/03/2014 - 10:50
Drupal Version
Tags

If your site is using the GT Theme, and has had the custom Georgia Tech Page Layouts package installed, then when adding a new block, or editing an existing block, you can make your blocks look fancier than a standard Drupal block.  This is done by selecting a custom style via the checkboxes under the "STYLING" section at the bottom of any block configuration page.  The available styles are:

  • BLOCK STYLE: promo block
  • BLOCK STYLE: related info block
  • ICON: Information
  • ICON: Alert
  • ICON: Download
  • ICON: Link
  • ICON: Institution
  • ICON: Mortar Board
  • BLOCK TITLE: GT Gold
  • BLOCK TITLE: GT Blue
  • BLOCK TITLE: Gray

BLOCK STYLE: promo block

This style formats your block title on a transparent background and the rest of the block on a grey background with gold top and bottom borders.

BLOCK STYLE: related info block

This style formats your block title on a gold background and the rest of the block on a grey background.

ICON: Information

This style formats your block title with an 'i' information icon before the title and a gold border below the title.  The body is styled as a normal Drupal block.

ICON: Alert

This style formats your block title with an exclamation point icon before the title and a gold border below the title.  The body is styled as a normal Drupal block.

ICON: Download

This style formats your block title with an down arrow icon before the title and a gold border below the title.  The body is styled as a normal Drupal block.

ICON: Link

This style formats your block title with an arrow icon (pointing to the upper right) before the title and a gold border below the title.  The body is styled as a normal Drupal block.

ICON: Institution

This style formats your block title with a Greek / Roman building icon before the title and a gold border below the title.  The body is styled as a normal Drupal block.

ICON: Mortar Board

This style formats your block title with a graduation mortar board icon before the title and a gold border below the title.  The body is styled as a normal Drupal block.

BLOCK TITLE: GT Gold

This style formats your block title with a gold background.  The body is styled as a normal Drupal block.

BLOCK TITLE: GT Blue

This style formats your block title with a blue background.  The body is styled as a normal Drupal block.

BLOCK TITLE: Gray

This style formats your block title with a grey background.  The body is styled as a normal Drupal block.

Making Super Blocks

Making Super Blocks afrank30 Fri, 12/12/2014 - 14:15
Drupal Version

Super Blocks are only available if your site has the Georgia Tech Super Block module installed.

Creating a Super Block

To start making a new Super Block, use the Administrative toolbar (the black bar across the top of your site). Choose Content > Add content > Super Block.

After the new Super Block form opens, you can enter your information into the fields described below.

Title and Description

Description

  • Example Description 1: "Block - Homepage - Bachelor's Programs"
  • Example Description 2: "Block - About Section - Contact Information"
  • The Description field is always required.
  • Only you and other editors of the site will see the "Description" field; it will be used for the block reference fields on layout pages (such as in the Article or Aside areas on a Multipurpose page.)
  • Be concise, but describe each block in a way that is easy for your fellow editors to sort through later (because you will probably have a long list of blocks) .
  • Consider using a pattern for naming your blocks that indicates what type of content it is, what parts of your website it will probably appear on, and then the specific content in this block.

Title

  • Example Title: "Bachelor's Programs"
  • The Title is optional.
  • If used, visitors to your site will read the Title as a very short text headline at the top of a Super Block.
  • You can use <em>, <strong>, and <br />, tags in the title if needed. Just don't forget to close <em> and <strong> tags! (i.e., <strong>Strong Title</strong>)

The Teaser and Image

​​Teaser Text

  • This field is optional, but can be used to include text or a blurb about the image in your Super Block.
  • It can also be used instead of an image, if only want to include text and links in your Super Block.

Primary Image

  • The Primary Image is optional, but is the heart of what makes super blocks so fun!
  • Image Size Recommendation: 492 by 320 pixels
  • Always enter the "Alternative text" so that your images communicate with people using screen readers, too!

Image Placement

  • This field is required, but you can ignore it if not uploading an image.
  • Here you can select positioning for your image and the default value is "Left".
    • If super blocks are in a region with other blocks (such as within the "Articles" section of a Multipurpose page), the image will fill the entire width of the block across the top, and any teaser text you entered will appear below the image.
    • But, if a super block appears alone in a region, the image will align with the left or right side of your block and any teaser text you entered will wrap around the sides of your image inside of the block.

The Jump Link

Jump Link Title and URL

  • These are optional, but you can enter a link (in the URL box) and it's human-readable label (in the Title box), if necessary.
  • The Link Title will show on the completed Super Block as a standard "Highlight Button".
  • The Link URL you enter will apply to the Highlight Button, and also to the Title and Primary Image of the Super Block.

Jump Link Location

  • This field is required, but you can ignore it if not entering a Jump Link.
  • Depending on what options you select, your Highlight Button link will appear either:
    • Below the teaser text and image (the default value), or
    • As an overlay on top of the image.

The Skin (or Design)

  • This field is required, and determines which of the pre-set design treatment is used for this block. The skin options are:
    • Standard: uses a gray title and jump link with white text and a gold icon (this is the default value).
    • GT Blue: uses a blue title and jump link with white text and gold icon.
    • GT Gold: uses a blue title, but the jump link is gold with white text, and a blue icon.

Slide Shows and Carousels

Slide Shows and Carousels
Category
root Mon, 05/14/2018 - 14:25
Drupal Version

While carousels are traditionally seen as a good way to squeeze more content into a limited amount of screen space, studies (see Should I Use a Carousel?) show that site visitors are most likely to ignore anything beyond the first slide, and a poorly built carousel can irritate users, leaving them with negative feelings towards your site and your organization.

More information is available on the image carousels page of the Georgia Tech Resources for Webmasters website, but in short, for the time being it's best to avoid carousels whenever possible, especially with Drupal sites.

If you inherit any Drupal sites, you may see the GT Slideshow or GT Carousel Slider module on them.  These modules are deprecated and no longer supported, so you should remove them from your site(s) as soon as possible.

Webforms

Webforms afrank30 Wed, 10/01/2014 - 09:50
Drupal Version
Tags

This section provides tips and tricks for using the Webform module to create forms on a Drupal website, from an Editor's perspective.


Webform Topics

Custom Emails for Webform 7.x-3.x

Custom Emails for Webform 7.x-3.x afrank30 Thu, 05/11/2017 - 13:42
Drupal Version
Tags

The following instructions show how to make it easier to read Webform data sent in emails (for Webform 7.x-3.x).

Under the Emails tab for a Webform, find the section titled Email template.

Default template

If you choose "Default template" from the drop down box, you usually have this code:

Submitted on %date
Submitted by user: %username
Submitted values are:
%email_values

The results of this submission may be viewed at:
%submission_url

Custom template

However, if you choose "Custom template" from the drop down box, you can customize how your webform data is output in the email(s) that are sent. For example, unless people are creating accounts on your site, you may want to remove the %username line.

Key values

Of more frequent use, though, is the need to simplify submitted data and shorten the labels. To include and format a specific piece of data in this email, use %value[key], where key is the machine name of the field holding that data.

Keys can be found under the Form components tab for a webform. For each field you want to include in the email, select Edit"for that field's row, and copy the Field Key.

Example template

An example custom email template, where you let webform create the names of your field Keys, based on the Label you gave each field, might look like this:

Submitted on %date

DETAILS:

Contact Person:
%value[contact_person]
%value[email]
Work: %value[work_phone]
Cell: %value[cell_phone_if_applicable]

Event Details:
Name: %value[event_name]
Date: %value[event_date] from %value[event_start_time] to %value[event_end_time]
Location: %value[event_location_please_include_rain_location_if_applicable]

The results of this submission may be viewed at:

%submission_url

Advanced Drupal Tasks

Advanced Drupal Tasks afrank30 Fri, 03/22/2013 - 09:36
Drupal Version

This section describes some of the more advanced tasks you might need to accomplish when editing a Drupal-powered website.


Advanced Topics

Roles and Responsibilities

Roles and Responsibilities root Mon, 03/11/2013 - 13:04
Drupal Version
Tags

Roles are used by Drupal to apply a set of permissions to a group of user accounts.  Some roles are built into Drupal, and some are automatically created by different Georgia Tech community modules and distributions, such as Drupal Express.

Drupal Provided Roles

Anonymous user

Automatically applies to anyone visiting your site who is not logged in.

Authenticated user

Automatically applies to anyone who is logged in to your site, so be careful about what permissions this role is given.

Roles Provided by Georgia Tech Community Modules

Editor

This role can Edit all pages, as well as the menu and blocks on a GT Drupal site. It's not usually assigned automatically, but by one of your site's Administrators.

Administrator

This role has limited access to the Administrative section of a GT Drupal site and can also do anything Editors can. Should NEVER be assigned automatically.

Super Administrator

This role has full access to the Administrative section of a GT Drupal site. Should NEVER be assigned automatically.

Contextual Filters in Views

Contextual Filters in Views ma195 Thu, 05/08/2014 - 10:24
Drupal Version
Tags

Contextual filters in Views are powerful, but getting them to work perfectly can be a nightmare. This will hopefully save some people from the headaches I had.

My goal was to have a News page that could easily be filtered to only have specific stories. I started with:

  • A Taxonomy vocabulary called "Keywords"
  • A "News Story" content type
  • A field named "Keywords" in the News Story that is a Term Reference type linked to the Keywords taxonomy

Our news stories are imported from Mercury, and the keywords are automatically imported into the Taxonomy vocabulary.

The goal is to have a page that lists all our news stories at example.gatech.edu/news.  A simple view can handle that easily. With a correctly configured contextual filter, we can add a taxonomy term to the end of the URL, and the view will automatically filter itself down to just the stories tagged with a term. Basically:

  • example.gatech.edu/news will list all news stories
  • example.gatech.edu/news/robotics will list all news stories with the keyword "robotics"
  • example.gatech.edu/news/music will list all news stories with the keyword "music"

Neat, right? The problem is, contextual filters can be a nightmare to set perfectly.

Step 1: Create the Basic View

Create a new view at /structure/views/add. We set it to show content of type News, sorted newest first. Make sure the "Create a page" box is checked, give it a URL, and set the display format to something simple like unformatted list of linked titles.

Save the view and head to the URL to make sure it works. Good? Let's head back and edit that view.

Step 2:  Make the View Advanced!

Make sure you are using the Page display, not the master. Usually when something isn't working, it's because I was not editing the page view.

Open the Advanced menu on the right if it isn't already.

Select Add next to Contextual filters.

Check Content: Has taxonomy term ID in the pop-up and Apply.

When the filter value is NOT in the URL:

This controls what the view does when there's nothing added to the end. What will show at example.gatech.edu/news.

  • Display all results for the specified field - shows everything. This is what makes the news page show all stories.
  • Provide default value - Lets you chose a default tag if you want a subset shown.
  • Show "Page not found."
  • Display a summary.
  • Display contents of "No results found."
  • Display "Access Denied."

When the filter value IS in the URL or a default is provided:

Override Title - This lets you change the default title. Enter "News stories tagged with %1"; this will take the term in the URL and substitute it for the %1. So if you are on example.gatech.edu/news/music, the title will be "News stories tagged with music."

Specify validation criteria

This is the tricky part. Check this, then:

  • Set Validator to "taxonomy term."
  • Select the "Keywords" vocabulary.
  • Set Filter Value type to "Term name converted to Term ID."
  • Check "Transform dashes in URL to spaces in term name filter values."
  • Set Action to take if filter value does not validate to "Display a summary."

Save the filter, then save the view.

Create or Rename a Menu

Create or Rename a Menu jtomasino3 Thu, 04/02/2015 - 09:24
Drupal Version
Tags

Create and Enable a Menu

  • To Create a New Menu:
    1. Navigate to the Menus page (Structure > Menus).
    2. Select Add Menu.
    3. In the Title field, enter a title.
    4. In the Description field, enter an optional description.
    5. Select Save.
  • To Enable a Menu:
    1. Navigate to the content type for the node(s) (Structure > Content Type > Multipurpose Page)
    2. Select the content type and select Edit.
    3. Choose Menu Settings
    4. Select the checkbox of the menu(s) you want to enable
    5. (Optional) Set the "Default Parent Item" to choose whatever menu you want as the default for that particular content type.

Note: Enabling the menu allows it show up in the dropdown list when you add a web page to a menu.

Rename a Menu

  1. Navigate to the Menus page (/admin/structure/menu).
  2. Select Edit Menu.
  3. In the Title field, enter a new title.
  4. Select Save

Note: The default menus cannot be renamed.

Editing Menus (Advanced)

Editing Menus (Advanced) jtomasino3 Wed, 04/08/2015 - 21:41
Drupal Version
Tags
  1. Navigate to Structure > Menus, or you can get there by hovering over the gold primary menu bar until a little cog appears in the upper right-hand corner. Click on the cog.
  2. You will see a list of links in your primary menu.
  3. Select the Add Link button.
  4. In the Path field, enter a path for the link.
    • This can be an internal Drupal path such as "node/add." or an external URL such as http://example.com.
    • Enter <front> to link to the front page.
  5. In the Description field, enter the text that will be displayed when a user hovers over the link.
  6. Enable any of the following options:
    • Enabled: If the link is not enabled, it will not be displayed in the menu.
    • Expanded: If this option is enabled and the menu link has children, the menu will always appear expanded.
  7. In the Parent Link list, select the parent menu of the link.
  8. (Optional) In the Weight list, select the relative weight of the link. Links with the "lightest" weight will display higher in a menu. Links with the same weight will display in alphabetical order.
  9. Select Save.

Reporting a Problem with Your Web Site

Reporting a Problem with Your Web Site afrank30 Fri, 03/22/2013 - 10:11
Drupal Version

If you run into a problem editing your Drupal website and need to get help from the community, please use the following guidelines to best share and explain the problem you have encountered.

  1. First, take a picture of the whole screen of your computer, making sure you are on the problem page and, if possible, showing the error you encountered. You can capture screenshots on either a Mac or on a Windows computer.
  2. Next, make sure to include the full web address (or URL) of the problem page. For example:  http://yoursite.gatech.edu/content/my-problem-page
  3. Clearly Describe the problem:
    1. Explain exactly what were you trying to do.
    2. Tell us what actually happened, and how that differed from what you expected to happen
    3. Type out any error messages that you received that aren't overly long.  Some people block images in their emails, and you can get a quicker response from them if they can just read the error message without having to manually open your screen capture image.
  4. Email your screenshots, URL, and description of the problem to whoever helps you with your website. If you don't have anyone, you can always send to the Georgia Tech Drupal Mailing List and hope someone knows how to solve your problem.

Resources for Drupal Developers and Site Administrators

Resources for Drupal Developers and Site Administrators

Learn how to administer or build Drupal sites at GT. Read on for knowledge, tools, and best practices shared by Drupal developers from across campus.

Get involved: consider joining our helpful mailing list and attending our fascinating monthly meetings.

Sections

root Tue, 03/12/2013 - 15:56

Drupal Installation

Drupal Installation root Tue, 12/04/2012 - 13:17
Drupal Version

This section contains guides to help you with installing a new copy of Drupal.  Information on updating and upgrading existing Drupal sites can be found elsewhere in the handbook.

Where to Host Your Drupal Site?

Where to Host Your Drupal Site? esembrat3 Fri, 03/15/2013 - 14:18
Drupal Version

There are a number of ways you can host your Drupal site on campus, which is strongly suggested for any unit-level website.

All units can take advantage of the central OIT Web Hosting service.  This service can host many popular PHP based content management systems, including Drupal and WordPress.  For those looking to quickly setup a unit-level website, OIT Web Hosting now supports Drupal Express, which will give you a jump start on building a Drupal based website by installing Drupal plus a number of standard add-on components, such as the official Georgia Tech website theme.

Should you choose not to use OIT's services, some Schools, Colleges, and other units have their own externally hosted or internally housed servers for web hosting. You should consult with the local IT representatives within the group to see if this is available.  In some cases, you may still be able to make use of Drupal Express by using the generic version of the Drupal Express installation script.

Installing Drupal to an OIT Web Hosting Account

Installing Drupal to an OIT Web Hosting Account kp37 Wed, 03/23/2016 - 16:19
Drupal Version

The following steps should guide you in getting a Drupal installation set up in an OIT Web Hosting account.  These steps will give you a generic Drupal installation -- if you'd rather start with a more turnkey configuration, you may want to look at Drupal Express.

Before You Begin

If you haven't done so already, you'll need to request a hosting account from OIT.  You will also need to know how to access the Plesk control panel for your account in order to complete the rest of these steps, and you may also wish to set an SSH password so that you can SSH into your web hosting space.

If you decide to set up Drupal somewhere else to build your site, and now want to move that site to OIT Web Hosting, you should see our separate Site Migration Guide.

Installing Drupal Using Installatron

The quickest way to get Drupal setup is to use the Installatron Applications Installer, which will download and setup Drupal for you.

  1. From the front page of the Plesk control panel, look for the Installatron Applications Installer link on the right-hand side of the page.
  2. Under the heading "Apps for Content Management", look for and select the Drupal blue water drop icon (the text underneath reads 'Drupal cms'. 
  3. You can read about Drupal on the next page and view the live demo if you like.  When you are ready to install, look for the drop-down in the top right section of the page with a big blue plus symbol and the words "install this application"
  4. On the next page answer all of the questions about your installation.  Details on some of the more notable settings are given below:
    • Version:  You should install the latest 7.x version, as it the only version currently supported by the Georgia Tech Drupal Theme and other GT Drupal modules.  Do not under any circumstances select a version earlier than 7.43, and only select an 8.x version if you are setting up a site that doesn't have to have full Georgia Tech branding and you are already familiar with and comfortable with supporting the 8.x version of Drupal.
    • Automatic Update and Automatic Update Backup:  You can leave these settings at their defaults unless you have a good reason for changing them.
    • Administrator Username and Administrator Password:  These have been randomly generated, but you can change them if you prefer.  Avoid using 'admin' or 'administrator' for the username - something more unique provides a little better security.
    • Administrator Email:  Set this to an email address that someone will be watching (ideally yourself).  The default will be for the mailing list that sends to everyone who is an owner or administrator for your OIT Web Hosting account.
    • Advanced:  Most of these can be left alone.  However, you may wish to select Let me manage these settings and then under Email Notification choose Let me choose which notifications are sent and uncheck some of the options.  Otherwise, you may get quite a bit of email from Installatron about your application.  For example, you may prefer to uncheck all of the "*Something* Complete" options so that you only get emails when an operation fails or when updates come available.
  5. Select the Install button at the bottom of the page to complete your installation.
  6. Once installation is complete, you can visit your site's URL to log into your Drupal installation and start configuring it and adding content.

Installing Drupal Manually From a Downloaded Archive File

Another way to install Drupal is to download the installer and copy it to your hosting account.

  1. Visit the Drupal.org website and download the latest version of the Drupal 7.x series for any site that needs to have standard Georgia Tech branding.
    • Do not under any circumstances select a version earlier than 7.43, and only select an 8.x version if you are setting up a site that doesn't have to have full Georgia Tech branding and you are already familiar with and comfortable with supporting the 8.x version of Drupal.
    • If your are comfortable with using SSH to connect to your Web Hosting account, you can select either download format (.tar.gz or .zip).  If you prefer to upload the archive file to your Web Hosting account via the Plesk control panel, you must download the ZIP format file.
  2. Upload the archive file to your OIT Web Hosting Account and unpack it where you want your Drupal installation to live.  From within the Plesk control panel, you can upload the archive file via the File Manager.  Once the file is uploaded, just select it in the File Manager to unpack it.  After the archive file has been unpacked, move it to your hosting account's "/private/" folder.
  3. In the Plesk control panel, go to the Databases manager and create a new database.  Copy down the database name, the database user name, and the password, as you will need them later.
  4. Navigate to your Web Hosting site's URL and you should get an installation screen for Drupal.  Follow the prompts and answer the questions - they should mostly be straightforward.  Refer to the Drupal Installation Guide if you need any help.
    • IMPORTANT NOTE:  When entering your database information you must enter "mysql.localhost" as the server name.  This in an artifact of the way that the OIT Web Hosting Servers are set up.

Migrating a Drupal Site to OIT Web Hosting

Migrating a Drupal Site to OIT Web Hosting esembrat3 Mon, 10/27/2014 - 13:11
Drupal Version

Moving an existing Drupal site (either a production site or one built on a development server) to an OIT Web Hosting account is not terribly difficult, but it is important to make sure you follow all of the right steps.

Skills Required for Migrating a Drupal Site

  • You will need to know how to access the Plesk control panel for your account in order to complete the rest of these steps you may also wish to set an SSH password so that you can SSH into your web hosting space.
  • You should have a basic understanding of filesystems and mySQL databases, as well as phpMyAdmin
  • If you need assistance with some of these steps, check with your local unit's IT support staff 

Before You Begin

If you haven't done so already, you'll need to request a hosting account from OIT.  If you are moving a live site, you should ask for the account to be set up as the hostname of your live site, but ask that DNS not be updated yet, since that would disrupt your existing site.  Once the account is set up, you can do one of two things to access it while you are working on migrating your existing site:

  1. You can edit your local computer's hosts list (on Linux and Macintosh computers, this is /etc/hosts) to locally map your live site's hostname to your OIT.  This is the quickest method, but while you have this mapping in place, you won't be able access your existing live site from that computer.
  2. You can create a DNS alias for your new site.  You or someone in your IT staff will have to create the alias in DNS, and then you'll have to go into the Plesk control panel for your new OIT Web Hosting site and add the alias there (via the Add New Domain Alias button on the main page) so that the Plesk server knows that your DNS alias goes with your OIT Web Hosting account.  This method takes a little more effort to set up, but with it you can access your new site from anywhere while you are testing it, and you can access your existing live site from the same computer at the same time.
  3. You could actually mix these two methods for perhaps the most versatile option:  you can define an alias for your new site in your local computer's host file, and then add that alias to your Web Hosting account via the Plesk control panel, but without adding the alias to DNS.  This will let you access both the old and new sites from your local computer, but you still won't be able to access your new site from anywhere else.

When your new site is ready to go live and replace your existing live site, you can have DNS updated (see below) and remove any unneeded aliases that you have created.

Moving Any Drupal Site to an OIT Web Hosting Account

  1. You will need to create an archive of the filesystem of your existing site, and an archive (often called an SQL dump) of your existing site's database.  How you do this will depend on where your existing site is located.  Please note that if you are comfortable with using SSH, you can archive your site's filesystem as either a GZipped Tar archive (.tar.gz extension) or a Windows style ZIP archive (.zip extension).  If you are not comortable with SSH and prefer to upload your archive to your Web Hosting account via the Plesk control panel, your archive must be in Windows style ZIP format.
  2. Upload the archive file to your OIT Web Hosting Account and unpack it where you want your Drupal installation to live.  From within the Plesk control panel, you can upload the archive file via the File Manager.  Once the file is uploaded, just select it in the File Manager to unpack it.  After the archive file has been unpacked, move it to your hosting account's "/private/" folder.
  3. In the Plesk control panel, go to the Databases manager and create a new database.  Copy down the database name, the database user name, and the password, as you will need them later.
  4. While still in the Databases manager, on its main page select the Webadmin link for the database you just created.  This will open phpMyAdmin for this database in a new browser window or tab.  On the Import tab of phpMyAdmin, import the SQL dump of your existing site's database.
  5. Either vis SSH or the Plesk control panel's File Manager, modify your Drupal site's sites/default/settings.php file and update the database information in it to match what you copied down in step three above.
  6. Navigate to your Web Hosting account's main URL, and you should hopefully see the front page of your Drupal site.  Try logging into it and check the Drupal status page and error logs to see if there are any problems with the site.

Updating DNS When Moving a Live Site

If your site is already live in another location, then you will need to update DNS to point your site's hostname to your new OIT Web Hosting account.  You will need to know your hosting account's server name - to get this, just look in your browser's address bar while logged into your Web Hosting account's Plesk control panel.  The server will be web-plesk#.gatech.edu, where # is a number from 1 to 11 (or higher, should they add more servers in the future).  Either update your existing site's hostname to point to this plesk server, or if you don't have that kind of access, ask your local IT support staff to make the change for you.  If you don't have anyone in your unit who can update DNS, you can always open a support request with OIT.

A Word on Migrating a Development Site to Live Production

If you are developing your site somewhere else and then moving it to an OIT Web Hosting account (or any other server where the DNS hostname for the site will be different from what it was in development), then you need to take special care to make sure that your internal links do not break.

When setting the URL paths for page links, inline images, attachment files, etc., make sure to enter those URLs as relative paths.  A regular (called 'absolute') URL looks like this:

  http://your-site-host-name/path/to/my/file.xyz

The relative version of that path looks like this:

  /path/to/my/file.xyz

Relative paths will continue to work even after you change the hostname of the website.  Absolute paths will cause the user's web browser to try to follow the link back to the development site.  This can cause all kinds of problems, ranging from links not working and images not showing as soon as the new site goes live, to problems that aren't detected until someone updates an attachment file yet no one sees the update because the link to that file is still retreiving the old version from your development server.

The command line savy developer may want to search through his/her SQL database dump for the hostname of the development server before uploading that dump file to the new OIT Web Hosting account.  This is a great way of catching any absolute URL links that are still lingering about somewhere in the site.

Importing a Migrated Site into Installatron

Installatron is a service available in OIT Web Hosting that (among other things) can keep the core of your Drupal site automatically updated with security patches. To import a migrated Drupal site into Installatron, please refer to the Installatron documentation provided by OIT's Web Hosting team and watch the video tutorial on this page.

Please note that by default, Installatron does not enable automatic updating of Drupal core when importing a Drupal website into Installatron. To turn on automatic update:

  1. From the front page of the Plesk control panel, look for the Installatron Applications Installer link on the right-hand side of the page.
  2. In the section that gives details about your Drupal installation, select the blue wrench icon button.
  3. Under Automatic Update, select 'Create a backup and update to new minor versions and security releases. (Recommended)'.
  4. Select Save All

Installing Drupal on Your Own Computer

Installing Drupal on Your Own Computer esembrat3 Fri, 07/19/2013 - 15:10
Drupal Version

Drupal can be locally installed by using the Acquia Dev Desktop application. Read Eric Sembrat's excellent Local Dev Environments slides about your other options.

Purpose

Acquia Dev Desktop installs a functional local web server on your machine and allows you to easily create, edit, and remove multiple Drupal sites using their user interface.

Potential Uses

  • Testing new patches or major upgrades.
  • Testing out new themes or modules.
  • Module or theme development.
  • Stress-testing a site.
  • Getting familiar with Drupal.

Expert Local Development Guides

How to Setup a Mac OS X / macOS System for Local Development

How to Setup a Mac OS X / macOS System for Local Development bwaye3 Tue, 10/07/2014 - 09:08
Drupal Version

This process allows you to set up your Mac as a faux-server for local development.

  1. Download XCODE from the App Store: https://developer.apple.com/xcode/
  2. Install command line tools: http://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/
  3. Install and configure WGET: http://coolestguidesontheplanet.com/install-and-configure-wget-on-os-x/
  4. Download wgethttp://ftp.gnu.org/gnu/wget/wget-1.15.tar.gz

How to Install Acquia Dev Desktop as a Local Development Environment

How to Install Acquia Dev Desktop as a Local Development Environment afrank30 Wed, 11/26/2014 - 09:28
Drupal Version

With the Acquia Dev Desktop (ADD) tool, you can easily and quickly set up a local development environment for Drupal on your computer.

Install Acquia Dev Desktop (ADD)

This handy, easy-to-install software is the fastest way to Drupal on your own computer! It includes all the pieces you need to run Drupal on Mac or Windows. With Acquia Dev Desktop, you can develop and test locally, then export to your server(s).

Make sure to write down where you install this on your computer (so you can find it later) and which default username and password you choose.

Add new ADD site

You can add a fresh new Drupal 7 site in Acquia Dev Desktop by clicking: Settings > Sites > New. (See Acquia's documentation for more information).

In this example, we will leave all the default settings for acquia, and change only the "Site name" (to "oit").

Using the DX Shell Script with ADD

See instructions on how to use ADD with the Drupal Express Shell Script.

How to Use the Drupal Express Shell Script on your computer with Acquia Dev Desktop

How to Use the Drupal Express Shell Script on your computer with Acquia Dev Desktop afrank30 Tue, 11/10/2015 - 09:41
Drupal Version

The following instructions are for using the Drupal Express Shell Script on your local computer to test Drupal site settings. These partially-complete instructions use Acquia Dev Desktop (ADD) and have only been tested on a Mac. (The author would be super grateful is someone could test on Windows and share any problems they encounter!)

Install Acquia Dev Desktop (ADD)

We have a separate page detailing ho to install Acquia Dev Desktop on your computer.

Prepare Your Folders and Files

  • Change the permissions to allow "Writing" for your new site's folder (oit.localhost), so that you can make changes.
  • Delete all the folders and files underneath "oit.localhost" (except settings.php).
  • (Optional) Decide if you want to delete any acquia modules (under profiles/acquia/modules), such as acquia_connector
  • (Optional) Decide if you want to add any modules you commonly use to sites/all/modules.

Empty Your Database

  • Choose the "Manage my database" option in Acquia Dev Desktop.
  • Select the "Check ALL" option at the bottom of the view for this site's database only, and choose "Drop". This will remove all the tables from this database.

Copy DX Database

Download the DX SQL.

Using phpmyadmin, follow the instructions in the README file, starting at "Import SQL file into your database" for the database ADD created for you (oit). This will make sure your user account (gburdell1) can log in to your new site.

Copy DX Files

Download the DX Files and then replace all the files and folders underneath "oit.localhost" (except settings.php).

Run update.php

In your settings.php file, find the line that says $update_free_access = FALSE; and change the "FALSE" to "TRUE". Save your settings.php file (you will need to change this back at the end).

Using the Acquia popup box, choose "Go to my site" (while the site chosen is your new oit.localhost site).

At the end of the web address it sends you to (such as oit.localhost), add "update.php" and hit Return. Run updates as you might normally on a Drupal site.

Change File System

Once finished updating, change the value in your settings.php file back to $update_free_access = FALSE;.

The design of the site won't look quite right until you change your site's file system (which was automatically set in the GT Editor module) by logging in to the site and visiting: admin/config/media/file-system

Change the "default" folder in each of these three paths to your site (oit.localhost):

  • Public file system path:sites/default/files, becomes sites/oit.localhost/files
  • Private file system path: sites/default/files/private, becomes sites/oit.localhost/files/private
  • Temporary directory: sites/default/files/tmp, becomes sites/oit.localhost/files/tmp

After you save these changes, your site should work.

Best Practices for Drupal 7 Setup

Best Practices for Drupal 7 Setup afrank30 Fri, 09/12/2014 - 14:56
Drupal Version

Before you make a Georgia Tech Drupal (7) site go live, it can be a good idea to go through a checklist of best practices to make sure you haven't forgotten any important settings.

This (draft/unfinished) checklist can also be helpful for regular site checkups, to make sure your Georgia Tech Drupal sites are still healthy and secure. It's designed for those sites on OIT's Web Hosting, but will generally apply to other settings, too.

This checklist is divided into best practices for Administering your site in TWO main areas:
  1. the Drupal Admin Interface and
  2. the OIT Hosting Control Panel

Please add to this list, without worrying about making it super organized (because we can do that later), more ideas might also be at: https://amsterdam2014.drupal.org/session/how-not-build-and-maintain-drupal-site

Table of Contents

For now, this checklist is divided into best practices for Administering your site in TWO main areas: the Drupal Admin Interface and the OIT Hosting Control Panel

Drupal Admin interface (at http://mysite.gatech.edu/admin)

  • Available Updates
  • Accounts
  • Logging and errors
  • Performance
  • Text formats
  • Login protection
  • Form protection
  • Site information
  • URL alias patterns
  • Modules, Libraries & Themes (standard)
  • Non-standard Modules, Libraries & Themes
  • Access/Permissions/Users
  • Other Good Defaults we Share?

OIT Hosting Control Panel (at http://hosting.gatech.edu)

  • Installatron
  • Backups
  • Scheduled Tasks (cron)
  • Owner/Administrator
  • Directory structure
  • URL Redirects
  • Other Good Defaults we Share?

Part 1: Drupal's Admin interface (at http://mysite.gatech.edu/admin)

Available updates settings (admin/reports/updates/settings)

  • Check for updatesWeekly
  • Check for updates of disabled modules and themesYes (unless on a multi-site, where only 1 site should check this)
  • E-mail addresses to notify when updates are availableAt least TWO (2) email addresses (preferably some office-wide emails).
  • E-mail notification thresholdOnly security updates

Account settings (admin/config/people/accounts)

  • Anonymous usersVisitor
  • Administrator roleSuper Administrator
  • Who can register accounts?Administrators only
  • Require e-mail verification when a visitor creates an accountYes.
  • When cancelling a user account: Disable the account and keep its content.
  • Personalization
    • Enable signatures: No
    • Enable user pictures: No
  • Emails: Default (unless reason to change)

Logging and errors (admin/config/development/logging)

  • Error messages to displayNone
  • Database log messages to keep100
  • Note: Do not enable the core syslog module if you are using OIT hosting. According to its documentation, it is not appropriate for shared hosting. You should be able to find most useful debugging information by going to the "log manager" section in plesk and looking at the error logs.

Performance (admin/config/development/performance)

  • Caching
    • Cache pages for anonymous usersYes.
    • Cache blocksVaries (how often do your blocks change?)
    • Minimum cache lifetime??
    • Expiration of cached pages??
  • Bandwidth optimization
    • Aggregate and compress CSS filesYes.
    • Aggregate JavaScript files??

Text formats (admin/config/content/formats)

  • Order mattersplace "basic text editor" at the top/first, then "minimal HTML", etc.
  • Plain textonly format to which Anonymous users should have access.
  • PHP code: do NOT allow anyone to use this.

Login protection (admin/config/people/cas)

  • cas, GT Login, etc.??
  • other details go here

Form protection ()

  • ? go here
  • other details

Site information (Configuration >  System > Site information)

  • E-mail address: this is the email FROM which emails are sent by the site (should probably be generic, rather than an individual).
  • Site name: ...

URL alias patterns (admin/config/search/path/patterns)

  • details go here

Modules & Libraries ()

  • set up google alerts to check for updates to libraries (such as ckeditor, phpcas, flexslider, etc), especially if they have security vulnerabilities.
  • disabled (should probably be uninstalled & then removed from sites/all/modules directory)
  • development only (such as devel module or bundle_copy, masquerade, etc.)
  • risky
  • poorly-supported
  • other details

List of non-standard modules used &/or changes to standard modules/theme ()

  • details go here
  • other details

Access/Permissions/Users ()

  • details go here
  • other details
OTHER GOOD DEFAULTS?
  • ANOTHER EXAMPLE HERE.
  • ADD OTHERS HERE

Part 2: OIT's Hosting Control Panel (at http://hosting.gatech.edu)

Installatron Applications Installer

  • If you are using Drupal, you should import your site into Installatron so it can keep your CORE code updated and secure.
  • Use Recommended setting for "Automatic Update": Create a backup and update to new minor versions and security releases.
  • Regularly clean out/delete all but your most recent INSTALLATRON backup (because you cannot set it to only keep a certain number, unlike your "Backup Manager").
  • Check that your "Administrator Email" is correct (and probably should also be generic for the office, instead of tied to an individual).
  • Check that installatron is using the correct URL (web address).

Backup Manager

  • Recommendations: Set to create one automatically each day, and to keep around 14 days worth.

Scheduled Tasks (cron)

Owner/Administrator

  • Set the owner of the site to a generic, office email alias (like mydepartmentweb@gatech.edu).
  • Regularly check that the administrators of a site are correct (and request removal of former maintainers).

Directory structure (multi-site vs. solo site, single system per virtual host, etc.)

  • This will vary depending on your site setup, but we no longer recommend using "contrib" and "custom" subfolders in the sites/all/modules folder.

URL Redirects

  • These are usually created in your .htaccess file (always keep a copy of the latest in your /private directory).
  • Check that your re-directs did not get overwritten when your site's Core code was late updated.
OTHER GOOD DEFAULTS?
  • ANOTHER EXAMPLE HERE.
  • ADD OTHERS HERE

File or Directory Permissions Errors

File or Directory Permissions Errors afrank30 Fri, 06/19/2015 - 13:26
Drupal Version

General Permissions Errors

Note:  If you are running in a shared hosting environment, like OIT Web Hosting, then you are not likely to get many if any general permission errors, as each website runs under its own hosting account in these environments.  Thus, it is nearly impossible to mess up file and directory ownership in these environments.  However, it is worth checking the file and directory permissions, as they are often changeable, and if the owner-write permission is removed from a file or directory then the web server will not be able to modify that file or directory.

If you see any kind of general file or directory permissions errors, the first thing to check is that your sites "sites/default/files" directory and all of its subdirectories are writable by account that your web server runs under.  On stand-alone web servers, these directories and their files don't necessarily have to be owned by this account, but the account still has to have permission to access them.  Consult with your server administrator if you need help in determining the right user and group ownerships for your website's files and directories.

Temporary Directory Permissions Errors

Sometimes after moving a Drupal site to a new web server, you may see an error message that looks something like this:

The specified file temporary://fileX could not be copied, 
because the destination directory is not properly configured. 
This may be caused by a problem with file or directory permissions. 
More information is available in the system log.

Often this is accompanied by the site looking strange and not having much theming or design. This happens because your site's file system needs permissions to access the Temporary directory.  Usually this directory is located at "/tmp", but sometimes the person who built the Drupal site configured it to use a special directory, and then when you copied the site to the new web server, either that special directory was not created or its permissions were not set correctly.

To fix this, try to log into the site as an administrative user and then navigate to the Media section of the Configuration administration page, and go into the File system sub-section.  If you have trouble navigating through the site, you might try going directly to that page:

  http://your-site-host-name/admin/config/media/file-system

On the File system page, make a note of the path set for Temporary directory and then check to make sure it exists on your server and that it is writable by the account that your web server runs under.  Alternatively, you may want to just change the value of Temporary directory to "/tmp" and see if that works.  For websites on OIT Web Hosting, the path "/tmp" should always work, and it's a good starting point for many other web servers out there as well.  If you still run into problems then you may need to contact your server administrator to find out what temporary directory path you should use with Drupal for that server.

Drupal Updates

Drupal Updates root Tue, 12/04/2012 - 13:40
Drupal Version

Updates patch Drupal to sometimes add new features and sometimes protect against discovered vulnerabilities and keep your sites working optimally. Always test new updates on a development site before applying them to your live, production site.


Drupal Updates Sub-Topics

Configuring the Drupal Update Manager

Configuring the Drupal Update Manager esembrat3 Thu, 02/21/2013 - 10:21
Drupal Version

The Update Manager, if used properly, can provide you an easily-accessible location to view what modules and themes need updating.

The settings for the Update Manager ( admin/reports/updates/settings ) provide a few key settings:

  • E-mail addresses to notify when updates are available - A list of emails to be notified when Drupal finds a new release of a module.
  • Check for updates of disabled modules and themes - To ensure all modules are kept up to date, this should be checked (on multi-sites, you only need to check disabled modules and themes for ONE of the multisites).

Updating Drupal Core Via Installatron

Updating Drupal Core Via Installatron root Tue, 12/04/2012 - 13:41
Drupal Version

Before You Begin

  • To be able to use this method of upgrading, your Drupal site must have been created via Installatron or imported into Installatron.
  • Please note that if you installed the Drupal application via Installatron with the update automatically setting, you will not need to go through these steps, as Installat ron will update the site as soon as the new release is posted.
  • Important!!! Installatron will overwrite your .htaccess and robots.txt files.  If you have made any changes to them, be sure to back the m up before upgrading so that you can restore your custom changes after the upgrade is done.
  • Be sure that your Drupal website is configured in Installatron.

Upgrade Process

  1. Open a web browser and navigate to http://hosting.gatech.edu/.
  2. Log in using your GT Account Username and password, and then select the appropriate site from the list.
  3. From the left-hand menu, select Installatron Applications Installer.
  4. An entry describing your Drupal site should appear.  Select the Upgrade button.
  5. Installatron will guide you through the upgrade process of the site.
  6. Follow the directions on the page and select Upgrade to complete the process.

Installatron Updating Tips

Installatron Updating Tips esembrat3 Thu, 08/28/2014 - 07:37
Drupal Version

Running updates on OIT Web Hosting is essential to ensuring that your site remains safe and responsive to every user. The preferred method of running updates is through Installatron, a server application which manages installed web applications on a hosting account.

Update Check

By default, Installatron will check for core updates in one of two ways:

  • For new Installatron Drupal websites, Installatron checks every 6 hours for Drupal security updates. 
  • For imported Installatron Drupal websites, Installatron does not check for Drupal core updates.

Installatron keeps track of each site's app separately, so there is not a way to determine exactly when an update is going to apply for a site. The documentation for Installation say that a site's web app will update between 12am and 6am server time.

Similarly, when Installatron checks for web app updates from the mothership, it's independent (e.g., the updates do not happen at 12 pm, 6 pm, 12 am, 6 am). This makes sense since the increased load of websites all applying updates concurrently would heavily degrade the hosting service.

Configuring Installatron Updates

To configure your Drupal site on Installatron to automatically update, follow the directions below:

  1. Log in to your website from OIT Web Hosting.
  2. Select Installatron Applications Installer.
  3. For the Drupal site in question, select the wrench to view/edit details.
  4. Under Automatic Update, select "Create a backup and update to new minor versions and security releases. (Recommended)".
  5. Select Save All.

Updating from Installatron

Please see Updating Drupal Core (Installatron).

False Flag on Latest Version

As Doug Curtis from OIT Web Hosting notes, there is a current bug in detecting the latest release of Drupal from within Installatron.

  • There is an open issue where Installatron shows a green check mark indicating it has the latest version but if you check the version number next to the check mark, it is not [current]. I have a ticket open with the vendor about this. This is a good reminder that you should always manually check your versions and not rely 100% on automatic systems.

Backup Directory

The default backup directory for Installatron is:

  • /application-backups

You can set custom backup locations through Installatron by editing your Drupal installation via the Applications Installer, and looking under "Default Backup Location".

Updating Drupal Core Manually

Updating Drupal Core Manually root Tue, 12/04/2012 - 13:43
Drupal Version

Before You Begin

  • The instructions below are for moving between different releases of the same major version of Drupal (e.g. 7.x, 8.x. etc.)  Please see our Site Migrations section for more details on moving to the next major version of Drupal, which is a much more involved process.
  • The instructions below assume your site is on a UNIX style web server and regularly reference the OIT Web Hosting environment.  If your site is hosted on a different kind of web server, then these instructions may have to be modified to work correctly for you.
  • Additional information can be found on the Drupal.org page about minor version updates.

Drupal Core Upgrade Process

  1. Open up a web browser and navigate to your Drupal site.
  2. Log into the site as an Administrator.
  3. Navigate to the Maintenance subsection of the Development section of your site's Configuration administration area (Configuration -> Development -> Maintenance) and enable the "Put site into maintenance mode" checkbox.  (Don't forget to save your change!)
  4. Either via SSH/SFTP or (for sites on OIT Web Hosting) the Plesk Control Panel, make a backup of your site's filesystem.
    • If you are using SSH, you can navigate to your site's base directory and issue the following command:
      • tar czf ~/drupalbackup.tgz *
    • If you are on OIT Web Hosting, you should store your backup in the "private" folder like so:
      • tar czf ~/private/drupalbackup.tgz *
  5. Backup your MySQL database.  On OIT Web Hosting, the easiest way to do this is to log into the Plesk Control Panel for you site and access phpMyAdmin via the Webadmin link in the Databases management section.  On the other hand, if you are on a stand-alone web server where you have direct access to mySQL commands, you can run a command like the following (be sure to insert the correct username, password, and database name for your particular website):
    • mysqldump -u USERNAME -p DATABASENAME > ~/backups/database-backup.sql
  6. Rename the directory containing your Drupal installation or move the contents of the directory to another location.  With many shared hosting services, you won't be able to rename this directory, so your only choice will be to move its contents.  When moving the contents, be sure to get the .htaccess file from this directory so that you'll have it for reference later on.
  7. If you were able to rename the directory containing your Drupal installation, then from that same parent directory, download and unpack the latest version of Drupal core (be sure to replace 'x' and 'y' with the right major and minor version numbers) and rename the new drupal-x.y directory to match the orignal name of your Drupal installation directory.
    • wget http://drupal.org/files/projects/drupal-x.y.tar.gz
    • tar -xzvf drupal-x.y.tar.gz
    • mv drupal-x.y orignalDirectoryName
  8. If you had to move the contents of your Drupal directory somewhere else, then make sure you are in that now empty directory and do the following:
    • wget http://drupal.org/files/projects/drupal-x.y.tar.gz
    • tar -xzvf drupal-x.y.tar.gz
    • mv drupal-x.y/* drupal-x.y/.???* .
    • rmdir drupal-x.y
  9. Move the following folders to your old Drupal directory to your new Drupal directory:
    • sites/
  10. Return to your web browser and navigate to  http://yourSiteHostName/update.php.  Follow the prompts to apply any database table updates that are needed.
  11. Check the administrative Status report to verify that everything is working as expected.
  12. Navigate to the Maintenance subsection of the Development section of your site's Configuration administration area (Configuration -> Development -> Maintenance) and disable the "Put site into maintenance mode" checkbox.  (Don't forget to save your change!)

Updating Drupal Modules

Updating Drupal Modules root Tue, 12/04/2012 - 13:47
Drupal Version

Before You Begin

  • Installatron does not upgrade modules, so even if you use Installatron to manage your Drupal core upgrades, module updates must still be done manually.
  • The instructions below assume your site is on a UNIX style web server and regularly reference the OIT Web Hosting environment.  If your site is hosted on a different kind of web server, then these instructions may have to be modified to work correctly for you.
  • Additional information can be found on the Drupal.org page about module updates.

Drupal Module Update Process

  1. Open up a web browser and navigate to your Drupal site.
  2. Login to the site as an Administrator.
  3. Put the site into maintenance mode (Configuration -> Development -> Maintenance) by enabling the "Put site into maintenance mode" checkbox and saving the configuration.
  4. Either via SSH/SFTP or (for sites on OIT Web Hosting) the Plesk Control Panel, make a backup of your site's filesystem.
    • If you are using SSH, you can navigate to your site's base directory and issue the following command:
      • tar czf ~/drupalbackup.tgz *
    • If you are on OIT Web Hosting, you should store your backup in the "private" folder like so:
      • tar czf ~/private/drupalbackup.tgz *
  5. Backup your MySQL database.  On OIT Web Hosting, the easiest way to do this is to log into the Plesk Control Panel for you site and access phpMyAdmin via the Webadmin link in the Databases management section.  On the other hand, if you are on a stand-alone web server where you have direct access to mySQL commands, you can run a command like the following (be sure to insert the correct username, password, and database name for your particular website):
    • mysqldump -u USERNAME -p DATABASENAME > ~/backups/database-backup.sql
  6. Either via SSH/SFTP or (for sites on OIT Web Hosting) the Plesk Control Panel File Manager, locate the existing installation of the module and either delete it or move it somewhere outside your Drupal installation's base directory.
  7. Download the archive file for the new version of the module and unpack it into the same location where the module had previously been installed
  8. Via SSH, a typical set of commands for steps #6 and #7 might look like this:
    • cd /path-to-your-drupal-site/sites/all/modules
    • rm -r modulename
    • wget http://drupal.org/files/projects/module-x.y.tar.gz
    • tar -xzvf module-x.y.tar.gz
  9. Return to your web browser and navigate to  http://yourSiteHostName/update.php.  Follow the prompts to apply any database table updates that are needed.
  10. Check the administrative Status report to verify that everything is working as expected.
  11. Navigate to the Maintenance subsection of the Development section of your site's Configuration administration area (Configuration -> Development -> Maintenance) and disable the "Put site into maintenance mode" checkbox.  (Don't forget to save your change!)

Site Migrations

Site Migrations afrank30 Thu, 06/26/2014 - 09:09
Drupal Version

This section contains tips on how to move sites from development (either on your local computer, or on a development server) to a production environment.  For more generic but also more official guidance, the official Drupal website has a Guide to Migrating a Drupal Site.

Please be cautious in using any of the information provided here in conjunction with migrating a production Drupal site:  always make backups of your live production site first, so that if anything goes wrong, you can fall back to the old version of the site.

If you are going to migrate your site to OIT Web Hosting, you may wish to review their FAQ on how to request Development, Test and Production Environments.  We also have a guide to Migrating a Drupal Site to OIT Web Hosting in our Installation section.


Georgia Tech Community Provided Resources

Migrating to Drupal 7 from Drupal 6

Migrating to Drupal 7 from Drupal 6 afrank30 Fri, 10/04/2013 - 14:02
Drupal Version

Editor's  Note:  We sincerely hope that no one is still running a site on Drupal 6 at this point, but just in case you should inherit a site that turns out to still be on Drupal 6, we're leaving the following instructions in place, even though they are a bit outdated now, and there's no guarantee that the external links will continue to work.

If you are looking for a migration guide to go to Drupal 8, please keep checking back, as we plan to add one to the Site Migrations section in the not too distant future.

Before You Begin

Create a SEPARATE Test site to use for this process, so you don't kill your Live, Production site and...BACK UP EVERYTHING!

The Recommended Process

Almost no one does a regular upgrade, because so much has changed between Drupal 6 and Drupal 7, and many contributed modules don't even exist in version 7. Instead, the process usually involves:

  1. Creating a new development Drupal 7 instance.
  2. Recreating any important content types and functionality in that development site.
  3. Removing any un-needed modules from the new site (this also keeps your maintenance work easier).
  4. Moving/migrating or recreating actual content (nodes, pages, users, files, taxonomy, etc.) into this new site.

How-To Links on Migration/Upgrading

Use the Feeds XPath Parser module to move content

Common Migration Problems

One of the more common problems with migrating Drupal 6 to Drupal 7 is that Drupal 6 did not have the now standard field system.  Instead, many developers of complex sites used a third-party (contrib) module called CCK (Content Construction Kit), which doesn't have a direct migration path into the Drupal 7 field system.

Another feature often used was the User Profile module, which while still present in Drupal 7, is officially deprecated and is only made available when you run a standard Drupal 7 upgrade process on a Drupal 6 installation.  If your Drupal 6 site uses this module, then you should really take the time to properly migrate that profile information into the Drupal 7 field system, since the user profile module isn't available at all in Drupal 8.

It is possible to do some automated migration of CCK and User Profile data via custom PHP scripting run at the command line, but this is not a task for the novice user, as you need a good understanding of the Drupal 6 and 7 database schemas.  For anyone else, you may either need to hire a web development company that can do this work, or consider hiring student assistants to manually re-enter the data (if the amount isn't too large) into a properly structured Drupal 7 development site.

Downloading a Site Backup File From OIT Web Hosting

Downloading a Site Backup File From OIT Web Hosting afrank30 Tue, 03/10/2015 - 10:58
Drupal Version

Download an OIT Web Hosting Backup File

Log into your Web Hosting account's Plesk Control Panel and select the Backup Manager option on the right-hand side of the main page.

On the Backup Manager page, you will see all of your existing site backups.  If you have not configured automatic backups and have never run a manual backup, then you won't have anything to download.  In this case, you can select the Back Up option and follow the prompt to initial a backup of your site.  Do note that this is done in the background and may take a while on bigger sites, so start it before you go to lunch, and hopefully it will be done by the time you get back to your office.

Locate the backup that you want to down load and select the green down arrow icon on the far right of the backup's entry (see screenshot below).

Your backup will download to your computer, and have a name similar to this: 

backup_mysite.gatech.edu_info_1503101033.xml.tar

Uncompress a Downloaded Backup File

You will need a special program to unarchive a backup file, as backups are provided in the TAR format.

  • On a Macintosh, you may be able to double-click the file and get Mac OS X to unpack it for you - your mileage may vary depending on your version of Mac OS X and how large the backup file is.  You can always go to the command line and unpack the file as well (see the Linux option below for instructions)
    • If you prefer to not use the command line and Mac OS X is giving you trouble, you can try the open-source Unarchiver App
  • On Linux or FreeBSD (or Mac OS X), you can unarchive the backup file from the command line like so:
    • tar -xf backup_mysite.gatech.edu_info_1503101033.xml.tar
  • On Windows, you'll need a utility app that can unarchive a TAR file.  Someone with Windows knowledge should insert here a link to such a utility app.

What is In a Backup Archive File?

Once you uncompress your backup file, you will have a directory with the same name as your file, but without the ".xml.tar" at the end.  Inside this directory, there are two files you will be working with:

  • The SQL backup of your site's database
  • The file system of your Drupal site

File System

The files for your site will be within a compressed file that has "user-data" in its name, like this:

backup_mysite.gatech.edu_user-data_1503101033.tgz

Uncompress this file into a folder of the same name (without .tgz on the end), then look inside it for a folder named "httpdocs", like this:

backup_mysite.gatech.edu_user-data_1503101033/httpdocs

This folder is where your Drupal site files live.  You can review them, copy them to a development web server on your local computer, or archive just that section of the file system in order to transport them to another computer.

Change settings.php Immediately

If you are going to try to use this backup to create a development copy of your live website, immediately change the database connection information so that you don't accidentally connect to your live site.  Look for your Drupal settings file at:  

backup_mysite.gatech.edu_user-data_1503101033/httpdocs/sites/default/settings.php

Database

The SQL for your database will be under a folder called "databases" and then another folder with the same name as your database, like this:

databases/database-name/backup_database-name_1_1503101033.tgz

Rename Your Database in SQL

First, uncompress this file.

If you want to edit the SQL, you should use a very basic text editor (such as Notepad on Windows or TextEdit on mac) because it is a LARGE file and may overwhelm fancier programs.

The main recommended edit is to remove the actual name of the database from the line near the top. This prevents conflicts when importing your SQL into an empty database with a different name.

Redirection and Checking for Broken Links

Redirection and Checking for Broken Links esembrat3 Thu, 08/04/2016 - 08:29
Drupal Version

A Redirect module is available for Drupal 7 to help manage link redirects and locate problem areas on your site post-migration.

Installation

To install, follow the directions below:

  1. Download the Redirect module
  2. Upload the module to your /sites/all/modules/ folder, or use the Upload New Module administration page.
  3. Install and enable the module.

Usage

The interface for the Redirect can be found under Configuration -> Search and Metadata -> URL redirects, or by navigating to /admin/config/search/redirect.

On the overview page, a listing of your existing redirects are in place. Drupal tracks each redirect, their status, the type of redirect, and how often they're accessed. 

Finding and Fixing Dead Links

You can also use the Fix 404 Pages, located at /admin/config/search/redirect/404 or as a sub-tab off of the URL Redirects page. 

This page allows you to identify currently-broken links on your site and a quick way to create a redirect. 

Leverage your local web developer (or contact the Georgia Tech Drupal mailing list) to see if a page or link needs to be redirected.

In the example above, wp-admin.php is a WordPress (another content management system) login page and is routinely used by bots and hackers to attempt to infiltrate your website. Because we're running Drupal, we can ignore most all of those pages. 

To add a redirect to one of these 404'd pages, select the Add Redirect link to the right.

Redirect Options

When creating a redirect, the form should look similar to below.

All that is needed to complete a redirect is completing the To, or where the page needs to go when redirected.

Under Advanced Options, the redirect status can help search engines and browsers interpret the link. The Redirect module provides some short description by each one to give an idea of what each does.

Unless otherwise noted, 301 Moved Permanently or Default (301) should always be used.

If you think you have a use case for any of the other redirect types, please contact a web developer on-campus. Improper usage of the redirect type may hurt access to your redirected page by search engines.

Updating From version 7.x-1.x of the GT Theme to version 7.x-2.x

Updating From version 7.x-1.x of the GT Theme to version 7.x-2.x afrank30 Mon, 08/04/2014 - 14:58
Drupal Version
Tags

Editor's Note:  The following information is rather outdated, but believe it or not, there are still a few sites out there that are running version 1 of the GT Theme.  Our current-day recommendation for anyone running that theme is to strongly consider just rebuilding your site from scratch with a fresh copy of Drupal 7 or Drupal 8, as if your theme is that much out-of-date (version 2 was released in late 2013), you content and other site structures are also likely to be pretty out-of-date as well.

Below are tips and/or steps on how to update your Drupal 7 site from version 1 of the GT Theme (unofficial) to version 2 (official).

  1. Put your site in maintenance mode (and try this on a TEST site first!).
  2. Change the "Appearance" of your site, so that it uses only CORE-provided themes (such as garland).
  3. After you make copies of them and save them somewhere safe, disable any older versions of the GT Theme and any subthemes you made that were based upon it.
  4. Remove any the actual files for the older GT Theme and its subthemes from your file system.
  5. Flush the caches on your site and, just for fun, run "update.php", too.
  6. Install the parts that are required for the 2.x version of the GT Theme in this general order:
    1. GT Content Types (submodule of GT Tools)
    2. GT Tools
    3. GT Theme
    4. THEN, the GT Subtheme
  7. Check to make sure can now add the new content types (such as Horizontal landing page) that come with version 2.x of the GT Theme.
  8. Under Appearance, choose the GT Subtheme (NOT the GT Theme itself) as your default theme for this site.
  9. If re-using the same blocks for this new look, you'll need to put them into regions for this theme under Structure > Blocks.

Georgia Tech Drupal Theme

Georgia Tech Drupal Theme esembrat3 Fri, 10/04/2013 - 12:42
Drupal Version
Tags

Since September of 2013, Georgia Tech Institute Communications has provided an official Georgia Tech Drupal theme suitable for all official unit websites, including but not limited to college, school, project center, and administrative units.  This theme implements the Georgia Tech Website Visual Style Requirements that all official websites are expected follow.

Configuration Walk-through Video

If you are new to the Georgia Tech Drupal theme, you can watch the installation and configuration of the GT Theme section of the video recording of the November 2013 GT Build Day. This is the first section of the video and runs approximately 45 minutes.


GT Theme Sub-Topics

Installing, Extending, and Upgrading the Georgia Tech Drupal Theme

Installing, Extending, and Upgrading the Georgia Tech Drupal Theme klp Thu, 03/03/2016 - 17:20
Drupal Version
Tags

Installing the Georgia Tech Theme

You will need to download both the current Georgia Tech Drupal Theme package, and the GT Tools module.

  1. Install the GT Tools module into your sites/all/modules directory, and the Georgia Tech Drupal Theme package into your sites/all/themes directory.
  2. Log into your site with administrative privileges and enable the GT Tools module.  Please note that you do not have to enable the GT Content Types or GT Directory sub modules that come with GT Tools.
  3. Go to the Appearance administration page and enable the "Georgia Tech - Drupal 7 Theme" and make it the default theme.
  4. After enabling the new theme, follow the Settings link shown below its name to configure the theme's settings, using our GT Theme Settings Guide as a reference as needed.

Extending the Georgia Tech Theme

The recommended way of extending the Georgia Tech Theme to meet your unit's special needs is to create a sub-theme instead of modifying any of the files in the Georgia Tech Theme.  This way, when new versions of the official theme are released, you can just drop them into place and not have to figure out all the different things that you customized.

As a way to get started quickly, there is an unofficial GT Sub-theme package that you can use as a base for your own custom sub-theme.

An important hint for those new to sub-themes:  on your Appearance administration page, you set your sub-theme to be your enabled and default theme.  It will then include everything that it needs from your base theme (the official Georgia Tech Drupal Theme).  For this reason, you must leave the Georgia Tech Drupal Theme installed on your site, and it's a good idea to leave it enabled as well.

For advanced developers, there is also a Sass based version of the official Georgia Tech Drupal Theme.

Upgrading the Georgia Tech Theme

It is highly recommended that you first test any new version of the official Georgia Tech Drupal Theme against a copy of your website to make sure you fully understand the effect it will have on your pages and content.

If you have done all of your customizations in a sub-theme, then upgrading the official Georgia Tech Drupal Theme is very easy:

  1. Download the latest version of the Georgia Tech Drupal Theme
  2. Backup the existing files in your sites/all/themes/gt directory and then remove the directory.
  3. Remove the sites/all/themes/gt directory.
  4. Install the Georgia Tech Drupal Theme package into your sites/all/themes directory.
  5. Log into your site with administrative privileges and flush all of the caches.  This can be done on the Configuration -> Development -> Performance administration page, or via the 'Home' menu if you have the Admin Menu third-party module installed.
  6. Go to the Georgia Tech Drupal Theme settings page and verify that all of the available settings are correct.  Note: it has been observed that sometimes after upgrading the theme, you will find all of the settings fields blank the first time you visit the settings page.  If this happens, simply switch to the global theme settings page and the go back to the GT theme settings page, and your old settings should be restored.

Please note that a new version of the Georgia Tech Drupal Theme could cause conflicts with custom CSS and template code in a sub-theme, so you'll have to watch for these issues and update any custom CSS/template files accordingly.

GT Theme Settings Guide

GT Theme Settings Guide eh94 Mon, 11/04/2013 - 13:10
Drupal Version
Tags

The GT theme version 2.x offers a variety of settings options.

How to Manage Theme Settings

To manage these options:

Description of Theme Settings

These include:

Georgia Tech Logo Options

Select the default GT logo, or go with one of the college logos. You can also upload a file to use, but it must be a transparent .png, and be within the specified dimensions -- plus be an official logo approved by Institute Communications! Contact Institute Communications if you need assistance getting a logo generated in the proper format.

Styling Version

This setting (only available in versions 2.5 through 2.7) configures which CSS/styling is applied to the GT website.  It allows you to switch to the new layout/style treatment (2.5) or stay backwards-compatible with previous styling. This is to help avoid "breaking" any styling folks may have done via a custom subtheme. The version 2.5 styling option also includes support for a couple of block classes that are added through the GT Tools module (/admin/config/system/gt):

New CSS styles for adding icons to block titles:

New CSS styles for adding colored backgrounds to block titles:

  • block-title-bg-gt-blue - GT Navy blue background w/ white text
  • block-title-bg-gt-gold - GT "Buzz" gold background w/ white text
  • block-title-bg-gray - "Dark" gray background (#646464) w/ white text

Site Header

These settings configure site header actions.

  1. Site Header Title: Same as the previous theme. The text provided here will appear in the site header, to the right of the main logo. The text will be set in "Buzz" Gold.
  2. Hide Home Page Title: Check this box if you want the default page title text to NOT appear on your home page. Note that this is NOT the Site Header Title (as mentioned above,) but the node title of your home page for your site.
  3. Search Options: (Removed in version 2.7) Select to have your search be the built-in Drupal search, the campus Google appliance, or user choice.
  4. Breadcrumb Options: By default the breadcrumb will list a link back to the main Georgia Tech site homepage first. If you'd like to have another default link always appear after the Georgia Tech link use these fields.

​Super Footer

These settings relate to the superfooter at the bottom of each page.

  1. Remove Superfooter: (Added in version 2.7): completely hide the superfooter
  2. Super Footer Menus Setup: The Full Georgia Tech Default option will give you the exact same set of super footer menus that appear on the home page of www.gatech.edu. The Georgia Tech Minimum option will give you just the menu from the left column in the super footer of the home page at www.gatech.edu, but the menu will be broken up into two shorter menus. The Configurable option allows you to have three fully configurable menus in your site's super footer.
  3. Collapsed Super Footer: Check this option if you would like to have the super footer collapsed by default. If this option is checked a "Resources" tab will appear above the lower footer, which serves as an open/close trigger for the super footer.
  4. Campus Map Image and Custom Street Address: By default the site super footer area will show an image of the campus map plus link to the map site, and the official GT mailing address. You can opt to upload your own map image, and have it link to where ever you'd like, plus enter your address.

Footer Login

These settings configure site footer login actions.

  1. Show a login link in the footer.
  2. Redirect to current page: (Added in version 2.7) instead of being redirected to homepage after you log in.
  3. Alternate Login URL: (Added in version 2.7): If you use a different URL to log in to your site, provide that full URL (i.e., http://editor.mysite.gatech.edu).

GT Tools Module

GT Tools Module afrank30 Thu, 12/19/2013 - 18:30
Drupal Version
Tags

The GT Tools module is required when using the GT Theme and should be installed before the theme on your Drupal 7 site.  It provides some additional functionality that Drupal doesn't support directly in a theme package, so this functionality had to be provided in a separate module.

GT Tools includes a sub-module called GT Content Types, which provides three new page layouts via custom content types.  If you want to use this sub-module, you must install the 2.2 version (or newer) of the blockreference module (older versions 2.0 and 2.1 don't work).

GT Theme Provided Menus

GT Theme Provided Menus eh94 Mon, 11/04/2013 - 13:35
Drupal Version
Tags

The GT Theme, by default, will use your site's "main menu" for your primary menu. The primary menu is the gold-colored horizontal one that sits below the main Georgia Tech logo. This menu will show the top-level links in a horizontal line, with child links appearing as drop-down boxes.

Additional menus provided by the GT Theme that you can modify include:

Social Media Links

Shown in the upper-right corner of every page, this menu includes presets for Facebook, Twitter, Google +, LinkedIn, Youtube, etc., plus an RSS feed icon. You can change the location that each icon links to. Be sure to let Institute Communications know if there are other social media outlets you think should be included.

Action Links

This menu appears to the right of your main menu, with a greater-than sign ('>') after each link. To keep things nice and streamlined we've limited the action links to three.

(Super)Footer Links

For the super footer you'll find three separate menus listed as footer links 1-3. If you opt to have a configurable super footer via the theme's appearance settings you'll get a list of default resource links that are hard coded into the the theme (Georgia Tech Resources, and Visitor Resources), and appear as the left column of links in the super footer, but you can customize up to three additional lists.

One thing to note is that the theme includes styling for "nolink" items added via the Special Menu Items module. If you install this module you can add links that serve as headers within a list of resource links to help break them up into different categories. "No link" items would appear like the Visitor Resources header does in the superfooter links on this site. You can also change the name of your resource links menus, which shows up at the top of the list of links.

Footer Utility Links

These links will appear above the standard "legal" links in the footer (Emergency Information, Legal & Privacy Info, etc.) This is ideal for adding a customized "Contact Us" link which can go to your own contact form.

GT Theme Troubleshooting and Advanced Topics

GT Theme Troubleshooting and Advanced Topics klp Thu, 03/03/2016 - 16:46
Drupal Version
Tags

The topics below are for troubleshooting specific problems and doing advanced implementations of the Georgia Tech Drupal theme. Implementing some of these features will require knowledge of advanced Drupal development techniques and/or PHP coding skills.


Advanced Topics Pages

Is Your Site Trying to Use the Google Search Appliance (GSA)?

Is Your Site Trying to Use the Google Search Appliance (GSA)? afrank30 Tue, 01/03/2017 - 11:11
Drupal Version

The Georgia Tech Google Search Appliance (GSA) was shut down at the end of December 2016.  If you are running version 2.9 or later of the GT Theme, then you do not need to worry about this, as version 2.9 and later of the them has had everything related to the Google Search Appliance removed.

If you are still running an older version of the theme, then we recommend that you upgrade to version 2.9 if you can.  If for some reason this is not feasible, then you can make sure your site is not trying to use the Google Search Appliance by doing the following:

  1. Visual check:  Select the 'SEARCH' link (shown with a magnifying glass) on your site.  If the drop-down has any checkboxes below the white search text field, then you need to follow the remediation instructions below.
  2. Search check:  If you don't have those checkboxes, then type something into the box and press Enter or Return.  If you are taken directly to Google, then you need to follow the remediation instructions below.

Remediation Instructions

Again, these instructions only apply if you are running Drupal 7 and the GT Theme.

  1. Log into your site as an administrator
  2. Under Appearance (/admin/appearance), locate your site's active theme under the 'Enabled Themes' section. The active theme for your site is indicated by the words '(default theme)'.
  3. Select the Settings link underneath the active theme's name (example: /admin/appearance/settings/gt_subtheme).
  4. Under the Search Options section, choose the Search This Site option.

To give better results when using Drupal 7's native search ability, you need to change the default search configuration settings.

Go to the Search configuration page at Configuration > Search and metadata > Search settings (or /admin/config/search/settings).

Under the Content Ranking section, change the default value of 0 for these settings:

  • Change Keyword relevance to a nice high number, such as 8.
  • Change Recently posted to a slightly lower number, such as 6.

Important Considerations for the Built-in Search Engine

Anyone leveraging Views or a page replacement module (Panels, Display Suite) will want to thoroughly test the local Drupal search engine, as Drupal's default search does not properly query Views.  In short, pages generated by views or Panels / Display Suite will not be cataloged and will not show up in relevant search query results.

On the flip side, just about all published content in any Drupal content type will be cataloged and shown in relevant search query results.  This means that search queries may turn up pages on your site that you have hidden by simply not linking them into any menus nor linking to them from any menu-linked pages.  Searches will also turn up Super Blocks and old GT Carousel image slides as individual content pages.

If this is a concern for you, you may wish to install the Custom Search module, which will allow you to hide content that you do not want showing up in search query results.

After installing Custom Search, navigate to the Configuration > Search and metadata > Custom Search > Content tab (found at admin/config/search/custom_search/content). At the bottom of the page, under the Content exclusion section, check the types of content, such as Super Blocks, that should NOT appear in search results.

GT Theme v2.8 - Search Text Box Not Appearing

GT Theme v2.8 - Search Text Box Not Appearing
Category
esembrat3 Mon, 03/20/2017 - 09:39
Drupal Version
Tags

Georgia Tech Drupal websites may notice that their search bar stops working after upgrading to version 2.8 of the official Georgia Tech Theme.  If your website was built by a developer or a vendor and uses overwritten template files, your website will likely exhibit this problem.

Symptoms

Search Box Does Not Appear

If your search selector shows an empty box (instead of the usual search box), you need to fix your Georgia Tech subtheme to match the new templates implemented in version 2.8.

 

Errors in Your System Logs

If you see an error like the following in your Drupal system log, your website likely has a broken search box.

Notice: Undefined variable: search_option_value in include() (line X of /var/www/vhosts/dev.coe.gatech.edu/httpdocs/sites/all/themes/[theme name]/page.tpl.php).

Solution

To fix this bug, replace the blob for your search box in any page-*.tpl.php files in your subtheme (sites/all/themes/[subtheme]/templates/[any page- tpl.php file] with the blob of search box code found in the file GT 2.8 Theme file sites/all/themes/gt/templates/page.tpl.php

Do not simply replace/overwrite the subtheme template file, as your subtheme may utilize custom template structure beyond the search box. 

How to Add Block Styles to Your GT Theme

How to Add Block Styles to Your GT Theme
Category
afrank30 Wed, 09/03/2014 - 15:15
Drupal Version
Tags

The GT theme includes some pre-set design treatments for blocks (see lists below of "Body styles" and "Title styles").

All versions of the new GT Theme include the CSS to display these design treatments for blocks, or "block styles". However, you have to manually add these styles to your site via the GT Tools settings to make them available as options when adding/editing blocks.

Option 1: Import SQL code into your database

The fastest way to get the standard styles is to import this sql code into your block_classes table (via phpMyAdmin in your web hosting panel).

Option 2: Create styles manually in your site's administrative interface

Another way to get the standard styles is via the block style class options, which you'll find under the GT Tools options. This is located under the System link (Configuration -> System -> GT Tools if you're using the Administration Menu module).

You can use this same method to add new block designs for your GT SubTheme, using CSS class declarations in your SubTheme and adding block styles classes through the interface (as described above).

Remember, the "Class name" must:

  • exactly match that of the class declaration in your CSS style sheet (e.g. "promo-block"),
  • begin with a letter, and
  • contain only numbers, lowercase letters, hyphens, or underscores.

Default Class names

  • promo-block
  • related-info-block
  • icon-info-title
  • icon-link-title
  • icon-alert-title
  • icon-download-title

As of version 2.5 of the GT Theme, the following styles were added:

  • icon-mortar-board
  • icon-institution
  • block-title-bg-gt-blue
  • block-title-bg-gt-gold
  • block-title-bg-gray

Georgia Tech Modules

Georgia Tech Modules esembrat3 Mon, 10/27/2014 - 12:57
Drupal Version
Tags

A number of custom modules for Drupal have been created by groups at Georgia Tech to aid campus web developers in building Drupal sites and connecting to Georgia Tech specific data sources.  The vast majority of these modules can be found in our central repository, and some of the more notable modules are described below:


Campus Supported Projects

GT Theme

The GT Theme is the official supported implementation of the website branding theme approved by Georgia Tech Institute Communications.  It requires the installation of the GT Tools module first (see below).

GT Tools

The GT Tools module provides some additional functionality that Drupal doesn't support directly in a theme package.  It also includes the GT Content Types sub-module, which provides the special content types "Horizontal Landing Page", "Vertical Landing Page", and "Multipurpose Page".

Mercury (Hg) Reader

The Mercury (Hg) Reader module lets you connect your Drupal site to Georgia Tech Mercury News and Events feeds.

Super Block Module

The Super Block Module provides content blocks preformatted with Georgia Tech design styles and colors.  It is installed like any other Drupal module, and will create a new content type called "Super Block".  The Drupal Editor's handbook describes how to create and use Super Blocks.


Community Supported Projects

The following projects are not supported by Georgia Tech Institute Communications or the Office of Information Technology.  There is some limited help available from the campus web development community, but in general you should not install and use these projects unless you are a skilled Drupal developer who can handle advanced support and troubleshooting of Drupal modules.

GT Editor

GT Editor is a Drupal feature package that implements a WYSIWYG text editor with a great deal more control over what content editors can create, preventing them from doing things that might be dangerous (embedding JavaScript, for example.)  The WYSIWYG Text Editors section has documentation on configuring GT Editor.

GT Login

GT Login is a Drupal feature package that installs the CAS module and configures it to work effectively with the Georgia Tech CAS user authentication server.  Some web developers may prefer to just install the CAS module manually and configure it themselves.

GT SubTheme

GT SubTheme is a theme for Drupal that extends the GT Theme (see above) and makes it easier to add your own customizations to the theme.  Some GT provided modules may expect you to have GT SubTheme installed.

Popular Third-Party (Contrib) Modules

Popular Third-Party (Contrib) Modules root Tue, 12/04/2012 - 14:13
Drupal Version
Tags

This section describes third-party (non-Georgia Tech) modules that could be useful for your Drupal site.  These are often referred to in Drupal documentation as "contrib" modules.

You should only install modules that you absolutely need, so that your site is easier to maintain and patch.  If you decide not to use a module, be sure to disable it, then uninstall it, and finally remove the module from your Drupal filesystem.  (Uninstalling is very important - if you don't uninstall a module before removing it, your Drupal site will through lots of errors at you.)

If you are not sure about what a module will do or if it will be useful, install it to a test instance of Drupal first so that you don't accidentally mess up a good site.


Drupal Contrib Module Lists

Popular Drupal 7 Contrib Modules

Popular Drupal 7 Contrib Modules root Wed, 07/12/2017 - 15:20
Drupal Version
Tags

Please see the introduction to contrib (third-party) modules before installing anything listed on this page.

The following information is provided as-is with no warranty or guarantees of any kind!  While members of the campus community have recommended the following modules for their listed purposes, it's perfectly possible you could blow up your Drupal website if you don't know what you're doing and install them incorrectly or alongside other modules that are incompatible.

Most descriptions are borrowed from the module's home page on the Drupal.org website.

APIs

These are only needed if required by another module.  The ones listed below are some of the most commonly used API modules.

  • Libraries - Introduces a common repository for libraries in sites/all/libraries and sites/<domain>/libraries
  • Chaos Tools (CTools) - A set of APIs and tools to improve the developer experience
  • Entity API - Extends the entity API of Drupal core in order to provide a unified way to deal with entities and their properties
  • FlexSlider - Integrates the Flex Slider library with Drupal, which allows you to build responsive, resizable slideshows 
  • Advanced Help - Provides support for advanced help documentation in modules provided in standard HTML format
  • JQuery Update - Upgrades the version of jQuery in Drupal core to a newer version of jQuery

Administrative Tools

  • Administration Menu - Administrative links are displayed in a CSS/JS-based menu at the top on all pages of your site, including links to common tasks and actions
  • Module Filter - Lets you more easily see installed modules grouped by type and quickly search through them
  • Filter Permissions - Provides filters at the top of the Permissions page for easier management.
  • Node Convert - Node Convert adds a menu tab "Convert" on the node view page that gives the ability to convert the node from its current content type to another content type.

User Authentication

Security

  • SpamSpan - Obfuscates email addresses to help prevent spambots from collecting them
  • Honeypot - Uses both the honeypot and timestamp methods of deterring spam bots from completing forms on your Drupal site
  • CAPTCHA - Provides CAPTCHA ("Are you a human?") challenge-response tests to virtually any user facing web form on a Drupal site.
  • SpamicideSpamicide adds an input field to each form then hides it with css, when spam bots fill in the field the form is discarded
  • BOTCHA - In BOTCHA, we don't abuse our human users - protection is completely transparent to them and non-intrusive. BOTCHA lets spambots to prove they are bots, and lets real users zip by
  • Mollom - Connects your site with the Mollom network to help determine if posts or comments are spam.
  • Security Review - Automates testing for many of the easy-to-make mistakes that can make your site insecure

User Interface

  • CK Editor - Allows Drupal to replace textarea fields with the CKEditor - a visual HTML editor, usually called a WYSIWYG editor
  • IMCE - An image/file uploader and browser that supports personal directories and quota
  • Image Resize Filter - Just insert an image and set it's height and width properties in HTML (done automatically by WYSIWYG editors) and the image is resized on output to match the HTML
  • Adaptive Image Styles - Allows any image to be adaptive simply by setting it to be rendered with the 'adaptive' image style.  Adaptive images are sized down based on the user's detected screen size, reducing bandwidth and load times.  [Requires .htaccess modifications]

Navigation / URL Paths

  • 404 Navigation - Causes Drupal to render the primary/main menu on 404 (page not found) error pages
  • Pathauto - Automatically generates URL/path aliases for various kinds of content (nodes, taxonomy terms, users) without requiring the user to manually specify the path alias
  • Pathologic - An input filter that can correct paths in links and images in your Drupal content in situations which would otherwise cause them to “break;” for example, if the URL of the site changes, or the content was moved to a different server
  • Redirect - Work in progress for a Drupal 7 integration and collaboration between redirection-type modules: Path Redirect and Global Redirect
  • Global Redirect - Makes sure that all ways to access a page redirect with 301 errors to a single URL path, which optimizes a site for search engines

Design / Layout

  • Paragraphs - Allows you — Site Builders — to make things cleaner so that you can give more editing power to your end-users
  • Node Block - Allows you to have nodes of specific content type(s) be provided as blocks, combining the editing flexibility of node fields with the placement flexibility of Drupal blocks
  • Panels - Allows a site administrator to create customized layouts for multiple uses
  • Menu Block - Provides configurable blocks of menu trees starting with any level of any menu

Flow and Logic

  • Workflow - Allows you to create arbitrary Workflows, and assign them to Entities
  • Revisioning - Allows for the configuration of workflows to create, moderate and publish content revisions
  • Rules - Allows site administrators to define conditionally executed actions based on occurring events (known as reactive or ECA rules)
  • Override Node Options - Allows permissions to be set to each field within the Authoring information and Publishing options field sets on the node form

Data Integration / Migration

  • Views - Provides a GUI for processing, sorting, and displaying data
    • Views Data Export - Provides a way to export large amounts of data from views [Requires Views module]
    • Views Bulk Operations - Augments Views by allowing bulk operations to be executed on the displayed rows [Requires Views module]
  • FeedsImport or aggregate data as nodes, users, taxonomy terms or simple database records
    • Feeds Extebsible Parser - A set of extensible parsers for Feeds [Requires Feeds module]
    • Feeds Tamper - Provides a small plugin architecture for Feeds to modify data before it gets saved [Requires Feeds module]
  • Bundle Copy - This module has export/import support for: Node types, Taxonomy, User, Field API fields, and Field groups

Fields and Forms

  • Link - Provides a standard custom content field for links
  • Date - This package contains both a flexible date/time field type Date field and a Date API that other modules can use
  • Location - Allows real-world geographic locations to be associated with Drupal nodes, including people, places, and other content
  • Entity Reference - Provides a field type that can reference arbitrary entities
  • Block Reference - Defines a field type that creates a relationship to a block and allows the block to be displayed as the content of the field
  • File (Field) Paths - Allows you to automatically sort and rename your uploaded files using token based replacement patterns to maintain a nice clean filesystem
  • Transliteration - Provides one-way string transliteration (romanization) and cleans file names during upload by replacing unwanted characters
  • Conditional Fields - User interface to the new States API, plus the ability to modify fields appearance and behavior on certain conditions when viewing content
  • Field Permissions - Allows site administrators to set field-level permissions to edit, view and create fields on any entity
  • Field Group - All fieldable entities will have the possibility to add groups to wrap their fields together. Fieldgroup comes with default HTML wrappers like vertical tabs, horizontal tabs, accordions, fieldsets or div wrappers
  • Webform - Allows for the creation of user friendly forms and surveys in Drupal complete with email receipts and data export

Popular Drupal 8 Contrib Modules

Popular Drupal 8 Contrib Modules root Wed, 07/12/2017 - 15:25
Drupal Version
Tags

Please see the introduction to contrib (third-party) modules before installing anything listed on this page.

The following information is provided as-is with no warranty or guarantees of any kind!  While members of the campus community have recommended the following modules for their listed purposes, it's perfectly possible you could blow up your Drupal website if you don't know what you're doing and install them incorrectly or alongside other modules that are incompatible.

Most descriptions are borrowed from the module's home page on the Drupal.org website.

Below is a list of popular contrib modules that have been ported to Drupal 8 and appear to work properly.  Do note that not all have "production" releases yet.

The following are being ported, but with notable changes, and are note quite ready for prime time yet:

  • Webform - Is being rebuilt from the code base of YAMLForm for Drupal 8 - still in beta at the moment

Location and Gmap

Location and Gmap
Category
esembrat3 Thu, 10/02/2014 - 08:59
Drupal Version
Tags

Location and gmap modules provide embedded Google Maps for Drupal websites. 

However, the documentation and readme for configuring both of these modules is sparse, if available. Most documentation on how to utilize these modules as a pairing exist in knowledgebase entries and bug reports, which makes development using these two modules a chore.

Installing and configuring these modules takes a few main steps.

Installation

  1. Download Location and Gmap from Drupal, using the most recent stable releases for Drupal 7.
  2. Add these modules to your sites/all/modules folder.
  3. Log in to the website you wish to add these modules to.
  4. Enable these modules.

Configuration: Google

  1. Using a Google account, access the Google API Console.
  2. Create a new project.
  3. Under APIs & auth -> APIs, enable Geocoding API (for the Geocoding service of Location) and Google Maps Javascript API v3 (for Gmap). 
  4. Create a server key (for Geocoding), making sure to restrict the IPs to your server.
  5. Create a browser key (Gmap), making sure to restrict the referers to your domain(s).

Configuration: Drupal

  1. Log in as an administrator to your website.
  2. First, edit Location at: admin/config/content/location
  3. Under 'Geocoding Options', enable 'Google Maps' for United Statres.
  4. Under 'Configure parameters', enter the server key from above into the 'Google Geocoding API Server Key'. 
  5. Click 'Save Configuration'.
  6. Second, edit Google Maps at: admin/config/services/gmap
  7. Under 'Google Maps API Key', enter the browser key from above.
  8. Click 'Save Configuration'.

Configuration: Field

  1. Create a content type which utilizes a Location field.
  2. On the field options, disable the postal code, as this feature tends to break geolocation in some instances.
  3. Save the field.
  4. Test by creating a new node!

Web Forms on Drupal Sites

Web Forms on Drupal Sites afrank30 Wed, 10/01/2014 - 09:51
Drupal Version
Tags

This section is for guides, tips, and tricks for creating and managing web based submission forms on Drupal sites.  It will primarily deal with the Webform module, but could include information on other tools that provide form capabilities.

Adjusting the 'From' Address in Webform Generated Emails

Adjusting the 'From' Address in Webform Generated Emails esembrat3 Thu, 11/19/2015 - 09:17
Drupal Version

A bug exists in Webform 3.x that can prevent you from changing the "From" address in an automated email template.  There is an existing Drupal.org discussion about this issue: https://www.drupal.org/node/1804214#comment-9661515

Drupal 7 Fix

  1. Visit Configuration -> Content -> Webform (admin/config/content/webform).
  2. Uncheck the Use Reply-To header option
  3. Save your changes.

Securing Web Forms

Securing Web Forms afrank30 Tue, 01/26/2016 - 09:20
Drupal Version
Tags

If not properly secured, forms can easily be used by hackers and automated "bot" programs to gain access to information within our sites, deface a site, or or even gain access to all the sites on a shared server.  The following is a non-exhaustive list of tips for making any web-based form more secure.

Form Safety Tips

  • Never ask for sensitive information or information you don't need. Examples include birth date, credit card number, student data (including GTID), and other sensitive data.
  • Protect your form with CAS login (for campus) or with CAPTCHA (for people without GT accounts).
  • Remove old data and forms.
  • Regularly archive and then delete old submissions and forms
    • Go in every month or semester and download the old submissions to a spreadsheet, and then delete those submissions from the website.
    • Close or remove web forms when they are no longer in use.
  • Use HTTPS for your site.

WYSIWYG Text Editors

WYSIWYG Text Editors root Tue, 12/04/2012 - 14:14
Drupal Version

While Drupal 8.0 comes with the CKEditor WYSIWYG (What You See is What You Get) text editor, Drupal versions before 8.0 do not come with any kind of WYSIWYG text editor by default.  A WYSIWYG text editor gives your content editors a way to create and maintain content using an interface that looks and feels a lot like using a word processor.  Formatting is applied using button controls, so the content editor doesn't have to know anything about HTML and can immediately see what the content is going to look like after it has been saved.

There are two popular options on campus for a WYSIWYG text editor:

  • CKEditor Drupal module and CKEditor library:  This popular editor is easy to set up and gives you a wide range of flexibility in what your content editors can create.

  • Georgia Tech GT Editor module:  This module is actually built around CKEditor, but provides a great deal more control over what content editors can create, preventing them from doing things that might be dangerous (embedding JavaScript, for example.)


WYSIWYG Text Editor Guides and Resources

Installing CKEditor in Drupal 7

Installing CKEditor in Drupal 7 esembrat3 Fri, 02/22/2013 - 10:52
Drupal Version
Tags

There are two parts to installing CKEditor for Drupal 7 (Drupal 8 comes with it already installed):

  1. The Drupal module, which is placed in the sites/all/modules folder.
  2. The CKEditor library, which is placed INSIDE the sites/all/libraries folder.

After installing the module and library, enable the module and it should take effect immediately.

If you want to customize your CKEditor settings, look in the administrative configuration area under Content Authoring -> CKEditor.

CKEditor Companion Modules

CKEditor Companion Modules esembrat3 Wed, 01/09/2013 - 10:27
Drupal Version

The Drupal community on campus has found a number of modules which help with using CKEditor:

IMCE

​IMCE can be used for managing images, and you might even use imce for files, as well.

Installation instructions for IMCE:

  1. Download, install, and configure IMCE.
  2. Remove the default Image button.
  3. Add the IMCE button.
  4. Enable the option "Plugin for inserting files from imce without image dialog".
  5. Enable the option "Plugin for inserting Drupal embeded media".

LinkIt

Linkit can be used for managing URL links to pages on the site and outside of the site.

Installation instructions for LinkIt:

  1. Download, install, and configure LinkIt
  2. Remove the default URL button.
  3. Add the LinkIt button.
  4. Check "Support for Linkit module".

Image Resize Filter

From the Drupal.org site:  Image Resize Filter makes it easy to resize images, especially when combined with a WYSIWYG editor such as tinyMCE, CKeditor etc. Users never have to worry about scaling image sizes again, just insert an image and set it's height and width properties in HTML (this is done automatically by WYSIWYG editors) and the image is resized on output to match the HTML.

Creating a True WYSIWYG Environment in CKEditor

Creating a True WYSIWYG Environment in CKEditor eh94 Thu, 09/11/2014 - 12:42
Drupal Version

If you'd like the look and feel of your body text field to better mimic the look and feel of your site's theme when editing pages then you'll need to configure the CSS settings for the appropriate CKEditor profiles to use your theme's CSS.

  1. Go to Configuration -> Content authoring -> CKEditor
  2. Select the Edit link under the OPERATIONS row for the appropriate CKEditor profile (advanced, basic, etc.)
  3. Under the CSS accordion fieldset change the Editor CSS drop-down to use "Define CSS"
  4. In the CSS file path field you'll need to enter the path to the CSS file(s) of your theme. If you'd like it to use the CSS from the main GT theme, enter the following:
    /sites/all/themes/gt/css/reset.css?v=1,/sites/all/themes/gt/css/default.css?v=1,/sites/all/themes/gt/css/typography.css?v=1,/sites/all/themes/gt/css/editor.css?v=1

    Note the query string at the end of each CSS file listed (i.e., "?v=1") If you are experimenting with adding links to your own stylesheets and are finding your changes aren't showing up, just change the value in the query string, save the CKEditor settings, and next time you edit a page your changes will most likely show up. By changing the query string value you'll get CKEditor to reload the stylesheet.

See Adding Classes to the CKEditor Styles Dropdown List if you'd like to add new custom styles there as well.

Adding Classes to the CKEditor Styles Dropdown List

Adding Classes to the CKEditor Styles Dropdown List afrank30 Thu, 01/23/2014 - 10:15
Drupal Version

If you want your editors to be able to easily apply your custom CSS classes via the Styles drop-down list in the GT Editor:

  1. Copy the js/ckeditor.styles.js file from the GT Theme (version 7.x-2.2 and above) into your subtheme folder.
  2. Add your own CSS styles to this file. The CKEditor documentation explains how this works.
  3. Go to Configuration -> Content authoring -> CKEditor
  4. Select the Edit link under the OPERATIONS row for the appropriate CKEditor profile (advanced, basic, etc.)
  5. Under the CSS accordion fieldset change the Predefined styles drop-down to "Use theme ckeditor.styles.js"
  6. Flush your browser's caches to get CKEditor to pick up the new file.  You'll need to flush your browser's caches each time you update this file.

If you'd rather not rely on users caches expiring or telling them to flush their caches, you can use another technique to specify your styles file:

  1. Go to Configuration -> Content authoring -> CKEditor
  2. Select the Edit link under the OPERATIONS row for the appropriate CKEditor profile (advanced, basic, etc.)
  3. Under the CSS accordion fieldset change the Predefined styles drop-down to "Define path to ckeditor.styles.js"
  4. Set the Predefined styles path to point to your custom styles file.  Add "?v=XXX" where XXX is some random value.  Change this value each time you make changes to your styles file.  This change will trigger web browsers to consider the file to be updated and to ignore the version held in the browser cache.

NOTE: If you implement a custom ckeditor.styles.js file,  you'll need to remember to integrate into this file any changes to the standard styles introduced by any newer version of the GT Theme.

Embedding Digital Videos in CKEditor / GT Editor

Embedding Digital Videos in CKEditor / GT Editor afrank30 Tue, 03/31/2015 - 10:23
Drupal Version

Embedding Georgia Tech MediaSpace Repository Content

A good solution for the Georgia Tech MediaSpace (Kaltura) repository has not been developed yet.  In the meantime, an experimental MediaSpace embed module is available for Drupal 7 from the developer who created the embed module for the now retired OIT Digital Media Repository.  Look for the GT Kaltura Embed Module download on that page.  Use at your own risk!

A Drupal 8 version of the GT Kaltura Embed Module is also available in the IAC Drupal 8 Repository (available on-campus only).

After installing either module, you will have to add the new input filter to your preferred text formats.  Make sure to set the ordering so that the filter comes last after all other filters.  This ensures that the filter's Javascript code does not get filtered out by any of your other text filters.

Embedding OIT Digital Media Repository Content

The OIT Digital Media Initiatives (DMI) has been retired.  Please use the Georgia Tech MediaSpace repository (see above) for all of your media repository needs.

Embedding YouTube and Vimeo Videos

Option #1 - Video Embed Field (Drupal 7 or 8)

  1. Download, install, and enable the Video Embed Field module.
  2. Add the new video field type to one or more of your Drupal Content Types.
  3. Content editors can now add videos to nodes of those content types by inserting the right linking details into the video field.
  4. WebWash provides a tutorial about video styles you can create with the Video Embed Field module.

Option #2 - Video Filter (Drupal 7)

  1. Download, install, and enable the Video Filter module.
  2. In the administrative configuration area of Drupal under Content authoring -> Text formats, configure each text format that you want to be able to use embedded videos.
    1. Enable the video filter.
    2. In the Filter processing order section, move the video filter down to the bottom of the list so that it is applied after all other filters.
    3. Don't forget to save your changes.
  3. On pages that use one of these configured text formats, you can now insert a video shortcode to create an embed of a supported video type.  See the download page at the link above for the full list of supported video services and formats.
  4. Example shortcode for embedding a video:

[ VIDEO::http://www.youtube.com/watch?v=98nNpzE6gIs::aVideoStyle ]

GT Editor Site Administrator Documentation

GT Editor Site Administrator Documentation root Fri, 07/07/2017 - 14:56
Drupal Version
Tags

The Georgia Tech GT Editor module is built around CKEditor, but provides a great deal more control over what content editors can create, preventing them from doing things that might be dangerous (embedding JavaScript, for example.)

This is a community supported project, meaning it is not officially supported by OIT or Institute Communications.


GT Editor Guides and Tutorials

Installing GT Editor in Drupal 7

Installing GT Editor in Drupal 7 afrank30 Thu, 01/23/2014 - 10:05
Drupal Version
Tags

Below are instructions for installing and configuring the GT Editor feature, which extends the CKEditor rich text editor to add additional tools for image, file, and video management, as well as security settings that filter out unacceptable code.

Editor's Note:  These instructions are for version 7.x-2.3 of GT Editor.

Video introduction

Watch an overview of GT Editor in minutes 1:39 to 1:45 of this video from our November 2013 GT Build Day.

Train Your Editors

Training guides can be found under the "Basic Training for GT Editor" section of this site.

Prerequisites (Things to Install First)

User Roles and Content Types

This feature assumes you are using the three user roles and three content types created by GT Tools

Libraries

You must install the CKEditor Library (currently version 4.4.3-full) in sites/all/libraries.

GT Modules and Themes

You should also install these GT features/themes:

Drupal Contrib Modules

You should also install (in sites/all/modules) these contributed Drupal modules:

GT Editor Installation

Once you have installed all of the above items, you can then install the GT Editor module like you would any other module.

Multi-sites and Path Issues

If you install GT Editor on a multi-site, you will need to change a number of path settings (as they are designed for a single, root site).  Here are some of the locations to change paths:

  • "Predefined styles path" at admin/config/content/ckeditor/edit/basic
  • "File system" for public, private, and temporary file directories at admin/config/media/file-system

My Links Menu (A.K.A. "Editor menu of POWER")

GT Editor, when installed, creates a new My Links menu for the Editor role.  Here are the links that GT Editor (as of version 7.x-2.3) adds to this menu:

  • add or change Events (Mercury)
  • get new Events (Mercury cache)
  • find Pages (list)
  • change Menu links
  • new Page
  • new Horizontal layout
  • new Vertical layout
  • new Multipurpose layout
  • new Block
  • move Blocks

You will need to alter the new link "get new Events (Mercury cache)",  as the default link goes to "http://mysite.gatech.edu/?clearcache=1". You need to change "mysite" to whatever your site's actual domain name is. This link makes it easier for editors to clear their cache in Mercury, to force updated events and news to show up in their Mercury blocks almost as soon as they are added to the Mercury system.

    Allowing Additional CSS Classes in GT Editor

    Allowing Additional CSS Classes in GT Editor
    Category
    afrank30 Thu, 01/23/2014 - 10:01
    Drupal Version
    Tags

    Are you adding design elements with CSS and want editors to be able to use your new CSS classes within GT Editor?  You may have discovered that those classes are being stripped out when the page is saved.  What's happening is that GT Editor operates on a whitelist principle to keep your site and its content safe. You must add any elements, classes, etc. that you want to use to the editor's whitelist - otherwise, it will assume the worst and remove them when you save a page.  GT Editor strips all non-whitelisted classes and elements using the WYSIWYG Filter module. This module is configured within each text format (such as the "basic text editor" format that comes standard in GT Editor).

    The Easy Way: Use Standard "gt-ed-*" Class Naming

    The latest versions of GT Editor (7.x-2.0-beta1 and above) will allow any CSS class that starts with "gt-ed-".  So, if you don't mind adding CSS classes that use this naming format, you're done.

    Create Your Own Text Format

    If you want to use CSS classes that aren't in the "gt-ed-" naming format, you will need to create your own text format (at admin/config/content/formats). This way, any changes you make to the format won't be overwritten when you update the GT Editor.

    It is recommended that you copy the settings from the existing basic text editor text format into your new format, and THEN make changes. If you take this approach, you'll need to remember to integrate changes to this format from each new GT Editor version.

    To add to the whitelist of classes, look under your text format's WYSIWYG Filter settings at: admin/config/content/formats/text_editor_basic. You will see sections called Rules for Class Names and Rules for Element IDs where these filters are configured.

    Unhiding the CKEditor Text Format Selector

    Unhiding the CKEditor Text Format Selector afrank30 Thu, 01/23/2014 - 10:21
    Drupal Version

    CKEditor normally shows a Text format drop-down selector just below the editing window, but the GT Editor hides this selector to streamline the editing experience.  However, there can be cases where you want to use other Drupal text formats for special cases (e.g. embedding a Twitter or Facebook feed).

    The GT Subtheme has CSS code that hides the drop-down, which you can find at sites/all/themes/gt_subtheme/css/gt_subtheme.css.  The lines that hide the text format dropdown box are:

    
            div.form-item-log,
    	.preview h3,
    	.preview .node-teaser,
    	body.page-admin-structure-block-add .form-item-regions-seven,
    	body.page-admin-structure-block-manage-block .form-item-regions-seven,
    	fieldset#edit-body-und-0-format,
    	fieldset#edit-field-body-1-und-0-format,
    	fieldset#edit-field-body-2-und-0-format,
    	fieldset#edit-field-body-3-und-0-format
    	{
    	   display: none;
    	}
    

    Changing the Default Format Without Displaying the Text Format Selector

    If you have created your own text format and want your editors to use it instead of the "basic text editor" format, you should change the order of the text formats so that yours is first/on top at admin/config/content/formats.

    GT Editor Paragraph Image Wrapping Problem

    GT Editor Paragraph Image Wrapping Problem esembrat3 Tue, 11/08/2016 - 08:25
    Drupal Version

    Some Georgia Tech Drupal users have encountered a bug where CKEditor/WYSIWYG settings were wrapping standalone images in paragraph tags.  To fix this problem, follow the two steps below.

    Step 1. Adjust Your Theme's template.php.

    In your theme’s template.php file, add:

    /**
    * Implements hook_wysiwyg_editor_settings_alter()
    */

    function THEMENAME_wysiwyg_editor_settings_alter(&$settings, $context) {
      if ($context['profile']->editor == 'ckeditor') {
        $settings['autoParagraph'] = FALSE;
      }
    }

    Be sure to replace "THEMENAME" with the actual machine name of your theme.  For the standard GT theme, the function name would be gt_wysiwyg_editor_settings_alter

    Step 2. Adjust Your Text Format.

    In your browser, go to {domain}/admin/config/content/formats and modify each text format that your site is actively using.  F or your specified text formats (here I’m listing the Advanced one), located at , make sure that the option "Convert line breaks into HTML (i.e. <br> and <p> )" is turned off.

    Using Block Templates to Safely Add PHP Code to a Page

    Using Block Templates to Safely Add PHP Code to a Page
    Category
    afrank30 Fri, 02/13/2015 - 14:09
    Drupal Version

    Editor's Note: While the methods outlined below do work, the recommended way of adding dynamic pages (pages with content controlled and/or generated using PHP code) is by creating a custom module (Drupal 7 custom module tutorial | Drupal 8 custom module tutorial).

    You can use the following method when you want to use third party embed code (for a Google Map, for example, or a twitter feed), but without compromising the security of your site by (shudder) turning on the PHP code filter or allowing unfiltered HTML formats.

    Instructions

    1. Create a normal block (not a Super block!), and don't type anything other than spaces into the Body field.
    2. Write down the block's ID number, which will show in the URL after you save the block and go back to that block's "Configure" page. For example, in the URL http://example.gatech.edu/admin/structure/block/manage/block/30/configure, the block id is the number between "block" and "configure", in this case, 30.
    3. Add this block to a page on your site, preferably a test page that no one will find, and keep that page open in your web browser.
    4. In the subtheme for your site, usually within its "templates" folder, create a file that will only effect this specific block.  For our example block #30, the file would be named block--block--30.tpl.php
    5. Inside this file, first paste the code for a generic block template file (Drupal 7) from the View source sub-section of the File section of the Drupal block API documentation page (Abbreviated source example copied below).
    6. If you want to completely overwrite what people might type into the Body field of this block, then replace the <?php print $content ?> line. Otherwise, decide if your embed code should appear below or above whatever the Body field's content.

    Sample Block Template Code (Drupal 7)

    <?php

    /**
     * @file
     * Default theme implementation to display a block.
     * For variables definition, visit:
     * https://api.drupal.org/api/drupal/modules!block!block.tpl.php/7
     */
    ?>
    <div id="<?php print $block_html_id; ?>" class="<?php print $classes; ?>"<?php print $attributes; ?>>

      <?php print render($title_prefix); ?>
    <?php if ($block->subject): ?>
      <h2<?php print $title_attributes; ?>><?php print $block->subject ?></h2>
    <?php endif;?>
      <?php print render($title_suffix); ?>

      <div class="content"<?php print $content_attributes; ?>>
        <!-- DELETE PRINT LINE BELOW IF OVERWRITING BODY OF BLOCK -->
        <?php print $content ?>
        <!-- START EMBED CODE HERE -->
        <!-- END EMBED CODE HERE -->
      </div>
    </div>

    Administrative Tips and Tricks

    Administrative Tips and Tricks root Wed, 07/12/2017 - 15:32
    Drupal Version

    This section collects useful tips and tricks for administering a Drupal website.


    Guides and Resources

    Using Node Convert to Change a Node's Content Type

    Using Node Convert to Change a Node's Content Type afrank30 Tue, 07/22/2014 - 14:03
    Drupal Version
    Tags

    The Node Convert module can be used to switch between different page layouts without losing existing content.  One example is changing a Basic page so that it uses a Horizontal Landing Page layout.

    Overview of Process

    1. After backing everything up, install the contributed Node Convert module in the usual way.
    2. Go to People -> Permissions and set permissions for your different user roles.
    3. Optionally, if you have a LOT of content to convert, or are just feeling super fancy, you can also create "node convert templates".

    Set Permissions for Users, Based on Their Role

    In your site's Administration interface, go to the page where you manage which features people can use on your site. In Drupal 7, this can be found at People -> Permissions (admin/people/permissions). The main roles usually needing permissions for converting layouts are Editor and Super Administrator.

    Editor Permissions

    Give the "Editor" role permission to convert To AND From each of the four (4) main page layouts, by checking the boxes next to these specific permissions:

    • convert from page
    • convert to page
    • convert from horizontal_landing_page
    • convert to horizontal_landing_page
    • convert from multipurpose_page
    • convert to multipurpose_page
    • convert from vertical_landing_page 
    • convert to vertical_landing_page

    Super Administrator Permissions

    Give the "Super Administrator" role all of the same permissions as an Editor, but then also check the "administer conversion" box.

    (Optional) Make Templates for converting content in large batches

    If you need to convert a LARGE amount of content, you can make this easier by creating "Node Convert templates" (under "admin/structure/node_convert_templates" in Drupal 7).

    Read documentation and examples of how to create and use these templates at:

    Field Boilerplate Help Text

    Field Boilerplate Help Text esembrat3 Thu, 05/24/2018 - 14:09
    Drupal Version

    Certain fields likely need additional explanatory text accompanying it.

    YouTube Field

    Per Georgia Tech's accessibility requirements, any publicly-available video must be captioned for end-users. YouTube's automatic captions are not enough to meet full guidance. Please see the Video Captioning and Audio Transcripts for more information.

    Image Field

    Per Georgia Tech's accessibility requirements, any image must have alternative-text describing the visual component of the text except the image is purely decorative.

    Security Tips

    Security Tips afrank30 Tue, 08/27/2013 - 10:51
    Drupal Version
    Tags

    The pages in this section provide helpful tips and tricks for improving the security of your Drupal website.  In addition to the information here, be sure to browse through the User Authentication section for more security tips, including how to require user login before viewing specific pages.


    Security Resources

    Keeping your Site Safe

    Keeping your Site Safe afrank30 Tue, 08/27/2013 - 11:54
    Drupal Version
    Tags

    Editor's Note: These tips are based on notes from “Securing Drupal 7: Don’t get Hacked or Spammed to Death!” presented at the February 2013 Georgia Tech Drupal User's Group Meeting.  Please feel free update with additional tips for securing Drupal sites!

    Secure YOUR Code

    • Drupal.org Guide to Writing Secure Code
    • Be careful if you write a module or make code changes to a Theme!!
      • Separate/Comment any changes to Code.
      • Don't hack CORE!
    • Don't install non-recommended modules, libraries, or themes
      • Test anything you're not sure about in a separate sandbox instance of Drupal

    Secure Drupal Core

    Update Drupal Core When Needed

    • Make sure the Update manager module is ON and configured for security emails (admin/reports/updates/settings)
    • Apply every security patch after backing up EVERYTHING
      • Module updates are EASY in Drupal 7
      • Installatron makes CORE updates easier (but MUST backup .htaccess and robots.txt).
    • Drupal Security Review Contrib Module - Scans your installation for common security problems

    Properly Configure Modules and Module Settings

    • Turn off the following modules unless you really need them:
      • PHP filter (Always keep this one off!)
      • Tracker
      • Comments
    • Configuration -> Logging and errors -> Error messages to display:  Set to None
    • Configuration -> Logging and errors -> Error messages to display:  Set to 1000 (or 10,000 if you have a really busy site)
    • Configuration -> Media -> File system:  Consider making private if that works for your site

    Properly Configure User Account Settings

    • Check over the User Account settings (Configuration -> People -> Account Settings)
      • Self registration for user accounts is enabled by default!  Configure Who can register accounts? so that only Administrators can register accounts.
      • Set the default for When cancelling a user account to "Disable the account and keep its content.”, because deleting users who have created content could lead to access bypass.  Alternatively, validate whether or not the user had ever created any content, and reassign the content to someone else before deleting the user account.
      • Disable the setting Enable personal contact form by default
      • Disable the setting Enable signatures (because it applies to ALL)
      • Disable the setting Enable user pictures (because it applies to ALL)
    • Regularly review your list of users (admin/people)
    • Disable User #1 in Drupal 7 as it is not needed
      • Configure a regular user account with administrative powers and use it instead
      • Rename user #1 from something common like 'admin' or 'root' to make it harder for hackers to guess the username

    Properly Configure User Permissions

    • Review user permissions regularly (admin/people/permissions)
    • Give the ANONYMOUS and AUTHENTICATED roles only View published content, add more permissions only if NEEDED.
    • Only Developer/SuperAdmin roles should get any permission that stats with "Administer”
      • (Possible) Exception. You might give EDITORS "Administer” for: Blocks, Comments, Menus.
    • Contrib Modules for fine grained permissions:
      • Override Node Options,
      • Role Delegation
      • Field Permissions, etc.

    Properly Configure Filters

    NOTE: Tailor the following to the needs of your site - not all sites need such strict rules in place.

    • Drupal.org Guide to Configuring Text Formats
    • Do NOT allow these tags: SCRIPT, IMG, IFRAME, EMBED, OBJECT, INPUT, LINK, STYLE, META, FRAMESET, DIV, SPAN, BASE, TABLE, TR, TD
    • ORDER of Filters (plain text for ALL at TOP)
    • Filter Permissions (limit ANONYMOUS & AUTHENTICATED to plain, give EDITOR basic)
      • More filters details in the Contrib modules section below.

    Contrib (Third Party) Modules and Themes

    • Disable or un-install modules you are not using (UI & Devel modules, like Masquerade). Regularly audit sites for unused modules.
    • Criteria for evaluating contrib (Erik Webb):
      • supported version(s)
      • maintainer reputation
      • total usage
      • number of open issues
      • usage change over time
    • Criteria 2: allows PHP execution? Some modules that do are: Devel; CCK fields; Views; Webform

    Contrib: CAS and Captcha/Spamicide

    • For GTaccount holders, CAS module (requiring GT Logins for certain pages/forms) will usually be sufficient to protect individual content types/forms
      • admin/config/people/cas
      • Redirection > Specific pages
      • If ANONYMOUS users can Add content or can Login, MUST HAVE Captcha + Spamicide
    • Helpful Tool: StopSpamForum.com (esp if you Block IPs in your Drupal site).

    Contrib: Editor and More Filters

    • Because user content is dangerous, pay attention to settings for editing and file uploading modules.
    • Who can use IMCE to add files/images & which file extensions are allowed? (profile)
    • Who can use LinkIt to make a Link? (profile)
    • Use WYSIWYG Filter to strip out unwanted code
    • Limit buttons on CKEditor Toolbar
    • Use Plain Text for ANONYMOUS users and on most TextArea Fields.

    Contrib: Field Permissions and Privacy

    • Create unique names for every field that holds remotely-sensitive info. Why? Because permissions are by FIELD NAME regardless of content type
      • Example: field_user_address, if used on 2 different forms, has the SAME permissions on both forms.
    • Tip: Use bundle_copy module to make a generic Content Type with pre-set fields & display settings that’s easy to alter & copy.
    • Types of data NOT to store and NOT to share:
      • FERPA student data not in directory (directory = name, email, field/dept)
      • HIPAA health-related
      • Identity theft-prone (SSN, Birthdate, etc.)
    • Types of permissions for fields and content types:
      • create
      • edit OWN; view OWN (might be safe)
      • edit ANY; view ANY (editors or admins only)
      • delete OWN; delete ANY (be careful, admins only)

    Contrib: Webform

    • http://drupal.org/project/webform
    • NOT good at fine-grained permissions
    • Can have PHP execution vulnerabilities
    • You have MUCH better better access control & reporting options (Views), if you use Content Types, instead.
    • Content types are Safer, but harder to delegate to editors for set up.

    Contrib: Views

    • http://drupal.org/project/views
    • Very popular, will be Core in Drupal 8.
    • Allows you to report out on data in LOTs of ways
    • Must take care with PERMISSIONS, esp by Role, for each View, esp if any data is private or sensitive.
    • Be careful not to allow PHP in arguments, unless necessary.

    Contrib: Pathauto and Auto Label

    External Libraries and Code

    • SUGGESTIONS requested. HOW Can we: ?
      • Regularly check libraries for security notices (CKeditor, phpCAS, jquery.cycle, etc.).
      • Audit 3rd party code for security holes (such as superglobals like $_GET)
      • Audit libraries’ example code or other 4th party included packages.
      • Discover unneeded code to remove from libraries (and, of course, notate in README.txt file)

    Editor Support

    • Training, especially security implications of:
      • forms
      • comments
      • file types
      • tag choices in HTML
    • Regular audits of content + users
      • every semester
      • less files/revisions/people to look over if hacked
      • less chance of un-used file/account being co-opted

    Server and Monitoring

    • Not a good use of time to try to hide clues that a site runs on Drupal (http://drupal.org/node/766404)
    • Robots.txt (only works on good search engines)
    • .htaccess (can limit to on-campus or VPN access, Drupal already hides directories)
    • use HTTPS, instead of HTTP
    • Securing file permissions and ownership (settings.php, etc., http://drupal.org/node/244924)
    • Regular BACKUPS (and diffs for comparison)
    • Avoid installing multiple applications on same hosting account (i.e. Wordpress AND Drupal)
    • Avoid storing ANYTHING other than the Drupal install in the web ROOT (httpdocs).

    References

    Setting Up SSL For Drupal Sites on OIT Web Hosting

    Setting Up SSL For Drupal Sites on OIT Web Hosting esembrat3 Thu, 06/16/2016 - 09:24
    Drupal Version
    Tags

    Editor's Note: Information on Obtaining and SSL Certificate and Setting Up SSL on OIT Web Hosting with an External Domain Name has been moved to the Georgia Tech Resources for Webmasters website.

    Additional details about enabling SSL for Drupal can be found in Jimmy Kriegal's posting in GitHub about SSL and Drupal sites.

    Part I: SSL Certificate

    See if you need an SSL Certificate, and if so, obtain your SSL Certificate

    Part II: Configure Your Drupal Instance

    Edit Your Site's .htaccess File

    Add the following directly after "RewriteEngine On" in your site's .htaccess file:

    RewriteCond %{HTTP_HOST} ^www\.(.+)$ [NC]
      RewriteRule ^ https://%1%{REQUEST_URI} [L,R=301]

    Edit Your Site's settings.php File

    Find the line for "$base_url" (or add one if this setting is not defined), and set it to the the fully qualified domain name of your site, like so:

    $base_url = "https://foobar.gatech.edu/";

    Important Note:  The settings.php file is usually protected from editing, so you may have to modify its access permissions before you can modify it.  Try editing it from the File Manager in your hosting account's Plesk Control Panel, as this may make it easier to override those protections.

    Move or Symlink Your Site to /httpsdocs

    Read the Enable SSL for your OIT Hosting Account post to see what kind of hosting account you have.  If you have a new-style account with only a /httpdocs/ directory, then all you need to do is add the following to your .htaccess directly below the lines you added in the "Edit Your Site's .htaccess File" section above:

    RewriteCond %{HTTPS} !=on
    RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]

    If you have an old-style account with both /httpdocs/ and /httpsdocs/ directories, you'll need to do one of the following:

    1. If your Drupal site is not managed by Installatron, you can just move everything from /httpdocs/ to /httpsdocs/, then create a .htaccess file in your /httpdocs/ directory with the following in it:

      Redirect / <YOUR-SITE-DOMAIN-NAME-HERE>/ 301

    2. If your Drupal site is managed by Installatron, then you don't want to move it (unless you're comfortable with taking it out of Installatron first, then re-adding it to Installatron after the move.) In this case, you can take a different approach of symlinking /httpsdocs/ to /httpdocs/.

      1. Remove the /httpsdocs/ directory completely (you should be able to do this now under the current release of the Plesk Control Panel system.

      2. Create the symlink of /httpsdocs/ to /httpdocs/, either through the File Manager in the Control panel, or if using SSH:

        $ cd /
        $ ln -s httpdocs httpsdocs

      3. Add the following to your .htaccess directly below the lines you added in the "Edit Your Site's .htaccess File" section above:

        RewriteCond %{HTTPS} !=on
        RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]

    Restricting a Website to On-Campus Access Only

    Restricting a Website to On-Campus Access Only afrank30 Tue, 08/27/2013 - 10:49
    Drupal Version
    Tags

    You can restrict your site so that only people who are on-campus (or using the VPN) can access it. This is a great idea for internal-use-only sites and also for all of your development/test websites if you are not using a local stack.

    Using .htaccess Configuration

    Here's the code to put into the .htaccess file in the root directory of your site (on OIT Web Hosting, this goes under httpdocs or httpsdocs usually):

    RewriteEngine On
    RewriteCond %{REMOTE_ADDR} !^130.207.
    RewriteCond %{REMOTE_ADDR} !^128.61.
    RewriteCond %{REMOTE_ADDR} !^143.215.
    RewriteCond %{REMOTE_ADDR} !^192.93.8.
    RewriteRule ^.* http://site.gatech.edu/message.html [R=301,L]

    The first three lines cover the main Atlanta campus, while the fourth line (192.93.8.) covers GT Lorraine in France.

    The method above will direct all outside users to /message.html on your site, where you can post a message about the site being for on-campus use only.  An alternate method shown below will just give users a 403 Forbidden error, which might be good enough in many cases.

    Order deny,allow
    Deny from all
    ## All Atlanta Campus (3 lines total)
    Allow from 130.207.0.0/16
    Allow from 128.61.0.0/16
    ​Allow from 143.215.0.0/16

    Using a Firewall

    If your website is not on OIT Web Hosting, then you can also limit access through firewalls:

    Software Firewall

    This kind of firewall you have to set up and maintain yourself, so you need to have some basic networking knowledge to get it configured correctly.  On the other hand, you can reconfigure it yourself whenever necessary.  On UNIX style systems (Linux, Mac OS X, etc.), you can use either  ipfilters or ipfw.  On Windows servers, Microsoft provides its own firewalling tools - check your Windows server documentation for more information.

    Hardware Firewall

    This kind of configuration has to be done via the GT Networking Firewall web application by someone authorized to make changes to the subnet that your server lives on.  The upside to this option is that you don't have to know anything about networking, and you don't have to worry about your firewall breaking when you run upgrades on your server's operating system.  The downside is that if you don't have access to mange the firewall for your subnet then you'll have to send your requests for changes up to whomever manages your subnet.

    User Authentication and Authorization

    User Authentication and Authorization root Tue, 12/04/2012 - 13:48
    Drupal Version

    Authentication and authorization are often confused with each other.

    Authentication is the process of securely identifying a user based on credentials presented (username, password, security token, etc.)  For website user authentication, Georgia Tech predominantly uses Central Authentication Service (CAS), often times referred to as the GT Login Service.

    Authorization is the process of determining what roles and/or privileges an authenticated user has been granted.  For user authorization, there are options available through both CAS SAML attributes and through LDAP queries.


    Authentication and Authorization Guides and Resources

    CAS Single Sign-On

    CAS Single Sign-On esembrat3 Fri, 03/15/2013 - 14:39
    Drupal Version

    Central Authentication Service (CAS) based single sign-on is the main method of doing authentication via GT Account Usernames for Drupal website logins.  Once users have logged into the GT CAS system, the can access any Georgia Tech website that utilizes CAS without having to enter their GT Account Username again, as long as they don't completely close their browser or clear their browser's cookie cache.


    CAS Guides and Resources

    Installing CAS

    Installing CAS root Tue, 12/04/2012 - 13:50
    Drupal Version

    There are two components needed to add CAS support to a Drupal website: the phpCAS Library, and two supporting Drupal modules.

    phpCAS Library

    This library is only needed for Drupal 7.  If you are installing the CAS module for Drupal 8, you can skip this section.

    1. Download and install the current, stable version of the phpCAS Library.  As of early 2017, the current version was phpCAS 1.3.4 – if you are using and older version, you should consider upgrading as soon as possible to get the latest security patches.
    2. Install it under the sites/all/libraries/ directory of your Drupal site.  Rename the top level directory to CAS so that you have the CAS.php file inside of sites/all/libraries/CAS/

    Drupal Modules

    You will need to configure CAS to talk to the Georgia Tech CAS service.

    1. Log into the special original user account (user #1) that you setup when creating your Drupal site.  This is the main administrative account that has full power over everything in your site.  If this account is the same as someone's GT Account Username, you should rename the account to something else (good names are "root" or "admin", which make it easy to identify the account later on.
    2. For Drupal 7, download and install the Libraries and CAS modules into your Drupal site's sites/all/modules/ directory, or if your site supports it, install them via the Install Module option in the Modules section of your site's administrative controls.
    3. For Drupal 8, download and install the External Authentication and CAS modules into your Drupal site's sites/all/modules/ directory, or if your site supports it, install them via the Install Module option in the Modules section of your site's administrative controls.
    4. Go to the Modules page of your site's administrative controls and enable (turn on) both modules.  Once you have enabled these modules DO NOT LOG OUT OF THE SITE until you have finished the remaining steps.  Otherwise, you will find yourself locked out of your site!
    5. For Drupal 7 only, go to the Permissions page of your site's administrative controls (found under the People section), and make sure that the following permissions are enabled for the highest level user role in your site (commonly "administrator", or for sites using the GT Profile, "super administrator") (Don't forget to save your changes!) :
      • CAS -> Administer CAS
      • User -> Administer Permissions
      • User -> Administer Users
    6. Go to the CAS settings page of your site's administrative controls (found under the Configuration -> People section) and configure your CAS settings (see Drupal version specific links below for more details).
    7. Add a new user to the site with the username and "CAS username" both being the same as your GT Account Username.  Set the other fields as needed (enter a random value for the password field) and give the account the highest access level available (usually 'administrator').  Don't forget to save the new account.
    8. In a different web browser from the one in which you are currently using (or via your browser's private browsing feature), browse to your Drupal site and verify that you can login with your personal GT Account Username and password.  You should not see the normal Drupal login prompt - if you are prompted at all, you should be taken to the Georgia Tech Login service and then brought back to the Drupal site after you've successfully logged in to your GT Account.
    9. Repeat step #7 above for each user who should have access to the site, setting the access level as appropriate for the individual user.

    CAS Configuration Guides

    Configure CAS (Drupal 6)

    Configure CAS (Drupal 6) root Tue, 12/04/2012 - 13:55
    Drupal Version

    The following settings should be adequate for most Georgia Tech developers using Drupal version 6. 

    The CAS configuration page can be found at: http://yoursite/admin/user/cas

    CAS Server Settings

    • CAS version — 2.0 or higher
    • CAS server — login.gatech.edu
    • CAS port — 443
    • CAS URI — cas
    • Check to see if a user is already logged in? — The function of this setting is unclear. It doesn't seem to do anything, but we (Communications & Marketing) leave it unchecked.
    • CAS PEM certificate verification — Do not verify the certificate
    • CAS PEM Certificate (phpCAS 0.6 or greater) — leave blank
    • Initialize CAS as proxy — unchecked
    • CAS PGT storage file format — Plain Text
    • CAS PGT storage path — leave blank
    • Enable CAS Single Sign Out (CAS server 3.1 or greater) — unchecked
    • CAS debugging output filename — leave blank

    User Account Settings

    • Is Drupal also the CAS user repository — unchecked
    • If Drupal is not the user repository, should cas hijack users with the same name? — You will probably want this box checked. This will allow you to create people's Drupal accounts before they log in. If you leave it unchecked, you will need to make user the following box is checked and you will have to get people to log in before you configure their accounts.
    • Should Drupal user accounts be automatically created? — If you want any GT user to be able to log into your site, you will want this box checked. If you want to pre-approve selected users, you will want to uncheck this box and make sure the previous box is checked. Warning: if you leave both this box and the previous box unchecked, there will be no way for CAS to associate its users with Drupal accounts.
    • Email Domain — mail.gatech.edu
    • Users cannot change email address — Checked, unless you want users to be able to use non-GT addresses.
    • Users cannot change password — checked
    • Auto-assign users to the role(s) — This is entirely up to you. Be warned, however: if you are allowing accounts to be created automatically and you are automatically endowing them with godlike powers, well, you might as well leave your house keys hanging from your mailbox while you're at it.

    Redirection Settings

    • Require CAS login for — You may specify protected pages if you have some portion of your site that is to be password-protected. If you are merely using CAS to authenticate site administrators, you make leave these fields blank.
    • Force redirection on initial login — If you want all users directed to a particular page upon login, check this box and enter the path in the following field.
    • Successful login message — We recommend the default unless you have specific other needs.
    • Redirect user on logout — https://login.gatech.edu/cas/login

    Miscellaneous Settings

    • Change password URL — https://passport.gatech.edu/
    • Registration URL — leave blank

    Login Form Settings

    • Add CAS link to login forms — Make CAS login default on login forms
    • CAS login invitation — default
    • Drupal login invitation — default
    • Redirection notification message — default

    Configure CAS (Drupal 7)

    Configure CAS (Drupal 7) root Tue, 12/04/2012 - 13:57
    Drupal Version

    The following settings should be adequate for most Georgia Tech developers using Drupal version 7.

    The CAS configuration page can be found at: http://yoursite/admin/config/people/cas

    CAS Server

    • Version — 2.0 or higher
    • Hostname — login.gatech.edu
    • Port — 443
    • URI — /cas
    • Certificate Authority PEM Certificate — leave blank

    Login Form

    • Add CAS link to login forms — Make CAS login default on login forms
    • CAS login invitation — Log In
    • Drupal login invitation — default
    • Redirection notification message — You will be redirected to the secure GT login page.
    • Successful login message — Logged in via GT as %cas_username.

    User Accounts

    • Automatically create Drupal accounts — unchecked/checked
      (Whether a Drupal account is automatically created the first time a CAS user logs into the site. If disabled, you will need to pre-register Drupal accounts for authorized users.)
    • Email address: username@ — gatech.edu
    • Roles — authenticated user
    • Users cannot change email address — checked
    • Users cannot change password — checked

    Redirection

    • Check with the CAS server to see if the user is already logged in? — unchecked
    • Require CAS login for — specific pages
      (Enter one page per line as Drupal paths. The '*' character is a wildcard. Example paths are 'contact' for the site-wide contact form, 'user' for the sitewide login page, 'forms/*' for every form you create under this fake directory.)
    • Excluded pages — default

    Login/Logout Destinations

    • Initial login destination — https://yoursite.gatech.edu/
      (Drupal path or URL. Enter a destination if you want the user to be redirected to this page on their first CAS login. An example path is "<front>" for the front page, or "user" for the user's page.)
    • Logout destination — <none>
    • Change password URL — https://passport.gatech.edu/
    • Registration URL — blank

    Miscellaneous & Experimental

    • Initialize CAS as proxy — unchecked
    • CAS debugging output filename — leave blank

    Configure CAS (Drupal 8)

    Configure CAS (Drupal 8) root Mon, 07/10/2017 - 14:08
    Drupal Version

    The following settings should be adequate for most Georgia Tech developers using Drupal version 8.

    The CAS configuration page can be found at: http://yoursite/admin/config/people/cas

    CAS Server

    • Version — 2.0
    • Hostname — login.gatech.edu
    • Port — 443
    • URI — /cas
    • SSL Verification — Verify using your web server's default certificate authority (CA) chain.

    All other sections are optional, but you will want to either:

    • Enable Login link enabled under the GENERAL SETTINGS section (to show a CAS login link on the regular Drupal login form/page).  This could be combined with the GATEWAY feature to speed up login for users already logged into their GT Account.
    • Post a link to /caslogin to your front page
    • Configure the FORCED LOGIN section, should you want to have visiting a path like /user automatically to log the user into CAS

    NOTE: The Drupal 8 CAS module uses a different login path (/caslogin) from what CAS used in Drupal 6 and 7, which was /cas .  However, you can easily alias /cas to point to /caslogin if you wish to maintain the old URL as a valid login path.

    An explanation on GATEWAY: this feature will check to see if the user is already logged into his/her GT Account and if so log him/her into the website.  If the user is not already logged in, then the user will simply access the site as a guest (anonymous) user.  For this reason, you must also enable the login link setting or post a login link to your front page to allow users to log into the site when they are not already logged into their GT Account.  (All GATEWAY does is to save users the trouble of selecting a login link when they've already logged into their GT Account.)

    Important: If you turn on both GATEWAY logins and Auto register users, then every Georgia Tech user who visits your site and is already logged into their GT Account will have a Drupal account created for them on your site.  This can result in your site ending up with thousands of user accounts, which can be a headache when it comes to managing the accounts of users who actually have special editing privileges on your site.  In general, you really don't want to configure a site this way unless you specifically want to allow all Georgia Tech community members to be able to create content and/or post comments to existing content.  An example of this kind of usage is this Georgia Tech Drupal community site.

    The FORCED LOGIN feature will require every visitor to have a Drupal account on your site and will log the visitor into their account when first accessing the site in a browser session.  Visitors who do not have a Drupal account will be denied access to the site.  You probably do not want to enable this for the whole site (unless the site is meant to be a private intranet), but it can be useful to enable FORCED LOGIN for subsections of a site (e.g. "/admin/*" to automatically force login when trying to access any administrative page.)

    Redirecting Users to the Campus CAS Logout Page

    Redirecting Users to the Campus CAS Logout Page root Tue, 12/04/2012 - 13:59
    Drupal Version

    Drupal and CAS utilize different logout functions. Sending the user to /logout will log the user out of your site only and just return the user to the front/home page.

    Sending the user to /caslogout will log the user out of your site and redirect the user to the logout page for CAS.

    One way to send users to the CAS logout page without hunting down and changing every script that calls logout is to set up /logout as an alias for /caslogout.

    Setting up the Alias

    • While logged in as an administrator, go to Configuration -> Search and metadata -> URL aliases -> Add alias (/admin/config/search/path/add)
    • Enter caslogout in the Existing system path field
    • Enter logout in the Path alias field
    • Select the Save button.

    Requiring User Login for Specific Pages

    Requiring User Login for Specific Pages afrank30 Fri, 06/05/2015 - 12:26
    Drupal Version

    If you are using the CAS module for user authentication, you can require users to be logged in to their GT accounts before they can access specific pages on your Drupal site.

    Enabling Restrictive Access (Drupal 7)

    1. Visit the CAS configuration page on your Drupal 7 site, at Configuration -> People -> CAS settings
    2. Under REDIRECTION, locate Require CAS login for and check the setting for specific pages.
    3. In the textbox under Specific pages, type in one page path per line (with no starting slashes)
    4. Select Save configuration at the bottom of the page once completed.

    Enabling Restrictive Access (Drupal 8)

    1. Visit the CAS configuration page on your Drupal 8 site, at Configuration -> People -> CAS
    2. Under FORCED LOGIN, locate Pages and type in one page path per line (include starting slashes)
    3. You may need to select the Enabled checkbox - untested and unclear as to whether Enabled has to be on when only forcing logins on specific pages.
    4. Select Save configuration at the bottom of the page once completed.

    Commonly Protected Paths

    Commonly protected paths include:

    • 'contact' for the site-wide contact form
    • 'user' for the site-wide login page
    • 'forms/*' for every form you create under this fake directory

    CAS Logout Error

    CAS Logout Error esembrat3 Mon, 08/24/2015 - 13:54
    Drupal Version

    Courtesy of Doug Curtis in OIT:


    People are receiving a 500 error when using the "GT Logout" link on a Drupal page.  It looks like the problem is that the Drupal CAS module is appending the "service=" query string to the end of the CAS logout URL.  The GT CAS server will accept "url=" query string but it doesn't accept the "service=" query string.  Previously, the CAS service would quietly ignore appended query strings it didn't recognize but that isn't currently the case.

    The way to fix this is to leave the "Logout destination" field blank in the phpCAS module's settings.  The "Logout destination" is supposed to be used to specify a URL to redirect the user to after the user has been logged out.  It is NOT supposed to be the URL for logging out of CAS.  By leaving the field blank, the application will be logged out of CAS but the user will still be authenticated in CAS.


    Updating the CAS Library to the Latest Version

    Updating the CAS Library to the Latest Version afrank30 Thu, 10/16/2014 - 09:41
    Drupal Version

    While the phpCAS library is pretty stable, its maintainers do still release updates periodically, and every now and then one of those updates is to fix a security issue. Below are step-by-step instructions for how to update your phpCAS library to the most current, secure version.

    For this example, we will update from version 1.3.2 to version 1.3.3, but the same steps should apply to updating between any versions of the phpCAS library (which allows logins with GTaccounts to our drupal sites).

    1. Download the latest version of phpCAS from the phpCAS website.
    2. If you don't want to use ssh/command line, "extract" the files from this compressed archive on your computer (Windows users can use the free 7-zip program to do so), which will create a folder called CAS-1.3.3, that has another CAS-1.3.3 directory and a package.xml file inside it.
    3. Change the name the second CAS-1.3.3 folder (that is inside the other) to CAS.
    4. Zip up that re-named "CAS" folder...usually by right-clicking and choosing either Compress "CAS" (on a Mac OS X computer) or Send to -> Compressed (zipped) folder (on a Windows computer).
    5. Now that you have a friendly zipped file, named "CAS.zip", find where the CAS library lives on your server. The best practices location on a Drupal site is under the "sites/all/libraries" folder (which often requires you to add the Libraries module to your Drupal site, first).
    6. Then, turn on your TEST site's maintenance mode (because, of course, you are not trying this out on your live site). For Drupal 7, you can enable this at: admin/config/development/maintenance
    7. Delete the current version of phpCAS that lives at sites/all/libraries, so that there is no "CAS" folder anymore.
    8. Upload your new CAS.zip file to your Test site's libraries folder, so that it looks like this: sites/all/libraries/CAS.zip.
    9. Check the box next to CAS.zip in your web hosting panel and then, from the menu of options at the top of your file list, choose More -> Extract Files and then select Okay.
    10. Once you see your new "CAS" folder, you can then delete the "CAS.zip" file from this directory and your library has been updated.
    11. Remove your Test site from maintenance mode and make sure it works correctly.
    12. If all goes well, follow the same process on your Live site.

    Using CAS to Retrieve GTED User Attributes

    Using CAS to Retrieve GTED User Attributes robert Wed, 07/29/2015 - 14:00
    Drupal Version

    CAS is capable of delivering some GTED attributes for the person logging in to Drupal, as part of the login process.  This means you don't have to configure and maintain an LDAP module nor manage an LDAP service account (read: no need to keep up with an expiring service account password).

    While Georgia Tech's CAS service will provide authentication for any site within the ".gatech.edu" domain, by default it won't release any attributes.  You'll have to request what attributes your application needs by filling out the OIT IAM Data Steward Request Form (this is the same web form that you use to request a GTED LDAP service account.)  Make sure you specify CAS authentication and whatever data you need under Data Request.

    Once that has been approved and CAS has been set up, configure Drupal to talk to CAS just as it's documented here on previous pages, except for the CAS Server Version, which needs to be set to SAML Version 1.1.  If the user's email address is one of the attributes you're requesting from CAS, then you'll want to leave the email address field under User Accounts blank.

    Now, under the Attributes tab, select the CAS Attribute Tokens button (not the "LDAP Attribute Tokens" if you have that).  It should show you a list of attributes Drupal is getting from CAS.  You may have to log out and log back in.  If you don't see the list, you may have to work with whoever handled your data steward request, sometimes these things take a bit of tweaking to get right.

    Still on the Attributes tab, select the Settings button.  You'll want Drupal to Fetch CAS Attributes "everytime a CAS user logs in" because, well, people's data changes all the time.  You'll probably also want to always Overwrite existing values from attributes, to make sure Drupal doesn't store any old data.  Under CAS ATTRIBUTE MAPPINGS, specify "[cas:name]" for the Username field and "[cas:attribute:email_primary]" (assuming you requested that) as the E-mail address field.

    LDAP Directory Information

    LDAP Directory Information esembrat3 Fri, 03/15/2013 - 14:42
    Drupal Version
    Tags

    Lightweight Directory Access Protocol (LDAP) is an open protocol for sharing directory information and can be used as an alternative to CAS to allow users to log in to a web application using their GT Account Username and password.  Unless your application doesn't support CAS, it's best to use it instead of LDAP, since LDAP requires obtaining a special GTED LDAP user account for your application.

    If you just want basic directory information for users without the ability to do user authentication, there is a public GT LDAP server called 'Whitepages' that can be queried from any server or workstation on-campus.


    LDAP Guides and Resources

    Whitepages GT Directory Server

    Whitepages GT Directory Server esembrat3 Fri, 01/11/2013 - 12:58
    Drupal Version

    There is a public-facing LDAP server from which you can pull general directory information from without authentication.  This server is only accessible from servers and workstations located on one of the Georgia Tech campus subnets.

    Connection Settings

    Use the default settings, unless otherwise stated beow:

    • LDAP Server Type - Open LDAP
    • LDAP Server - ldap://whitepages.gatech.edu
    • LDAP Port - 389
    • Binding Method - Anonymous Bind
    • Base DNs for LDAP users, groups, and other entires this server configuration - dc=whitepages,dc=gatech,dc=edu
    • AuthName attribute - uid
    • Email attribute - mail

    Testing Queries

    To test queries, see the OIT article on LDAP.

    Specific Clients

    • Mac Mail: LDAP Server: whitepages.gatech.edu (adding "ldap://" into the field causes the lookup to fail for me. --Sterling)

    LDAP and CAS Integration

    LDAP and CAS Integration esembrat3 Fri, 03/15/2013 - 14:42
    Drupal Version
    Tags

    Integration between LDAP and CAS allows you to grab user data fields and attributes available from the campus LDAP servers while still authenticating users via CAS. 

    Editor's Note:  As the CAS Attributes module is not participating in the Drupal security advisory policy, and the code is still in beta and hasn't been updated since 2013, we can't recommend using this technique, but we are providing the instructions below as a reference.  At this time, there is no usable version of CAS Attributes for Drupal 8, so this method is only usable currently for Drupal 7 sites.

    Drupal 7 Instructions

    1. Make sure the LDAP, CAS, and CAS Attributes modules are installed.
    2. Configure LDAP and CAS according to this handbook's instructions. Be sure to use the public-facing LDAP server for easiest setup.
    3. Go to the CAS Attributes settings page at Configuration -> People -> CAS -> Attributes (admin/config/people/cas/attributes)
    4. Open LDAP tokens in a second tab.
    5. Copy and paste the appropriate Tokens back to the profile fields on the CAS Attributes main settings page. 
    6. You may also want to use the Real Name module to replace displays of the user's username with a combination of other Profile fields.

    Use GTED to Automatically Add Users to Roles or Organic Groups

    Use GTED to Automatically Add Users to Roles or Organic Groups ma195 Wed, 04/16/2014 - 15:02
    Drupal Version
    Tags

    On campus we have GTED, the Georgia Tech Enterprise Directory, an LDAP server that stores lots of information about people.  Some is public, but a lot of it is private. With a departmental account, you can get a lot of information and feed it into Drupal to automatically set up groups of users.

    Requirements

    • Drupal 7
    • A departmental GTED account
    • Installing the following modules (in dependency order).   Note: All of the "LDAP *" modules are part of the LDAP module package.
      • CTools (ctools)
      • Entity API (entity)
      • Number - Drupal Core Module
      • LDAP Servers (ldap_servers)
      • LDAP User Module (ldap_user)
      • LDAP Query (ldap_query)
      • LDAP Authorization (ldap_authorization)
      • LDAP Authorization - Drupal Roles (ldap_authorization_drupal_role)
    • Organic Groups - optional, but we will include setup instructions; adding Organic Groups requires the following modules:
      • List - Drupal Core Module
      • Text - Drupal Core Module
      • Entity API (entity)
      • Entity reference (entityreference) - required for Organic Groups https://drupal.org/project/Entityreference
      • Organic groups UI - Sub-module of Organic Groups
      • Organic groups access control - Sub-module of Organic Groups
      • LDAP Authorization - OG (organic Groups) (ldap_authorization_og)

    Setup

    Create your Roles

    Go to /admin/people/permissions/roles or People -> Permissions -> Roles and create the roles you are going to populate. For this demo, we will create three: Employees, Faculty and Staff.

    Create your Organic Groups (Optional)

    Organic Groups requires a content type and a bit of setup. We will assume that this has been done already. For this demo, we will create three: OGEmployees, OGFaculty and OGStaff.

    Set Up LDAP

    Head to /admin/config/people/ldap or Configuration -> People -> LDAP Configuration

    Settings

    You can leave everything the same here, though you may want to check "Enabled Detailed Watchdog Logging" for testing.

    Servers

    Select the Add LDAP Server Configuration button.

    Connection Settings

    • Machine name and name can be whatever you want.
    • Check Enabled
    • Server Type is default
    • LDAP server is ldaps://r.gted.gatech.edu The ldaps:// in front is important!
    • LDAP Port is 636. This is the secure LDAP port.

    Binding Method

    • Binding Method for Searches should be Service Account Bind
    • DN for non-anonymous search is: uid=XXXXXX,ou=Local Accounts,dc=gted,dc=gatech,dc=edu with XXXXXX replaced by your departmental GTED login account

    LDAP User to Drupal User Relationship

    • The Base DNs for LDAP users, groups, and other entries will be ou=accounts,ou=gtaccounts,ou=departments,dc=gted,dc=gatech,dc=edu
    • AuthName attribute is uid. In GTED, your uid is your gt account.
    • Not including for now - Email Attribute is gtprimaryemailaddress

    LDAP Group Configuration

    This is where things get funky.

    The quick version:

    • Check A user LDAP attribute such as memberOf exists that contains a list of their groups.
    • Enter edupersonscopedaffiliation for Attribute in User Entry Containing Groups

    Save!

    Testing

    You should now have a GTED server set up. If it is not enabled, do that now.

    Now let's ake sure you can connect and read a record. Click test. Under "Testing Drupal Username" enter a GT account that is an active user in Drupal (preferrably your own) and click the "Test"

    You may see a bunch of error messages, but you should also see a lot of info about yourself.

    More Details

    LDAP supports groups, but GTED doesn't use them. What we do use is a field in the eduPerson schema named eduPersonScopedAffiliation. This can have multiple entries. Here's mine as an example:

    • member@gtaccounts
    • employee@gt
    • member@gt
    • credit-alum@gt
    • former-credit-student@gt
    • employee@psdept 490:arch-admin:college of arch adm & schools
    • member@psdept 490:arch-admin:college of arch adm & schools
    • employee@coa
    • member@coa
    • faculty@gt
    • faculty@coa
    • faculty@psdept 490:arch-admin:college of arch adm & schools

    Any of these can be used to sort people into a group. There are a lot more. Here's some examples from a grad student who is part of the HCI program, so they are a member of the College of Computing, College of Architecture, and Psychology departments.

    • credit-student@gt
    • student@gt
    • graduate-student@gt
    • masters-student@gt
    • student-employee@coa
    • student-employee@gt
    • member@coa
    • student@coc
    • member@coc
    • student@psych
    • student@coa
    • member@psych

    There's plenty of things that we can do with all this. My goal was to set up automatic grouping for our Intranet, so we could have things only visible to faculty, or staff, or students.

    User

    Leave this alone for now. We could use LDAP to behave like CAS and handle authentication and have users auto-created when verified by LDAP.  CAS works fine, so let's not mess with it.

    Authorization - Roles

    Add a Drupal Role Configuration.

    Make sure the GTED server is selected

    Check "Enable this Configuration"

    Uncheck "Only apply the following LDAP to drupal role configuration to users authenticated via LDAP." The basic GT Drupal install is using CAS for authentication.

    Enter your LDAP to Drupal in the "Mapping of LDAP to drupal role" box. The basic form for GTED will be the edupersonscopedaffiliation value, then the drupal group.

    So for our three Roles, the entries should be:

    employee@gt|Employees
    faculty@gt|Faculty
    staff@gt|Staff

    Click Add

    Back on the Authorization screen. First, make sure your config is enabled. Frequently it won't be if it was just created. If you need to, just edit and Enable it. Click test on the entry you just created.

    Enter your own GT Account, and a few others then test. If everything works, you should see entries in the "Authorization IDs" column for anyone who was filtered into a group.

    Authorization - Organic Groups

    This is very similar to the way that Roles are configured, except that the mappings correspond to the Organic Group name and role. For this demo we use:

    employee@gt|node:OGEmployees:2
    faculty@gt|node:OGFaculty:2
    staff@gt|node:OGStaff:2

    Note: As of 4/16/2014 there is a bug in LDAP Authorization of Organic Groups. If a user has the "Administer Organic groups permissions" which GT Super Administrators do, then they will not be added to the Organic Groups on login. It seems to work fine for users without OG Admin rights.  https://drupal.org/node/2064319

    Two-Factor Authentication

    Two-Factor Authentication esembrat3 Mon, 12/15/2014 - 08:07
    Drupal Version

    All Georgia Tech users who have been enabled for two factor authentication (2FA) are required to log into CAS with their two-factor token via the Duo 2FA service.  As of summer 2017, this includes virtually all campus employees, and will soon include all students.

    So, long story short, there is no reason to add your own two-factor authentication to your Drupal websites - you would, in effect, just be creating three-factor authentication, which would likely create more headaches than benefits.

    More information on the campus program can be found on the OIT Two-Factor Authentication website.

    Finding a Person's GT Account Username

    Finding a Person's GT Account Username afrank30 Wed, 08/05/2015 - 09:39
    Drupal Version

    The GT Account Username is the standard computer account for everyone at Georgia Tech.  It is used to access a variety of systems including TechWorks, BuzzPort, and Mercury, and can be used to access your Drupal site by installing the CAS module.   

    You may often find that need to add someone to a group in Mercury or to your Drupal site, and you need to know the person's GT Account Username.  Here are several ways that you can look up that information:

    Using Office 365

    [Instructions courtesy of Noel Moreno]

    • Go to the "People" area (click on the "waffle" in the upper left, then select "People").  
    • In the left column, check the radio button for "Directory".  
    • Enter the person's name, email address, partial name, etc. in the search box.  
    • Results are returned on the right.  Select the person of interest.  
    • In the data returned, the GT Account Username will in the person's "IM" value.  It will be "sip:[gt account]@gatech.edu".

    Using Zimbra Email

    • Compose a new fake email.
    • Click on the "To" button.
    • Search for the person. When you have found the person, DO NOT click on or select their name.  Instead, hover over their name in this directory, and their GT Account Username will be one of the fields shown.

    Using Command Line tools

    Note: Any command line tools to query data via the Georgia Tech "White Pages" (which both the Georgia Tech Directory Tools and the 'ldapsearch' examples use) will only work from on-campus or over the campus VPN.

    Creating a Georgia Tech Guest User Account

    Creating a Georgia Tech Guest User Account esembrat3 Wed, 01/09/2013 - 10:16
    Drupal Version

    If you have enabled CAS authentication to help keep your site secure, but have a limited number of non-GT users who need access to certain protected features of your Drupal site, you can create guest GT Account Usernames for them.

    Creating a New Guest User Account

    1. Log into PASSPORT (https://passport.gatech.edu)
    2. Under Sponsored Guests, choose Manage guests.
    3. Select the Create a new guest button and follow the instructions to create your guest user.
      • Only grant LAWN wireless or T-Square access if necessary.
      • Only grant permissions for the length of time the guest will need access (1-365 days).
    4. Write down the Guest's new GT Account Username and Password, so you can communicate it to them over the phone or in person (since it's not very safe to send passwords electronically).

    Solving Post-Migration Login Issues

    Solving Post-Migration Login Issues afrank30 Mon, 03/02/2015 - 10:32
    Drupal Version

    If you are unable to log in with CAS after migrating a site, make sure you copied the .htaccess file in the root of your site (httpdocs on OIT Web Hosting). 

    Please note that this file may be hidden to some file browsers. If so, configure your file browser to show hidden files.

    Technical Details

    CAS requires that Clean URLs be enabled. When Clean URLs is enabled, Drupal edits the .htaccess file to properly handle normal-looking URLs. 

    When a Drupal website is migrated without the .htaccess file, Drupal reverts to the ugly URL schema (i.e. http://drupal.gatech.edu?q=user/login). This has the side-effect of also disallowing CAS from working properly.

    CAS PEM certificate location

    CAS PEM certificate location
    Category
    esembrat3 Thu, 08/30/2018 - 09:48
    Drupal Version

    To use the CAS PEM certificate installed on websites hosted on OIT webhosting, please use the following path:

     /etc/pki/tls/certs/ca-bundle.crt

    Applying fix to resolve CAS redirect loop

    1. Login to Plesk via https://hosting.gatech.edu
    2. Click “Databases” in the side menu
    3. Click “phpMyAdmin” to edit your database
    4. Go to the “variable” table
    5. Look for a variable named “cas_cert”
    6. Click the “BLOB” link next to the variable name in the value column to download the “variable-value.bin” file
    7. When you open the file in Notepad++ (or your text editor of choice), you’ll see a line similar to this:                                               s:33:" /etc/pki/tls/certs/ca-bundle.crt";
    8. Delete the PEM path (DO NOT DELETE THE QUOTES!) and save the file
    9. Click the “Edit” link next to the “cas_cert” variable
    10. In the “value” row item, click the “Browse” button to upload the edited file
    11. You can now login to your website (if you still see the CAS authentication error message, click the “reload” button on your browser)

    Optimization and Performance

    Optimization and Performance esembrat3 Mon, 12/17/2012 - 11:51
    Drupal Version

    This section documents ways that you can optimize your Drupal site for better performance.


    Guides and Resources

    Drupal Core Optimization

    Drupal Core Optimization esembrat3 Wed, 01/09/2013 - 10:48
    Drupal Version

    A number of performance settings are recommended to cache Drupal data objects and speed up your site.

    Enable Caching and Aggragation Settings

    These settings can be enabled in Drupal 7 via the administrative control panel under Configuration -> Development -> Performance

    • Cache pages for anonymous users
    • Cache blocks
    • Compress cached pages
    • Aggregate and compress CSS files
    • Aggregate JavaScript files
    • Set Minimum cache lifetime = 15 minutes

    Disable and Remove Unnecessary Modules

    Several key internal functions in Drupal will scan all installed modules, so be sure to not only disable but also uninstall and remove any third-party (contrib) modules that you are not using.  This not only improves your site's speed but also helps to keep it better secured.

    Core modules should not be removed, since they'll just reappear the next time you do a core upgrade.  However, consider turning the following off to help speed up your site:

    • Statistics - You can offload this computation to Google Analytics
    • Syslog - We recommend using dblog instead.
    • Tracker - This can generate a lot of data, so turn it off unless you have a real need for knowing what individual users are doing.
    • Overlay - A potentially useful module, but can generate noticeable frontend lag.

    Additional Optimization Techniques

    Performance Modules

    Performance Modules esembrat3 Wed, 01/09/2013 - 10:51
    Drupal Version
    Tags

    There are also quite a few modules that attempt to cache resource-heavy actions on Drupal.

    Getting Started with Performance Module

    For most websites, core Drupal caching should be sufficient to keep CPU/memory usage down and keep your website running smoothly. However, for larger and more complex websites, additional caching and optimization will be needed.

    For your specific website (and its use cases, structure, and workflows), please browse through the modules below and see which module(s) may work for your website. 

    For questions, please contact the Georgia Tech Drupal mailing list and someone will be glad to help!

    Advanced CSS/JS Aggregation

    Availability: Drupal 7, Drupal 8

    From the module's Drupal.org page:  AdvAgg allows you to improve the frontend performance of your site. The performance benefits are achieved by using some of the features found in AdvAgg and its sub modules. Out of the box AdvAgg's frontend performance will be similar to cores.

    Boost

    Availability: Drupal 7

    Boost provides static page caching for Drupal enabling a very significant performance and scalability boost for sites that receive mostly anonymous traffic.  For shared hosting this is your best option in terms of improving performance.

    • Boost is not recommended for large websites (nodes >= 1000), as the caching process will take up the websites' allotment of CPU cycles. This will slow down the website to be unusable for end-users.
    • Boost can be used alongside Memcache API and Integration
    • No configuration for Boost is necessary beyond installing and enabling the module. 
    • Core caching in Drupal must be disabled for Boost to work properly

    CDN

    Availability: Drupal 7, Drupal 8

    CDN provides easy Content Delivery Network integration for Drupal sites. It alters file URLs, so that files are downloaded from a CDN instead of your web server.

    Before you begin, you will need to select a CDN provider. CDN have different costs and features depending on your needs. 

    • These CDNs are currently used on campus:
      • Keycdn.com - Used by the Office of International Education (Jimmy Kriigel)
        • http://oie.gatech.edu
        • http://pacific.gatech.edu
        • http://oxford.gatech.edu
    • This module is best used for websites with lots of traffic and lots of images and/or locally hosted videos.
    • KeyCDN has made a CDN Drupal Integration Tutorial available.
    • The CDN module has TEST Mode.  If you don't want to use the CDN to serve files to your visitors yet, but you do want to see if it's working well for your site, then enable testing mode.  Users will only get the files from the CDN if they have the permission to "Access files on CDN when in testing mode".
    • The "Far Future expiration" option doesn't work with the IMCE module.
      • Update: IMCE has a patch in their dev branch for this issue.
    • You can manually flush a CDN cache file by having the Display statistics Shows enabled and scrolling down to the bottom of the page and selecting "Touch" to purge the file.

    Entity Cache

    Availability: Drupal 7

    From the module's Drupal.org page:  Entity cache puts core entities into Drupal's cache API.  Due to the entity loading changes in Drupal 7, no core patches are required.

    Don't bother using this module if you're not also going to use Memcache API and Integration or Redis – the purpose of Entity Cache is to allow queries to be offloaded from the database onto alternative storage, and there are minimal, if any, gains from using it with the default database cache.

    Memcache API and Integration

    Availability: Drupal 7

    This module provides integration between Drupal and Memcached with the following features:

    • An API for using Memcached and the PECL Memcache or Memcached libraries with Drupal.
    • Memcache backends for the following systems (all drop-in):
      • Caching (memcache.inc)
      • Locking (memcache-lock.inc)
      • Sessions (memcache-session.inc) (D6 only)
    • A module that provides a comprehensive administrative overview of Drupal's interaction with Memcached and stats.
    • A set of tests that can be run to test your memcache setup.

    Memcache is ideal when there are lots of database reads and writes, as it is a cache for the data layer (this is also why it can so easily whitescreen your site when things go wrong). This article does a decent job of explaining the "whens" and "whys" of APC, Varnish and Memcached.

    Recommended Settings

    After enabling the memcache module, add this text to the bottom of your settings.php:

    $conf['cache_backends'][] = 'sites/all/modules/memcache/memcache.inc';
    $conf['lock_inc'] = 'sites/all/modules/memcache/memcache-lock.inc';
    $conf['memcache_stampede_protection'] = TRUE;
    $conf['cache_default_class'] = 'MemCacheDrupal';
    $conf['cache_class_cache_form'] = 'DrupalDatabaseCache';
    $conf['page_cache_without_database'] = TRUE;
    $conf['page_cache_invoke_hooks'] = FALSE;
    $conf['memcache_servers'] = array('localhost:11211' => 'default');

    You will need to adjust the module directories if your module is installed in a different directory.

    Troubleshooting

    In some cases, Drupal will white-screen after settings.php is edited to reflect the new memcache settings. If this occurs, please check your error log on Web Hosting.  If you see a 'Fatal Error', follow the directions below (taken from this Drupal.org thread):

    1. Backup your website.
    2. Download registry_rebuild and upload to sites/all/modules.
    3. Run registry_rebuild by navigating your browser to: [yourdomain]/sites/all/modules/registry_rebuild/registry_rebuild.php
    4. If no errors show up, your registry has been rebuilt.
    5. Delete the module from the sites/all/modules directory.

    Varnish HTTP Accelerator

    Availability: Drupal 7

    Varnish HTTP Accelerator provides integration between your Drupal site and the Varnish Cache, an advanced and very fast reverse-proxy system.  Basically, Varnish handles serving static files and anonymous page-views for your site much faster and at higher volumes than Apache, in the neighborhood of 3000 requests per second.

    Other Ways of Increasing Performance

    Other Ways of Increasing Performance esembrat3 Wed, 01/09/2013 - 10:52
    Drupal Version
    Tags

    Besides performance modules, there are several other methods for increasing the performance of your Drupal site.

    Disable Modules Only Needed During Development

    Only enable these modules while actively developing, and then turn them off the rest of the time.

    Track Your Site's Performance Baselines

    Locate and Fix PHP Errors/Warnings

    • Turn on verbose error reporting to find errors and warnings (check Apache error logs as well)
    • Perform performance testing of any custom coding.

    Optimize Javascript and Other Front-End Features

    Automating Drupal Cron on OIT Web Hosting

    Automating Drupal Cron on OIT Web Hosting esembrat3 Wed, 01/09/2013 - 10:49
    Drupal Version

    Unless you manually configure Drupal cron to be run by your web hosting server, it will be automatically run when someone visits a page on your Drupal site after a certain amount of time has passed.  This method works perfectly fine, but can slow down the display of the page the user requested since the cron run will block page generation until it has finished.  This becomes more noticeable on site visited less frequently as more tasks can accumulate that need to be executed during a cron run.

    To keep this from happening, you can schedule Drupal cron to run automatically in the background.  On a web server that you fully control, you can use UNIX style cron to run the Drupal cron job.  You can also do this on OIT Web Hosting, but you have to configure the job via the Plesk Control Panel.

    Step by Step Instructions

    1. Log into your hosting account's Plesk control panel.
    2. On the main control panel page, navigate to Schedule Tasks, found in the right-hand sidebar menu.
    3. On the Scheduled Tasks page, select the Add button
    4. Fill out the form as follows (the example here will set up Drupal cron to run every eight hours):
      • Minute: 0
      • Hour: 0,8,16
      • Day of the Month / Month / Day of the Week: * (insert an asterisk)
      • In the text field, Command, enter the following:
        curl --silent --compressed http://YOURDRUPALSITE.gatech.edu/cron.php?KEY-FROM-ADMIN-REPORTS-STATUS-PAGE
        You can find the link to put at the end of this command (KEY-FROM-ADMIN-REPORTS-STATUS-PAGE) on your Drupal site's status report page at Reports -> Status report (admin/reports/status)

    Video Tutorial

     
     

    Logs and Logging Tools

    Logs and Logging Tools root Wed, 07/12/2017 - 14:27
    Drupal Version
    Tags

    Logging details about your site's usage can be very valuable, but if not configured properly, can also be a huge resource drain.  The following articles provide useful best practices for managing your Drupal site's logging functions.


    Logs and Logging Guides and Resources

    Errors, Warnings, and Log Settings

    Errors, Warnings, and Log Settings afrank30 Mon, 06/15/2015 - 09:42
    Drupal Version
    Tags

    Fix Errors Whenever Possible

    Although hiding error messages is important from a security perspective, errors and warnings mean that something isn't working correctly, and that could likely have a negative effect on your site.  It's best to try to fix them to fix them if you can (especially if they are in your own code), or for third-party contrib modules, report them to the module or project owner.

    PHP Message Types

    PHP, which Drupal runs under, can generate three types of messages:

    • Notices - Something to be aware of that you might want to do differently, but probably won't keep your site from working.
    • Warnings - More serious issues than Notices, but are not keeping your site from running.
    • Errors - A serious issue that has caused the site code to stop running before reaching a normal completion.

    In short, errors are problems that have to be fixed, because they are impeding use of your site.  Warnings and notices ought to be fixed, but notices may be things that you have a reason for doing in an unusual way.

    Drupal 7+ Message Settings

    To change the way your Drupal 7 or 8 site shows PHP messages, go to the  Configuration -> Development -> Logging and errors (admin/config/development/logging) administrative control page.

    The recommended settings for a live, production site are:

    • Error messages to display: None. 
    • Database log messages to keep: 100 (unless you need a longer audit trail)
    • Note: Do not enable the core syslog module if you are using OIT hosting.  According to the syslog module's documentation, it is not appropriate for shared hosting.  You should be able to find most useful debugging information by looking at the error logs, as described below.

    Error Logs on OIT Web Hosting

    If using OIT Web Hosting, you will find a record (or log) of errors the server is tracking in your Plesk control panel.

    From the main panel, go into the Logs section and look for the log file called "error_log". You can either view or download this file, which lists detailed error log messages.

    Other forms of web hosting will have their own logging areas where you can look for error logs.  Check with your server administrator to find out where the logs are on any non-OIT server that you might be using.

    One thing to keep in mind is that server error logs will only contain messages from PHP.  Any messages generated by Drupal itself will be found in the Drupal Error log, found in the administrative area of your site under Reports -> Recent log messages.

    Sample Error Messages on Web Hosting

    Here are some examples of error messages you might find in your hosting log:

    [Mon Jun 15 03:01:53 2014] [warn] RSA server certificate CommonName (CN) `hosting.gatech.edu' does NOT match server name!? 
    [Mon Jun 15 08:52:25 2014] [error] [client 130.207.000.00] File does not exist: /var/www/vhosts/mysite.gatech.edu/httpdocs/favicon.ico, referer: http://mysite.gatech.edu/node/77 
    [Mon Jun 15 09:03:20 2014] [warn] [client 130.207.000.00] mod_fcgid: stderr: PHP Warning:  chdir(): open_basedir restriction in effect. File() is not within the allowed path(s): (/var/www/vhosts/mysite.gatech.edu/:/tmp/:/usr/share/pear:/var/cache/hg:/opt/atomic/atomic-php55/root/usr/share/pear) in /var/www/vhosts/mysite.gatech.edu/httpdocs/custom-file.php on line 88

    Database Logging Configuration

    Database Logging Configuration afrank30 Mon, 04/07/2014 - 08:10
    Drupal Version
    Tags

    If using the "Database logging" module in core, be sure to keep only a small number of entries (1,000 seems reasonable).

    Until we have a solution that can feed syslog information from Drupal into regular system logs on OIT Web Hosting, we use the "Database logging" module in core to track errors, logins, and other system messages. This module stores its logs in the watchdog table.

    It is important to set this module to only keep a small number of log entries (such as 1,000), so that our database servers don't get overwhelmed.  You can change the settings for your Drupal 7 site at: Configuration -> Development -> Logging (admin/config/development/logging).

    Making Sure Access Logs Are Tamed

    Making Sure Access Logs Are Tamed
    Category
    kp37 Mon, 01/25/2016 - 19:17
    Drupal Version
    Tags

    It looks like there's a bug in Drupal 7 where, if you ever turn on and activate the Statistics module (enabling the logging of accesses to the database), and then decide to turn off the Statistics module, Drupal keeps on logging to the table that it creates (accesslog), and cron never clears anything out of that table, so it can just keep growing indefinitely.  On a busy site, this can result in multiple millions of entries in that table.

    Here's what you can do to check for this condition:

    1. If you know how to use something like phpMyAdmin to examine your database, look for an accesslog table (it may have a prefix on it, depending on how your copy of Drupal was set up).  If it exists, then your site has Statistics turned on, or did at some point in the past.  If the number of rows is huge, then you probably need to do the next step.
    2. If you know you need to fix this problem, or if you don't know how to use phpMyAdmin, you can do the following:
      1. Go into your Drupal site and turn on the Statistics core module.  
      2. Next, go to Administration -> Configuration -> System -> Statistics and look at the settings there.  Disable Enable access log, set Discard access logs older than to '1 hour', and then save the configuration.  
      3. Finally, go to Administration -> Reports -> Status report, and initiate a manual cron run to clear the accesslog table.  Note that this may fail to complete if you have over a million entries in the table.  If so, then you'll need to use phpMyAdmin or something similar to clear out the table.
      4. Once you've gotten past step 2.3, go back to your Modules page and disable Statistics.

    Of course, if you actually want to use the Statistics module, then make sure that Discard access logs older than is set to something other than 'never', so that the accesslog table doesn't grow indefinitely.

    Automation and Version Control

    Automation and Version Control esembrat3 Mon, 12/17/2012 - 11:51
    Drupal Version

    This section is for tips and tricks to help automate your Drupal site maintenance tasks, specifically using the Drush command line interface.  Also covered is the use of version control systems like GitHub.

    GitHub at Georgia Tech

    GitHub at Georgia Tech
    Category
    esembrat3 Mon, 02/24/2014 - 13:10
    Drupal Version
    Tags

    Georgia Tech staff, students, and faculty can now use a Georgia Tech instance of GitHub, a version/revision control system.  This service is available thanks to the College of Engineering's brilliant proof of concept with GitHub Enterprise, and the ensuing excited buy-in from the Office of Information Technology.

    What is GitHub and Why Should I Use Revision Control?

    GitHub is a proprietary hosted extension of the open-source Git version/revision control system commonly used for open-source software projects.  It is very useful for multi-developer projects, as it allows coordinating and tracking code changes and the orderly acceptance and integration of those changes into the master project.  Version control also makes it much easier to revert back to an earlier version of the software if it is discovered that accepted changes have caused unexpected problems.

    Or, to put it short, it'll save your bacon.  Figuratively, not literally.

    Support Policy

    OIT does not offer technical support or training for Git or GitHub usage.  If you want to learn how to use git, see below for many educational resources.

    Accessing Georgia Tech GitHub Enterprise

    Just go to https://github.gatech.edu and log in with your GT Account Username and password.

    GitHub User Software

    You can access repositories in GitHub using git from the command line of most Unix based operating systems (see GitHub's KB), but you can also use a variety of GUI (graphical user interface) applications, such as:

    Drupal List

    We have a Drupal community group in GitHub that allows users to share and collaborate on projects. Please add collaborative projects to the GT Drupal group on GitHub at Georgia Tech.

    Learn to Use git with GitHub Resources

    You can learn how to use git (and GitHub) with these tools from GitHub Enterprise, such as:

    • Guides: Tutorials, tips, and workflows to help you and your team learn about GitHub.
    • Classes: Monthly free, online classes about GitHub, Git, and the union of these two technologies (and free events following these online classes that allow you to get answers directly from GitHub Experts.)

    Learn to Use git with General Internet Resources

    The internet has lots of other great places to teach you about git. Here are a few:


    Local GitHub Guides and Resources

    Forking a GitHub Repository and Using Pull Requests

    Forking a GitHub Repository and Using Pull Requests
    Category
    cfort6 Wed, 04/27/2016 - 16:15
    Drupal Version
    Tags

    Forking creates a copy of a repository which you can work on. You can then submit a pull request to have your changes reviewed and integrated with the master repo. This is the order of operations:

    FORK > SYNC > BRANCH > COMMIT > PUSH > PULL REQUEST

    Download a PDF version of this guide.

    Forking a Repository

    Reference: https://help.github.com/articles/fork-a-repo/

    In Github, navigate to the repository to be forked and select “Fork” on the upper right. Select your own user name when prompted. This creates a copy of the repository for you on Github.

    Now you should see your fork. Copy the URL using this button:

    Open Terminal and type:

    git clone https://github.gatech.edu/ORG_NAME/Repo-Name

    Here (after clone) you should paste the URL you copied at the beginning of this step. This creates a local copy of your clone on your machine under your current directory.

    Connect your Fork to the Master

    Next, sync your fork with the master to ensure that any changes going on with the master will be reflected in your local fork/clone.

    Navigate in Github to the original repository. Copy the URL as shown:

    • Open Terminal and change directories to the fork you cloned.

      cd (enter)
      ls (look for your cloned fork/repository name)
      cd Fork_Name
      git remote -v

      git remote add upstream https://github.gatech.edu/ORG_NAME/Repo-Name

    • Alternately, you can both add and fetch (sync with) your master by using this instead:

      git remote add -f upstream https://github.gatech.edu/ORG_NAME/Repo-Name

    • Verify your upstream repository is syncing.

      git remote -v

    Syncing Your Fork

    Reference: https://help.github.com/articles/syncing-a-fork/

    You probably want your fork to mirror the latest changes being made to the main repository. If you used “git remote add -f upstream” in the previous step, this is already done. If you used “git remote add upstream” and now you need to fetch upstream to sync your fork, you can use this method.

    • In Terminal, change to the directory of your local clone and fetch upstream to sync with the original master repository.

      cd Fork_Name
      git fetch upstream
    • Check out your fork’s local master branch.

      git checkout master
      git merge upstream/master

    Branch Your Fork

    Now Branch your issue locally.

    In Terminal:

    git checkout -b name_of_your_new_branch

    Committing Changes to Your Fork

    • Change your files as needed.

    • In Terminal,

      git status

      This will confirm that git is watching your modifications.

    • Add the files to staging (substitute your file name or names)

      git add path/file_name

    • Then commit

      git commit -m “First commit”

    You will get feedback saying how many files were changed and how.

    Note for newbies: A branch may contain many commits. Name your branch to reflect what you’re working on and name commits to reflect more specific changes.

    Pushing Your Changes to GitHub

    In Terminal,

    git push origin name_of_your_new_branch

    Now you should see your branch show up in Github.

    Making a Pull Request

    Reference: https://help.github.com/articles/using-pull-requests/

    • Select your branch in Github. Select “New pull request”

      You can enter details about the changes you are suggesting. You can also select a branch to send the request to, if it’s not the master branch.

    • When you’re ready, select “Create pull request” at the bottom.

      After you send a pull request, any commit that’s pushed to your branch will be automatically added to your pull request, which is useful if you’re making additional changes.

    Drush (Drupal Shell)

    Drush (Drupal Shell) esembrat3 Mon, 12/17/2012 - 13:05
    Drupal Version
    Tags

    Drush (Drupal Shell) is a great Drupal "module" to accomplish many administrative tasks via the command-line. It is not a module in the normal sense, because it's not enabled/disabled from the Drupal admin. Instead, it actually lives anywhere on your local system and is run like any other local executable. Here are some of its key features from the Drush Drupal.org page:


    A few core drush features:

    • The Drush Package Manager allows you to download, enable, disable, uninstall, update modules/themes/profiles/translations from the command line in a very simple way (apt-get style) - just type e.g. drush dl views and drush enable views in a Drupal directory to install the Views project!
    • Additionally, the Drush Package Manager also allows you to update all your modules with just one command - drush update.
    • Drush Core: several useful utilities for site administrators and developers (e.g. drush cron or drush cache clear)
    • Drupal SQL Commands help you issue queries to any of your databases (i.e. is multi-site aware) and even helps you migrate databases between your environments.
    • Drush simpletest commands make it easy to run unit tests from the command line and email results to your dev team.
    • Drush now supports aliases which let's you perform actions on separate Drupal installations.  This is very useful for multi-site configurations.

    Drush Guides and Resources

    Updating Modules via Drush

    Updating Modules via Drush esembrat3 Mon, 12/17/2012 - 13:06
    Drupal Version

    If you have to perform module updates on your Drupal site, then Drush is the way to go. Drush will help you to update all modules on your site(s) quickly and painlessly.

    Prerequisites

    • SSH/shell access
    • Somewhat higher than basic Unix/Linux command-line experience

    Process

    Drush has many commands and options. These commands need to be run from the directory where the settings.php file for your site is, i.e.

    /path/to/drupal/sites/default

    /path/to/drupal/sites/gpburdell.gatech.edu

    For the purpose of updating your modules you will basically use it like below:

    drush update

    This is interactive and will give you a listing of all the modules that need to be updated for a given site. You can then choose to update them all or continue.  Unless you are certain you want to do all of your updates at once, I suggest you use this command to see what updates are needed, then use the below command to update a few of the modules separately at one time. For short you can also use use "drush up".

    drush update modulename0 modulename1

    This let's you specify a list of modules you want to update.

    drush updatedb

    This command will perform any updates to the database schema for your modules.  This is run automatically after every Drush update. For short you can also use "drush updb".

    If you have multi-sites then after you do a Drush update you may have to move to your other multi-site folder to do a drush updatedb to update any changes to the database schema.

    Best Practices

    • Limit the number of modules you use on your Drupal sites as much as possible.
    • Try to keep modules that are shared by more than one multi-site in the sites/all/modules folder.
    • Always check the release notes for any new modules to see if installing them will require any other changes or dependencies.

    Gotchas

    • Drush expects a backup directory to be present in the root of your Drupal installation like /path/to/drupal/backup where it backs up the previous version of the module to.  Make sure you have write access to this directory.
    • If you had any modified files in the previous module directory you will need to copy those back to the correct place after the module is updated.  Luckily everything will be in the backup directory.
    • Depending on permissions you may need to run Drush as the super user.  Ask your system administrator for sudo access if needed.

    Using Drush on OIT Web Hosting

    Using Drush on OIT Web Hosting aa17 Mon, 03/18/2013 - 17:00
    Drupal Version

    If you are hosting a Drupal website on OIT Web Hosting, you can SSH into your host, but you cannot run the command-line tool Drush from your SSH session because OIT doesn't allow PHP to be run directly from the SSH command line of Web Hosting accounts.  However, this doesn't mean that you cannot use Drush at all with OIT Web Hosting – you just have to work around this limitation.

    Disclaimer

    THESE INSTRUCTIONS ARE COMPLETELY, 100%, NO, EVEN 1000%, NOT SUPPORTED IN ANY OFFICIAL WAY BY OIT WEB HOSTING.  No warranty expressed or implied.  Always back up your site and database(s) before trying these instructions.  These instructions, though tested on several sites, may break your site, cause data loss, or even make your dog not like you any more.  Be careful!

    Process

    Essentially, you will run Drush locally on your computer, but have it operate on an OIT Web Hosting site.  To do this, you will need to:

    1. Establish an SSH tunnel for the database connection, and
    2. Mount your site's files over ssh via SSHFS.

    Note: The instructions presented below are for using Drush on a Mac. If you want to try this from a Windows computer, both SSH (<) and SSHFS (WebDrive) clients are available for Windows.

    Prerequisites

    • Drush, installed locally – Installation instructions are available at the Drush Docs site.  If you have the Acquia Dev Deskstop installed, you already have Drush.  You can also install it via homebrew.

    • An SSH client – Suggested products are:

      • On a macOS / Mac OS X system: Terminal or iTerm
      • On a Windows system: SecureCRT
    • An SSHFS client to let you mount a remote filesystem over SSH – Suggested products are:

    • Access to your site via SSH – You must know the password for your site's (unfortunately named) FTP Login account, which you can set/reset via your web hosting administration panel in the Web Hosting Settings screen.  (Note as of the 2015/16 Plesk upgrades, you can now set up and use an SSH key instead of needing the SSH/FTP password.)

    • Be on campus or have access to the campus VPN Service, as OIT Web Hosting does not allow SSH directly from off-campus.

    Steps to Drush Bliss

    In the instructions below, foo.gatech.edu is a placeholder for your site's actual hostname, and foo is a placeholder for your site's SSH/FTP account. Replace these with your site's hostname and SSH/FTP account where appropriate.  Also, these instructions assume you are using Transmit as your SSHFS client.  Configuration screens for WebDrive will be similar.

    1. Install Drupal, if you haven't already... via source, Installatron, etc.
    2. Edit your httpdocs/sites/default/settings.php file, changing the databases array's host and port entries to read:
       'host' => php_sapi_name() == 'cli' ? '127.0.0.1' : 'mysql.localhost',
       'port' => php_sapi_name() == 'cli' ? '3307' : '3306',
    3. Create a file named dbip.php in your sites httpdocs directory: 
      <?php 
      if (array_key_exists('REMOTE_ADDR', $_SERVER) 
         && ((substr($_SERVER['REMOTE_ADDR'], 0,7) == '128.61.') 
         || (substr($_SERVER['REMOTE_ADDR'], 0,8) == '130.207.') 
         || (substr($_SERVER['REMOTE_ADDR'], 0,8) == '143.215.') 
         || (substr($_SERVER['REMOTE_ADDR'], 0,9) == '192.93.8'))) 
         { 
          echo gethostbyname('mysql.localhost'); 
         } 
      ?>
      
    4. On your local machine, in a terminal window, open up an SSH tunnel through your Web Hosting server to your Web Hosting account's database host:
      ssh -N foo@foo.gatech.edu -L 3307/`curl -s http://foo.gatech.edu/dbip.php`/3306
    5. Use an SSHFS client to mount your site's httpdocs directory. For Transmit, use the SFTP connection and choose Mount as Disk:


       
    6. In a terminal, navigate to the mount point ( /Volumes/foo.gatech.edu/ ) and run drush status to test your configuration. You should see the message "Database : Connected and Drupal bootstrap: Successful."
    7. When you are finished using Drush on your site, remember to close (control-C) the SSH command doing the tunneling and unmount your site's filesystem (drag it to the Trash).

    MySQL Databases for Developers

    MySQL Databases for Developers
    Category
    afrank30 Wed, 11/26/2014 - 09:23
    Drupal Version
    Tags

    This section contains selected resources and guides for dealing with the MySQL databases that are integral to every Drupal website.


    MySQL Resources and Guides

    Creating a MySQL Database

    Creating a MySQL Database
    Category
    afrank30 Wed, 11/26/2014 - 09:21
    Drupal Version

    Creating a new MySQL database for a site hosted on OIT Web Hosting can be a little confusing.  Below are the steps for getting a database set up and configured properly via the Web Hosting Plesk control panel, as well as generic steps for creating a new database on any MySQL instance that has phpMyAdmin installed.

    MySQL Database Creation on OIT Web Hosting

    1. Visit http://hosting.gatech.edu/ and select the website you want to work with from the list of sites that you manage.
    2. Select the Databases management link.
    3. On the Databases management page, select the Add New Database link.
    4. Fill in the fields on the Add New Database form, and be sure to copy down everything for future reference.  Use the password generate to generate a secure password (select the 'Show' button to see the generated value so that you can copy it down.)
    5. Select the OK button to create your new database.
    6. Back on the Databases management page, you should see a listing in the table for your new database.  The Webadmin link on that row will let you access your database via phpMyAdmin.

    Video Tutorial (1:13)

    MySQL Database Creation on a Standard Apache HTTPD Server Via phpMyAdmin

    1. Log into phpMyAdmin on your server with the master (root) user account for your mySQL instance.
    2. Select the Databases tab.
    3. In the box under Create database, enter the name for your new database and select the Create button.
    4. Select the Users tab and create a new user with a unique name and password.  Be sure to write down the name of the database you create, as well as the username and password you make for it. (As always, try to choose a fairly-secure database username and password and do NOT use your GTaccount - jdoe3).
    5. Once the account is created, grant it access to the database that you created.  You'll probably want to give the account all privileges for the database except "grant", as you usually don't want the account to be able to give out access to other accounts.

    Video Tutorial (0:39)

     

    MySQL Database Connection Tools

    MySQL Database Connection Tools
    Category
    afrank30 Wed, 09/04/2013 - 09:54
    Drupal Version

    You can view any MySQL database on an OIT Web Hosting website using many different GUI based applications. Below are a few implementations that have been used by members of our community:

    General Instructions

    OIT has an FAQ entry explaining how to connect to your hosting database, which also discusses using phpMyAdmin to view your database(s) from your hosting control panel (which doesn't require any additional software).

    Rochester University has a nice tutorial on using phpMyAdmin with MySQL.

    Elsewhere in this handbook is a  more in-depth post on SSH tunneling.

    The general information you'll need, if you choose to connect with a more graphical software application, is:

    • the domain name of the site your database uses (example: mydepartment.gatech.edu)
    • the SSH or FTP Login account name and password for this site
    • the host your database lives on: for OIT Web Hosting, use "mysql.localhost" instead of plain "localhost".
    • the database account's username and password (this will be different from the SSH/FTP login account and password)
    • the port for your database: 3306

    MySQL Workbench

    Andrew Dugenskei (a member of the GT Drupal community) has a preference for MySQL Workbench.

    Fortunately, MySQL Workbench (available for Mac OSX and Windows) makes it very easy to communicate with OIT web hosted databases and it is free. If you're on campus, no other software is needed. If you're off campus, you just need to first make sure you are connected to the VPN.

    Below is a screen capture from the Workbench connection manager with some pseudo values. Once the correct values are entered, connecting to an OIT databases is a just a click away.

     

    From the above screen capture and based on the Workbench Tutorial, you can use these settings.

    Under the Connection Tab, Choose "Standard TCP/IP over SSH" and then enter these parameters for your site:

    • SSH Hostname: mydepartment.gatech.edu (port name ":22" at end is optional)
    • SSH Username: myFTPaccount (for your SSH or "Local FTP" account on Web Hosting)
    • SSH Password: myFTPpassword (for your SSH or "Local FTP" account on Web Hosting)
    • MySQL Hostname: mysql.localhost (for web hosting, just use this instead of worrying about which server you're on)
    • MySQL Server Port (leave same): 3306
    • Username: database_user (for this database only)
    • Password: database_password (for this database only)
    • Default Schema: leave blank

    Navicat (Mac, Windows, Linux)

    Mike Alberghini (a member of the GT Drupal community) has a preference for Navicat because the software:

    • Has a good GUI
    • Handles multiple databases well,
    • Has Mac OS X support
    • Is 40% off for educational users
    • Saves connection info for ssh tunnels and start them as needed to connect to servers

    Screenshots of a successful Web hosting database connection with Navicat are below. 

    For Navicat, use the following settings on the "General" tab:

    • Connection Name = My Department Site
    • Hostname/IP Address = mysql.localhost (this is important for you to connect to Web Hosting)
    • Port (leave same) = 3306
    • User name = This is the username for your DATABASE's user.
    • Password = This is the password for your DATABASE's user.

    To finish your connection with Navicat, use the following settings on the "SSH" tab:

    • Use SSH tunnel = check YES
    • Hostname/IP Address = mydepartment.gatech.edu
    • Port (leave same) = 22
    • Username = This is the username of the web hosting FTP account for this site.
    • password = This is the password for the web hosting FTP account for this site.

    Sequel Pro (Mac)

    Adam Arrowood (a member of the GT Drupal community) has a preference for Sequel Pro because the product:

    • Has a nice GUI, ssh tunneling, etc. as found in other similar products.
    • Runs (only) on Mac OS X.
    • Is a free product.

    Code Snippets

    Code Snippets bwaye3 Fri, 03/14/2014 - 20:53
    Drupal Version

    This section is for sharing sample code that does useful things for site administrators and developers.  Please do not add anything directly to this page, but rather create a sub page for each individual snippet.

    Adding Multiple Jump Links to GT Super Blocks

    Adding Multiple Jump Links to GT Super Blocks
    Category
    esembrat3 Tue, 07/26/2016 - 08:06
    Drupal Version

    To allow more than one jump link on each Superblock, a quick hack is needed.

    Please note:  This is not guaranteed to work with future versions of Super Block, so proceed at your own risk.

    Prerequisites

    Log in to GT Github and download the templates/node--super-block.tpl.php file from the gt_ae project.

    Adding Multiple Jump Links

    1. On your website, edit the content type Super Block.
    2. Select Manage Fields.
    3. Select Edit, to the right of Jump Link (field_nbsb_jump_link).
    4. Under Number of Values, increase the value from 1 to your desired number (supports up to unlimited).
    5. Add the templates/node--super-block.tpl.php file to your subtheme's templates/ folder.
    6. Clear caches.
    7. Test to see if it works.

    Embedding Live Streaming Video from OIT

    Embedding Live Streaming Video from OIT afrank30 Tue, 12/15/2015 - 08:56
    Drupal Version
    Tags

    Editor's Note:  The following instructions may be out-of-date now, but are left here for future educational reference.

    Below is sample code for embedding a live stream from OIT's Wowza server onto your Georgia Tech Drupal site, and includes sample code to embed live captions, which are required for accessibility compliance.  For more information, visit the test live stream site.

    Overview

    The safest way to include this code on a page on a Drupal site is to not use an unfiltered text format, but instead to use a block template file within your subtheme. Below is sample embed code for a live stream video and live captioning of an event.

    The following words will need replaced with real values in the below code. Contact the IT person controlling the streaming to find out what those values should be.

    • [[EXAMPLE-STREAMING-SERVER]]
    • [[EXAMPLE-PLAYER-SERVER]]
    • [[PORT-NUMBER]] (Usually 1935)
    • [[STREAM-NAME]]
    • [[CAPTION-ID]] (The test value is IHaveADream)

    Streaming Sample Code

            <!-- START Live streaming video code: JWPlayer 7 and OIT Wowsa server -->
            <h3 id="live-video">Live Video</h3>

            <script type="text/javascript" src="http://[[EXAMPLE-PLAYER-SERVER]].gatech.edu/sites/all/libraries/jwplayer/jwplayer.js"></script>
            <style>
                /* This is just to overwrite styling on the theme that resizes the object to be so small. It should be inserted directly before the standard embed code. If you have more than one video embed on a page, you'd need to add this for each one, incrementing the '0' after player_swf_ accordingly.
                */
                <!-- #player_swf_0 { height: 100% !important; } -->
            </style>

            <p id="alternate-video">
            <ul>
                <li><a href="https://support.jwplayer.com/customer/portal/articles/1597259-keyboard-shortcuts">Keyboard controls ('c' toggles captions)</a></li>
                <li>If having difficulties with the video, try the <a href="https://www.google.com/chrome/browser" title="Download Chrome">Chrome web browser</a>.</li>
                <li>To access captions on Android, download the <a href="https://www.videolan.org/vlc">VLC Player app</a>, open <a href="http://[[EXAMPLE-STREAMING-SERVER]].gatech.edu:[[PORT-NUMBER]]/live/[[STREAM-NAME]]/playlist.m3u8?DVR">this stream link</a>, and then choose "Closed captions 1" as the Subtitle track.</li>
            </ul>
        </p>

        <div id="player">

            <script type="text/javascript">
                var player = jwplayer("player");
                player.setup({
                    file: "http://[[EXAMPLE-STREAMING-SERVER]].gatech.edu:[[PORT-NUMBER]]/live/[[STREAM-NAME]]/playlist.m3u8",
                    image: "http://[[EXAMPLE-PLAYER-SERVER]].gatech.edu/assets/small_bling_desktop_2560x1440.jpg",
                    hlshtml: true,
                    width: "100%",
                    aspectratio: "16:9",
                    autostart: true,
                    stretching: "uniform",
                });

                player.on("captionsList", function () {
                    player.setCurrentCaptions(1);
                });
            </script>

        </div>
        <!-- END Live streaming video code -->

    Deprecated Captioning Sample Code

    Please note that the code below is no longer recommended - please use the code above instead.

    The code is available in cases of live captioning an event on a budget. As an example, you could display your stenographer's live captions during a presentation, using only a web browser and a large-screened monitor.

    At the bottom of a template file, you would include embed code for live captioning:

    <!-- START Live caption code: Feed from your Caption Company based on instructions at https://streamtext.zendesk.com/entries/21705252-embedding-streaming-text-with-streamtext-into-your-web-pages -->

    <h3>Live Captions</h3>
        <div class="live-caption">
        <iframe id="stFrame" title="Live Caption iframe" src="http://www.streamtext.net/text.aspx?event=[[CAPTION-ID]]&chat=false&header=false&indicator=false&footer=false&fs=30&spacing=1.75&bgc=262626&fgc=ffe08b&ff=Roboto,Verdana,serif" style="width:100%;min-height:400px">
        </iframe>
       </div>

    <!-- END Live caption code -->

    Read more about easy control options for this captioning embed at the Streamtext site.

    Listing Enabled Modules Using a bash Script

    Listing Enabled Modules Using a bash Script
    Category
    afrank30 Tue, 09/30/2014 - 11:14
    Drupal Version
    Tags

    A shell script that prints out a list of enabled modules in all accessible databases, designed for ssh use when you need to check multiple Drupal 6 or 7 databases at one time.

    Editor's Note:  A similar concept would work just as well for Drupal 8, but the database table names and structures have changed in Drupal 8, so you would need to adjust the script accordingly.  Also, be aware that this script will not work on any Drupal instance where you have used a custom table prefix for all of your Drupal site tables.

    With thanks to Abdul Manaf on DBA.stackexchange for the basic code.


    # mysql credential
    user="root"
    pass="pwd"
    
    all_dbs="$(mysql -u $user -p$pass -Bse 'show databases')"        
    
    # Exclude databases you don't want to check, such as non-Drupal 6 or 7 dbs.
    # Then output database name and an alphabetized list of Enabled modules.
    for db in $all_dbs
         do
            if [[ "$db" != "information_schema" &&
                "$db" != "mysql" &&
                "$db" != "performance_schema" &&
                "$db" != "test" ]] ; then
                echo '====================='
                echo "DATABASE: $db (ENABLED Modules)"
                echo "---------------------------"
                mysql -u$user -p$pass $db -sN -e "SELECT name FROM system WHERE status = 1 AND type = 'module' ORDER BY name ASC;" 
            fi 
         done
    

    Listing Enabled Modules Using phpMyAdmin

    Listing Enabled Modules Using phpMyAdmin
    Category
    afrank30 Tue, 09/30/2014 - 11:40
    Drupal Version
    Tags

    Below is SQL code that prints out SQL statements that you can copy and paste back into phpMyAdmin (or any MySQL management tool that can connect to your Drupal database).  These statements will help you get a list of enabled modules, when you need to check multiple Drupal 6 or 7 databases at one time.

    With thanks to Aaron Brown on DBA.stackexchange for the basic code.

    Be careful to copy the backquotes/backticks (that look a little like left-leaning apostrophes) exactly.


    SELECT CONCAT('SELECT \`name\` FROM ', schema_name, '.\`system\` WHERE \`status\` =\'1\' AND \`type\` =\'module\' ORDER BY \`name\` ASC;')
    FROM information_schema.schemata
    WHERE schema_name NOT IN ('information_schema','mysql','performance_schema','test', 'excluded_database');
    

    This will print out a series of SQL statements, like the one below, which you could paste into the SQL tab of phpmyAdmin, in order to create lists of enabled modules.  This can be helpful if you don't have ssh access to your site, but still want an easy way to get a simple text list of enabled modules.

    SELECT `name` FROM ms6_sample1.`system` WHERE `status` ='1' AND `type` ='module' ORDER BY `name` ASC; SELECT `name` FROM ms7_sample2.`system` WHERE `status` ='1' AND `type` ='module' ORDER BY `name` ASC;

    Troubleshooting Questions and Answers

    Troubleshooting Questions and Answers klp Thu, 04/21/2016 - 17:21
    Drupal Version

    This section is for general developer and administrator questions that commonly come up and their answers - particularly questions that don't really fit under any of the other existing topics.  Please list one question per sub-page and follow the format of the first question about Drupal Sites on OIT Web Hosting Unable to Send Emails.

    If you need some generic advice about how to deal with a Drupal site that has stopped working (e.g. the dreaded "white screen of death"), Kevin Pittman has written a fairly comprehensive guide called "So, You Blew Up Your Drupal 8 Site - Now What?".  It's written for Drupal 8, but all of the concepts apply to earlier versions – the specific details will just be a little different.


    Questions and Answers

    Drupal Sites on OIT Web Hosting Unable to Send Email

    Drupal Sites on OIT Web Hosting Unable to Send Email esembrat3 Wed, 04/22/2015 - 15:11
    Drupal Version

    Issue

    Email from a Drupal website on OIT Web Hosting is being delivered to non-Georgia Tech email addresses, but is failing on Georgia Tech email addresses (@gatech.edu).

    Solution

    Per OIT Web Hosting:

    Since this problem has come up more frequently, I’ll clarify what the issue is:

    outbound.gatech.edu requires that if you are sending to *@*.gatech.edu address that the OIT MX servers handle (which is most of them), the “From:” address has to be a valid Georgia Tech address. Along with this, if the “From:” address isn’t valid, there is no way for outbound.gatech.edu to send a bounce message back.

    This is a requirement of the OIT MX servers and isn’t related to anything that Web Hosting restricts.  In fact, on the Web Hosting servers, the message shows as sent, but that just means it was sent on to outbound.gatech.edu.

    To fix this issue, ensure that the From: email address in Drupal (set in Configuration -> Site Information) is a valid Georgia Tech email address.

    Changing Your Site's Host Name / Domain Name

    Changing Your Site's Host Name / Domain Name klp Tue, 05/17/2016 - 15:28
    Drupal Version

    Issue

    Below is a quick summary of what you need to do if you are changing your Drupal site's host name / domain name without moving it to a new web hosting location.

    If you are moving the site to another location, then you'll also need to see the Site Migration section for additional guides.

    Solution

    1. First, go ahead and request that your new host name be created in DNS and pointed to your existing web server.  You'll need to know the host name and/or IP address of your existing server to provide to your DNS administrator.  If you don't know either, then provide the current host name for your website, and your DNS administrator should be able to determine the web server hostname and IP address from it.
    2. Configure your web server to recognize the new host name.  If you are using an automated web hosting solution like OIT's Web Hosting, then go into your control panel and add the new host name as a domain alias for your hosting account.
    3. Check your site for links hard coded to your old host name:
      • The quickest way of doing this (though it does require some advanced knowledge) is to dump your database out to an SQL file and do a search through that file for instances of your old host name and then identify the pages that need to be updated.  
      • Alternatively, you could go through every page, opening each one up for editing, and check the page source for every inline link and every inline image.  
      If you don't fix these links, then users will be silently switched over to the old hostname when they follow those hard coded links, and when you eventually delete the old hostname from DNS, those links will simply break.
    4. If you want to force everyone to view your site through the new host name (which is important for Search Engine Optimization), you can add something like the following to your .htaccess file, where oldsitename.gatech.edu and newsitename.gatech.edu are replaced with the appropriate values:

        RewriteCond %{HTTP_HOST} ^oldsitename.gatech.edu [NC]
        RewriteRule ^ http%{ENV:protossl}://newsitename.gatech.edu%{REQUEST_URI} [L,R=301]
      

    Formatting breaks on Slideshow Carousel, SuperBlocks or other Content Types after 2.9 Theme upgrade

    Formatting breaks on Slideshow Carousel, SuperBlocks or other Content Types after 2.9 Theme upgrade
    Category
    afrank30 Mon, 04/02/2018 - 09:40
    Drupal Version

    Issue

    After updating to the 2.9 version of the GT Theme, the formatting is broken for custom content types (such as Super Blocks and Slideshow Carousels), usually those created via the Features module. Often the types show CSS classes as text instead of as visual styling.

    Example of broken Super Blocks

    super blocks showing css classes as text instead of styling

    Solution

    Find the theme_registry_alter function in your features .module file. Replace the line that line the defines the template file location with the fuller code from Using template (.tpl.php) files in your own module.

    Old theme_registry code

    $theme_registry['template-file']['path'] = drupal_get_path('module', 'gt_ct_carousel_slider') . "/templates/";

    New theme_registry code

    // Defined path to the current module.
      $module_path = drupal_get_path('module', 'gt_ct_carousel_slider');
      // Find all .tpl.php files in this module's folder recursively.
      $template_file_objects = drupal_find_theme_templates($theme_registry, '.tpl.php', $module_path);
      // Iterate through all found template file objects.
      foreach ($template_file_objects as $key => $template_file_object) {
        // If the template has not already been overridden by a theme.
        if (!isset($theme_registry[$key]['theme path']) || !preg_match('#/themes/#', $theme_registry[$key]['theme path'])) {
          // Alter the theme path and template elements.
          $theme_registry[$key]['theme path'] = $module_path;
          $theme_registry[$key] = array_merge($theme_registry[$key], $template_file_object);
          $theme_registry[$key]['type'] = 'module';
        }
      }

    Missing Module Issues with Drupal 7.50+

    Missing Module Issues with Drupal 7.50+ afrank30 Fri, 07/15/2016 - 14:31
    Drupal Version

    Issue

    After upgrading to Drupal 7.50 (or later), you start seeing red error messages that read "The following module is missing from the file system...".

    Drupal 7.50 began scanning more carefully for module and theme files, including files for modules and themes that had been disabled, but not uninstalled.  Unfortunately, many Drupal site administrators have disabled and deleted modules in the past without running the uninstall process, and once the module has been deleted, you no longer have a way to uninstall it.

    Solution

    • If the module listed is "mymodule", then the issue is most likely with the GT Tools module (specifically, the GT Content Types sub-module of GT Tools).  Upgrade your site to the latest version of GT Tools, and that should fix the problem.

    • For other modules and themes, the easiest solution is to download a copy of the module or theme in question, install it back into your website's filesystem, then go to Modules -> Uninstall on the administration menu bar and uninstall that module.  You can then delete the module or theme from your filesystem.

    • If you cannot obtain the a copy of the module again (e.g. it was a locally written custom module, and all copies have been deleted), you can suppress the error messages by updating your database (WARNING: Back up your database before attempting this proceedure!)

      Via whichever MySQL tool you prefer to use (e.g. phpMyAdmin), run the following SQL commands against your Drupal database (replace 'XXXX' with the relative path from the Drupal site root directory to the module or theme in question -- e.g., "sites/all/modules/ctools"):

      DELETE FROM `system` WHERE filename like 'XXXXXX';
    • If the missing object is a Drupal profile (e.g. "gt_profile" or "gt_install"), then fixing the problem is a little trickier.  Please see the article on fixing a missing profile in Drupal 7.

    Missing Profile Issues

    Missing Profile Issues root Tue, 07/11/2017 - 14:04
    Drupal Version

    Issue

    You are seeing a red error message in Drupal stating that a Drupal profile is missing from the file system.  Common examples are "gt_profile" and "gt_install", but the issue could happen with any profile.

    Much like with the more common missing theme or module file issue, it is possible that a previous Drupal site administrator deleted the directory for the Drupal profile used to install your Drupal site from the filesystem.  S/he may have thought that the profile was not needed after site installation, but Drupal does actually expect it to be there, and will throw error messages on some of the administration pages if those files are missing.  More often than not, the issues is just that someone simply forget to copy a custom profile directory over when applying a Drupal core update.

    Compounding the issue is that Drupal behaves a bit poorly when it can't find the assigned custom profile directory, and partially disables the profile in the database.  This prevents you from correcting the problem by just replacing the missing files (which is the simple solution for missing modules and themes).

    Solution

    If you have a copy of the missing profile, copy the files back into the right place in the filesystem, then try running the following against your Drupal database from your preferred MySQL administration tool (e.g. phpMyAdmin), replacing 'XXXX' with the path under the 'profiles' directory to your custom profile:

    UPDATE `system` SET status=1 WHERE filename like 'profiles/XXXX';

    If you do not have a copy of the missing profile, you can reset the site to the default profile:

    UPDATE `system` SET status=1 WHERE filename like 'profiles/standard/standard.profile';
    REPLACE `variable` SET `value`='s:8:"standard";' WHERE `name`='install_profile';
    

    If you still see error messages about your old custom profile, try running the following SQL command, replacing 'XXXX' with the path under the 'profiles' directory to your custom profile:

    DELETE FROM `system` WHERE filename like 'profiles/XXXX';

    Upgrading Drupal 7 to 8

    Upgrading Drupal 7 to 8 kp37 Tue, 11/28/2017 - 18:56
    Drupal Version

    Migration, not Upgrading

    Drupal 8, released in November of 2015, is a major rewrite of the Drupal core engine and APIs. Because Drupal 8 has changed so much, there is no direct in-place upgrade path to go from any earlier version of Drupal to Drupal 8. Instead, Drupal 7 and earlier sites must be migrated to Drupal 8, which involves setting up a whole new Drupal 8 website and copying into it (manually or automatically) the content of the older website.

    Requirements and Web Hosting Support

    Drupal 8 requires a hosting environment running at least PHP 5.6 and preferably PHP 7.0 or later, and support for both PHP versions is available on OIT Web Hosting. You can check your hosting account's Plesk Control Panel to see what PHP version your account is currently configured to use (the version number shows on the main control panel page, directly below the "PHP Settings" option).

    If you want to have your hosting account upgraded to PHP 7 when you launch your Drupal 8 website, just open a support request with OIT and they'll take care of that for you.

    Georgia Tech Migration Roadmap

    Beyond PHP support, each Georgia Tech unit website will need several extra components to be fully usable. The following table is an attempt to start tracking the status of the components needed for Georgia Tech Drupal 8 sites, and it will be updated as releases and additional information come available.

    Status of common Drupal 7 components in Drupal 8
    (Last Updated November 28, 2017)
    Component Name Available
    for
    Drupal 8?
    Comments?
    Georgia Tech Web Theme In Beta

    A community built version of the GT 3 beta theme is available.

    An official version is expected in mid to late February 2018.

    GT Account Authentication Yes

    CAS module v1.0RC2 is fully usable and CAS configuration instructions are available.

    Mercury News and Events No

    A port of the official Hg Mercury module is tentatively planned for late spring 2018.

    An alternative community built approach using the Migrate API is being investigated, but no details are available yet.

    GT Content Types No Vertical, Horizontal, and Multipurpose page types are not expected to be ported to Drupal 8. Such pages will have to be rebuilt in Drupal 8. Alternative page layout systems include:

    A future release of Drupal 8 (8.5 or 8.6) is expected to have its own layout system that will be similar to Panelizer.

    GT Drupal Express (DX) No

    A Drupal 8 installation for GT Drupal Express (DX) has not been announced or planned.

    Current DX websites should remain on Drupal 7 and consider manual content migrations to Drupal 8 in the future, as it is unlikely that a script will be developed to aid DX migrations to Drupal 8.

    A Drupal Express migration strategy guide is under development.

    Web Forms Partially

    The traditional Webform module is being completely rewritten for Drupal 8. The new version is still in release candidate state.  It is much more capable than the old version, but also more complex, and will require some notable retraining for existing users.

    Drupal 8 itself comes with a limited Contact Form functionality and a handful of contrib modules (such as Contact Storage) are available to extend that functionality, though not to the level found in the traditional WebForm module. Contact forms are recommended for simple RSVP and feedback forms.

    Complete Migration Process

    Kevin Pittman has posted a guide to migrating from Drupal 7 to Drupal 8 that includes a lot of planning tips and technical details.

    Drupal Express (DX) to Drupal 8 Upgrade/Migration Strategies

    Drupal Express (DX) to Drupal 8 Upgrade/Migration Strategies kp37 Thu, 11/30/2017 - 10:56
    Drupal Version

    Many Georgia Tech websites have been built using Drupal Express (DX), which is a custom version of Drupal 7 that allows you to create a website with little technical or design expertise. The ready-made site comes with built in features and tools like news and events listings, and mobile optimization.

    For several years, the Office of Information Technology has offered Drupal Express as an option when requesting a new web hosting account, providing the unit with this special version of Drupal pre-installed in the account so that the unit can start using the site almost immediately without having to do any technical work on the back end of the site.

    Unfortunately, the people who helped to create Drupal Express no longer work in Georgia Tech's Institute Communications Office, so there has been no planning at this time for any kind of automated upgrade or migration path for Drupal Express sites. Even if anyone were to work on such a path, the high level of customization in Drupal Express's page layouts and other tools coupled with the major changes in Drupal 8's underlying architecture would make an automated upgrade of a Drupal Express site very difficult.

    Below are some guidelines and tips for planning a manual site migration from Drupal Express to Drupal 8:

    • Drupal Express sites may still benefit from using the Drupal Migrate tool to at least bring over their Basic Page content. Bear in mind that some amount of clean-up will be necessary after using Migrate, but the clean-up may be easier than cutting and pasting a lot of Basic pages into your new site.

      Kevin Pittman has posted a detailed Drupal 8 Migration guide that describes how to use the Migrate tool.

    • Vertical, Horizontal, and Multipurpose page types are not expected to be ported to Drupal 8 and will not be copied over by the Drupal Migrate tool. Such pages will have to be completely rebuilt in Drupal 8. Alternative page layout systems include:
      • Paragraphs
      • Panels and Panelizer
      • A future release of Drupal 8 (8.5 or 8.6) is expected to have its own layout system that will be similar to Panelizer.

    • Other components included in Drupal Express may not be available for Drupal 8 or may have been superseded by new components. A breakdown of known Drupal Express components and their status is posted below.

    In case you are enlisting the help of someone with technical developer skills who would like to know more about the make-up of Drupal Express and what to expect when migrating a Drupal Express site to Drupal 8, below is the full list of components included in Drupal Express (excluding minor ones no longer needed in Drupal 8) and their known Drupal 8 status.

    Please note that just because a module has a production version, this does not mean that it works the same as it did in Drupal 7 or that it supports all of the features in the Drupal 7 version.  Please read the documentation for each module to see what has changed.

    Custom Drupal Express components and their Drupal 8 status
    (Last Updated March 22, 2018)
    Component Name Available
    for
    Drupal 8?
    Comments?
    Georgia Tech Web Theme In Beta

    A community built version of the GT 3 beta theme implementation is available.

    An official version is expected in mid to late February 2018.

    GT Superblocks No No port planned or expected of this custom module
    GT Editor No No port planned or expected of this custom module, but the built-in CKEditor provides much of the same functionality and can be customized as needed
    GT Login No No port planned or expected of this custom module, but the CAS module can be installed to provide GT Account Username based authentication.  CAS configuration instructions are available.
    GT Tools No Was only needed for the Drupal 7 Georgia Tech version 2 Web Theme
    HG Reader Planned An official port of this module is tentatively planned for late spring 2018
    JWFilter Superseded JWFilter was for the old OIT DMI media repository.  Please use the GT Kaltura video embed module for embedding videos from the new Georgia Tech MediaSpace repository
    Contrib (Third Party) Drupal Express components and their Drupal 8 status
    (Last Updated November 30, 2017)
    Component Name Available
    for
    Drupal 8?
    Comments?
    Admin Menu Superseded Use Admin Toolbar
    Admin Views In Drupal 8 Core  
    Block Reference Superseded Use the built in Entity Reference field
    CKEditor In Drupal 8 Core  
    CTools Production Not required by any previous Drupal Express modules in Drupal 8
    Custom Search Beta From the Custom Search project page: "The 8.x-1.0-beta branch is usable, and instead of overriding the default search block like it did with D6/7, it provides its own block(s)"
    Date In Drupal 8 Core  
    Diff Release Candidate See the Diff project page
    Field Group Beta See the Field Group project page
    Google Analytics Production See the Google Analytics project page
    IMCE Production See the IMCE project page
    IMCE MkDir No  
    Libraries Development Not required by any previous Drupal Express modules in Drupal 8
    Link In Drupal 8 Core  
    LinkIt Production See the LinkIt project page
    Menu Block Production See the Menu Block project page
    Module Filter Production See the Module Filter project page
    Nodeblock Superseded Create a custom block type in Drupal 8 and add an Entity Reference field configured to reference node content
    Override Node Options Production See the Override Node Options project page
    Pathauto Production See the Pathauto project page
    Pathologic No  
    Revisioning In Drupal 8 Core Replaced by the combination of Workflows and Content Moderation.
    Token Production See the Token project page
    Transliteration No A filename transliteration patch for Drupal 8 core is available if you want to have filenames transliterated, but that patch hasn't been committed to production core yet
    Video Embed Field Production See the Video Embed Field project page
    View Unpublished Alpha See the View Unpublished project page
    Views In Drupal 8 Core Existing views do not migrate to Drupal 8, but can be recreated by hand
    Views Bulk Operations Production See the Views Bulk Operations project page
    WYSIWYG Filter In Drupal 8 Core  

    Drupal 8 Tips and Tricks

    Drupal 8 Tips and Tricks klp Mon, 03/14/2016 - 15:46
    Drupal Version

    This section is for tips and tricks specific to Drupal 8, which is quite different from it's predecessors, Drupal 7 and 6.  Topics posted here will eventually be migrated into the main sections of this handbook after some mainstream adoption of Drupal 8 on campus has occurred.


    A quick overview of writing Drupal 8 modules (and migrating Drupal 7 modules to Drupal 8) can be found on the Ivan Allen College's Web Developer website.


    The current development version of the CAS module does work, but there is no documentation yet.  The most important piece of the puzzle is that after you install and enable the module, the default login path is now '/caslogin', not '/cas' as in the Drupal 6 and 7 versions.  (You'd think a change like that would be documented somewhere ...)  Also, even though the configuration page has options for Gateway and Forced Login settings, these are not fully functional yet, so you'll most likely have to go to /caslogin to log into your site every time, though you can make an alias to /caslogin (e.g. '/gtlogin')


    Drupal 7 began forcing mySQL to act like a traditional SQL server so that all SQL code used in Drupal will be highly compatible with other database systems like PostgreSQL or SQLite.  This means that mySQL statements that syntactically work in other contexts may produce errors under Drupal 7 or 8.  Drupal 8 adds the 'ONLY_FULL_GROUP_BY' restriction, which can potentially cause custom mySQL code that worked in Drupal 7 to fail with errors in Drupal 8.

    Here's the exact settings being used in Drupal 8: 

    • SET sql_mode = 'ANSI, STRICT_TRANS_TABLES, STRICT_ALL_TABLES, NO_ZERO_IN_DATE, NO_ZERO_DATE, ERROR_FOR_DIVISION_BY_ZERO, NO_AUTO_CREATE_USER, ONLY_FULL_GROUP_BY'

    The mySQL Reference Guide has full details on these SQL modes and their effects.  (See especially the section on STRICT mode and ONLY_FULL_GROUP_BY mode.)


    Here's how to whitelist HTML tags in your module output that are normally stripped out by the XSS filter:

        $tagList = array('input');
      
        return array(
          '#markup' => $buffer,
          '#allowed_tags' => array_merge(\Drupal\Component\Utility\Xss::getAdminTagList(), $tagList),
        );

    And here's how to allow data URLs in your module output for displaying images with data that you've already pulled in from a data source (code updated 2017-12-11 to a better format that avoids whitescreening in certain use cases):

      $allowedProtocols = \Drupal\Component\Utility\URLHelper::getAllowedProtocols();
      $allowedProtocols[] = 'data';
      \Drupal\Component\Utility\URLHelper::setAllowedProtocols($allowedProtocols);

    If you're wanting to add features to CKEditor in Drupal 8, don't do it the hard way.  Check out our compilation of CKEditor tips and tricks first!


    Here's a quick reference guide to working with the new configuration management system.  You'll need this if you want to build a module that adds its own configuration to Drupal during its installation process:

    Simple Configuration API | Drupal.org


    Add additional tips and tricks here.


    Additional Resources

    Controlling Drupal 8 Caching

    Controlling Drupal 8 Caching
    Category
    kp37 Fri, 12/01/2017 - 16:39
    Drupal Version

    Drupal 8 has a much more sophisticated and ultimately aggressive caching system.  While this is supposed to be a good change, sometimes it really gets in your way.

    Kevin Pittman has written an blog post on Drupal 8 Internal Caching for Dummies that helps clarify the different types of caching that occur and how to configure them to work to your advantage.

    (The advice that had been posted here by Kevin has been removed as it was no where near as accurate as what is in the blog post.)

    Drupal 8 CK Editor Enhancements

    Drupal 8 CK Editor Enhancements kp37 Thu, 01/26/2017 - 16:15
    Drupal Version
    Tags

    Drupal 8 includes the popular What You See is What You Get (WYSIWYG) editor CKEditor, but out of the box it only provides the 'minimal' configuration, which is missing a lot of the features you may have come to enjoy when implementing CKEditor in Drupal 7 using the CKEditor module and the full version of CKEditor.

    Fortunately, there are a few easy ways to make CKEditor much more useful.  To start, the Drupal core team has assembled a list of add-on modules that implement popular CKEditor plugins, which makes it very easy to add official CKEditor features to your site:

      CK Editor Modules and Plugins | Drupal.org

      Important:  Most if not all of these modules do not include the actual plugin.  You will need to go to ckeditor.com and download the matching plugin, then create a 'libraries' directory at the root of your Drupal 8 installation and unpack the plugin into that directory.  For example, for the 'font' plugin, you should end up with a 'libraries/font' directory, which would have a file named 'plugin.js' in it, along with any other supporting files for the plugin.

      When downloading a plugin, you will need the version that works with CKEditor 4.5.1, as that is what comes with Drupal 8.2.x.  When you eventually upgrade to Drupal 8.3 or later, re-check the version of CKEditor included, as when they update to CKEditor 4.6, you'll have to update all of the extra plugins that you are using.

      In addition to the plugin based modules referenced above, the following special purpose Drupal 8 / CK Editor modules may also be of interest:

      • Editor Advanced Link - Adds additional properties (title, class, id, target, rel) to the Link properties box
      • Editor File - Adds the ability to upload files directly into CKEditor (just like you can now do with Images)

      Here are a few more tips and tricks for enhancing CKEditor:

      Where Did Image Properties Go?

      One thing you won't find in any of the lists above is a means of bringing back the extensive set of image properties available in CKEditor under Drupal 7, and there's a reason for this.  The designers of Drupal 8 want you to upload properly sized images and let Drupal handle their placement, so that they can be as responsive as possible.  This is actually a good thing in retrospect, as it's going to minimize the situations where a content editor uploads a giant 3000+ pixel image and then uses the size properties to make it fit on the screen.

      That said, you're probably going to want a way to float images left and right.  That ability still exists and is enabled via Configuation -> Content authoring -> Text formats and editors.  Modify one of your text formats and look for the "Align images" checkbox under "Enabled Filters".  The explanation for the option isn't very informative, but enabling it will enable options on the CKEditor image placement pop-up to left or right align (float) the image.

      You'll also want to enable "Caption images" directly below "Align images", as it provides a very useful feature for entering automatically positioned and formatted visible image captions.

      Expanding CKEditor's Default Window Height

      One feature lost in Drupal 8 is the ability to set the number of rows on a textarea field and have CKEditor expand to fill that space.  However, you can still manually set the height of CKEditor, but you have to do it by creating a simple module.  We won't go into how to write a module here, as there are plenty of tutorials out there covering this basic topic.  Once you have the skeleton of a bare bones module in place, add this function to it, replacing 'xxxxxx' with the machine name of your module:

      function xxxxxx_editor_js_settings_alter(array &$settings) {
        foreach (array_keys($settings['editor']['formats']) as $text_format_id) {
          if ($settings['editor']['formats'][$text_format_id]['editor'] === 'ckeditor') {
            $settings['editor']['formats'][$text_format_id]['editorSettings']['height'] = '600px';
          }
        }
      }

      This will set your CKEditor window height to 600px tall.  Just change 600 to another value if you prefer the window to he taller or shorter.

      Adding a Font Size Drop-Down

      While it is not recommendable to add a font selection drop down on Georgia Tech sites, many content editors want to be able to make lines of text bigger, and if you don't give them a way to do it correctly, they'll make those lines headings, which creates accessibility problems.

      The easiest way to fix this is to add the CKEditor Font plugin using the CKEditor Font module. Once installed you can edit any of your text formats and add the 'S' button (for font 'S'ize) to the button bar.  However, if you want to be fully accessibility compliant, you should also change the available size list from point sizes to percentages.  That can be done by creating another bare bones module (see the Window Height section above) and putting the following code into it:

      function xxxxxx_editor_js_settings_alter(array &$settings) {
        foreach (array_keys($settings['editor']['formats']) as $text_format_id) {
          if ($settings['editor']['formats'][$text_format_id]['editor'] === 'ckeditor') {
            $settings['editor']['formats'][$text_format_id]['editorSettings']['fontSize_sizes'] ='80%/80%;90%/90%;Normal/100%;110%/110%;120%/120%;130%/130%;140%/140%;150%/150%';
         }
        }
      }

      Note: if you want to change the font size menu and the window height, you can (and should) combine the code into a single function in a single module.  Just add the innermost assignment line from one of the code snippets to the other snippet.

      Getting CKEditor to Use Your Theme CSS

      By default CKEditor uses a very basic set of CSS, so the text you create and edit won't look exactly like it will when displayed by your Drupal site's theme.  However, you can tell CKEditor to use your site's CSS so that the editing experience better reflects reality.

      To do this, you will need to be using a custom sub-theme.  In your sub-theme's .info.yaml file, add the following lines:

      ckeditor_stylesheets:
        - css/fonts.css
        - css/general.css

      YAML is very picky about spacing, so take care to get it right:  it's two blank spaces (no tabs allowed), then a dash, then one more space.  Of course, replace fonts.css and general.css with whichever CSS files are needed to implement your theme's special text formatting.  You can have any number of CSS lines underneath the 'ckeditor_stylesheets:' heading.

      If you add this to a theme that is already active, be sure to flush all of your caches to get the change to take effect.

      Front End Tools & Tricks

      Front End Tools & Tricks esembrat3 Wed, 11/08/2017 - 10:24
      Drupal Version

      Front end refers to the forward facing design and implementation of the look of the website. 

      Mercury News and Events

      Mercury News and Events

      Mercury (Hg) is a central repository for sharing news and events at Georgia Tech. It can be used to publish news and events to any campus website, but cannot be used with websites hosted outside our campus network.

      The basic concept for using Mercury is that a campus unit will have a news and events group created on the Mercury server (http://hg.gatech.edu/).  The unit can then add the Mercury Hg Reader module to their website to pull news and events from their Mercury group and display those items on their web pages.

      Please note: The Mercury system is only available on-campus or while connected to the Georgia Tech VPN.


      Mercury (Hg) Documentation

      root Thu, 07/06/2017 - 17:21

      Introduction to Mercury

      Introduction to Mercury
      Category
      afrank30 Tue, 08/04/2015 - 16:52
      Drupal Version
      Tags

      What is Mercury?

      Mercury is a Drupal-based content syndication system used to input news and events (plus related photos and videos) for websites. It is the back-end source for the Daily Digest, Campus Calendar, and News Center, as well as for news and event listings on dozens of other campus websites.

      How Does it Work?

      Communicators all over campus enter news and events (plus related photos and videos) into Mercury, which can then be shared among all users of the system. This way, you only have to enter and edit your information in a single place, but it can be shared with lots of different sites. Items entered into Mercury are associated with users’ groups (more on that in a minute).

      News and event items can be distributed to websites by building feeds of those items within Mercury. Other websites are configured to periodically visit Mercury to make a copy of the items contained in a feed and display them on the site. In a typical Mercury installation, the website will “check in” with Mercury every hour to get the latest copy of a feed. Therefore, depending on how your website is set up, items you enter in Mercury may not immediately appear on your website.

      Main Parts or Sub-systems

      Mercury consists of the following sub-systems.

      Groups

      All Mercury users are members of two or more groups (at a minimum, a Mercury training group plus the Georgia Tech Events Calendar group). Groups serve as buckets for content associated with the group's focus. Groups are typically set up for a main academic unit or office, but separate groups for a sub-units unit can be added as needed. For instance, a research center could have its own Mercury group separate from its parent school or interdisciplinary research institute. To request that a new group be established, please visit the 'Request a Group' form in Mercury.

      Users, Roles, and Permissions

      Users are associated with groups and may have varying roles within those groups — typically authors or publishers. It is possible to have different roles in different groups.

      • Authors have the ability to create content within their assigned groups, but it stays in draft form.
      • Publishers can publish content to make it live and available to other websites.

      Content

      As noted above, content consists of news, events, images, videos, profiles, and a few other types discussed elsewhere.

      Content entry forms provide many fields, so these items should be flexible enough for most purposes. For assistance with creating news and events (and related photos/videos), visit the how-to pages for creating news and events.

      Feeds

      The major point of difference between Mercury and your average content-management system is Mercury's feed system. Content can be organized (arbitrarily or via a selection of rules) into XML Feeds, which can then be displayed by remote sites (like yours). The Feeds system allows you to organize any content from Mercury — your own and others' — to populate your news and events pages, and the XML output format gives developers the flexibility to show those pages in a wide variety of ways.

      Feed Readers

      This is the code on your site that allows it to read the feeds you create and to display them. We offer a number of tools, including a Drupal module, for getting this set up.

      What's in a Name?

      In Greek mythology, Mercury was the messenger of the gods. Likewise, Mercury is our divine method of communicating and sharing information.

      When you visit the website where you enter content into Mercury, you'll notice that it starts with “Hg”, which is the symbol for the element Mercury on the periodic table. And well, heck, we're geeks: so we can do that ... sort of thing.

      Mercury Users Guide

      Mercury Users Guide
      Category
      esembrat3 Fri, 02/22/2013 - 08:38
      Drupal Version
      Tags

      This section provides an introduction to using the Georgia Tech Mercury (Hg) News and Events system.  None of the information in this section is Drupal specific - it's just being housed here for historic reasons.

      If you are looking for information on how to install and manage the Mercury Hg Reader module, we have a separate section about Mercury Developers Guide.


      Table of Contents

      Getting Started with Mercury

      Getting Started with Mercury
      Category
      afrank30 Tue, 12/30/2014 - 14:22
      Drupal Version
      Tags

      First Step: Logging In

      When you log in to Mercury for the first time, a Mercury user account will automatically be created for you.  The login link is on the upper left of the Mercury website at http://hg.gatech.edu/

      Please note: The Mercury system is only available on-campus or while connected to the Georgia Tech VPN.

      A group administrator cannot give you access to a group in Mercury until you have logged in for the first time.  So, if you expect to use Mercury and haven't ever logged in with your Georgia Tech account (e.g. gburdell1), please do so now.

      Your Default Groups

      As soon as you log in, you will become a member of two groups: Georgia Tech Events Calendar, and Hg Training.

      The Georgia Tech Events Calendar group is a group in which all Mercury users are a member with the basic role of Author. Currently the main calendar on the Georgia Tech Web site is populated with any event created in Mercury that is in a published state, and part of the Georgia Tech Events Calendar group. This allows users to keep internally focused events on their own sites and only promote events open to the campus on the main calendar. Therefore, when entering events get in the habit of selecting the Georgia Tech Events Calendar group with your group selections if you want your event to appear on the main calendar. Note that you're also required to select one of your "home" groups.

      The Hg Training group was set up for temporary training purposes. This group serves as a testing ground for helping users become familiar with generating Mercury content. However, any images, videos, or published content you add to this group will be viewable by others in the Mercury system.

      Permission to Publish

      In order to publish an event or news item in Mercury you must be a publisher of a group outside of the default groups. For most major campus units, there is already a group set up - consult the groups directory to request membership from the group's manager. If none of the existing groups apply to your needs, you can use the Group Request form to submit a request for a new group.

      Once you have been set up within a group, your first step to enter content into Mercury is to select the appropriate group on the right-hand side of the page. Once your group is selected, you will be given numerous options to create content on the left-hand sidebar.

      Groups, Users, and Roles in Mercury

      Groups, Users, and Roles in Mercury
      Category
      afrank30 Tue, 08/04/2015 - 16:55
      Drupal Version
      Tags

      About Mercury Groups

      Groups serve as buckets for content, and are often associated with an academic unit or office. Separate groups for sub-units can be added as needed. For instance, a research center could have its own Mercury group separate from its parent school or interdisciplinary research institute.

      However, the main purpose of groups is not to sort or categorize content, but to control who can edit (and delete) content.

      Users are associated with groups and may have varying permissions within each group; it is possible to have different roles in different groups. All Mercury users are members of one or more groups (at a minimum, your major affiliation plus the Hg Training group).

      Consult the groups directory to request membership from a group's manager. If none of the existing groups apply to your needs, please use the Group Request form to submit a request for a new group, or the Update Group information form to send correct managers for a group.

      A tutorial is available for managing group memberships in Mercury.

      About Mercury Roles

      Each Mercury group has different sets of permissions for different users. Each permissions set is collected into a "Role", of which these are the main types:

      1. Author
      2. Publisher
      3. Manager
      4. Administrator

      A tutorial is available for changing a user's Mercury role.

      Author

      Almost everyone you add to your group will have this role. An author can create content, but cannot make that content live (i.e. Publish it) and often cannot edit other people's content or feeds. This role is mainly useful if your group wants to:

      • have some users moderate content before it is made public,
      • allow people from other units to create draft content for your group, or 
      • allow people from other units to automatically add their events/news to your group/calendar.

      Warning: if you make someone an Author in your group, they can publish your group's items if they are a Publisher in any other group.

      Publisher

      Publishers can create, edit, and publish content and feeds. They can also act as moderators for Author-created content.

      Manager

      There can be only one...manager of a group. Similar to being an "Owner" of a web hosting site, it allows Mercury support staff to know who is primarily responsible for a group. They have the same powers as an Administrator, but can also bulk remove or modify more than one user at a time using "Operations".

      Administrator

      This role can add new members to a group, and can allow people to become "Authors", "Publishers" or "Administrators" for a group.


      Groups and Users Sub-Topics

      Managing Group Memberships in Mercury

      Managing Group Memberships in Mercury
      Category
      afrank30 Tue, 12/30/2014 - 14:30
      Drupal Version
      Tags

      To add or remove a person, you must have the role of Administrator for that group.

      Adding a Person

      1. On a Group page, find and select the Group tab at the top of the page (after the "View" tab).
      2. Select the "Add people" link.
        The shortcut to this link for any group is: http://edit.hg.gatech.edu/group/node/#/admin/people/add-user, where # is the group ID number.
      3. In the User name text box, type the name of the person you want to add.
        • If their name automatically appears as a drop-down after a few moments, select their name in that drop-down.
        • If not, the person needs to log in to Mercury, so that their account can then be found in the system.
      4. Check the boxes next to the Roles this person should have within your Group.
      5. Select the Add users button at the bottom of this page.
      6. If successful, you will see a message at the top of the page that says "[User Name] has been added to the group [Group Name]."
      7. You can return to the Group tab page by selecting the Group link in the breadcrumbs, after the name of this group.

      Removing a Person

      1. On a Group page, find and select the Group tab at the top of the page (after the "View" tab).
      2. Select the "People" link.
        The shortcut to this link for any group is: http://edit.hg.gatech.edu/group/node/#/admin/people, where # is the group ID number.
      3. In the Name text box, type the name of the person you want to remove and select Apply.
        • If their name automatically appears as a drop-down after a few moments, select their name in that drop-down and then select the Apply button.
        • If not, you may have misspelled their name (or they may be a member under their GT Account, e.g. gburdell3).
      4. Find this person's account in the table at the bottom and select the Remove link in the farthest right column for their row.

        (Only the Manager of the Group can remove more than one user at a time using "Operations".)
      5. Select the Remove button on the next page.
      6. If successful, you will see a message at the top of the page that says "The membership was removed."

      Changing a User's Role (Permissions) in Mercury

      Changing a User's Role (Permissions) in Mercury
      Category
      afrank30 Tue, 08/04/2015 - 17:06
      Drupal Version
      Tags

      To be able to change a person's Role (permissions), you must have the Role of Administrator for that group.

      Changing a Person's Role

      1. On a Group page, find and select the Group tab at the top of the page (after the View tab).
      2. Select the People link.
        The shortcut to this link for any group is: http://edit.hg.gatech.edu/group/node/#/admin/people, where # is the group ID number.
      3. In the Name text box, type the name of the person whose role you want to change.
        • If their name automatically appears as a drop-down after a few moments, select their name in that drop-down and then select the Apply button.
        • If not, you may have misspelled their name (or they may be a member under their GT Account, e.g. gburdell3).
      4. Find this person's account in the table at the bottom and select the Edit link in the farthest right column for their row. (Only the Manager of the Group can modify more than one user at a time using "Operations".)
      5. On the next page, check or uncheck the boxes next to the Roles you want to add or remove.
      6. Select the Update membership button at the bottom.
      7. If successful, you will see a message at the top of the page that says "The membership has been updated."

      How to Share Content Between Groups in Mercury

      How to Share Content Between Groups in Mercury
      Category
      afrank30 Tue, 08/04/2015 - 18:22
      Drupal Version
      Tags

      The Interface

      At the bottom of most every type of content in Mercury, you will see a section called Groups audience, which will let you choose from a list of the Groups of which you are a member. You can select more than one Group by holding down the Command or Control button while clicking on each group's name.

      Your current group (example: "School of Awesomeness") will automatically be chosen. As appropriate, you might also get permissions to share your content with other groups you belong to (perhaps an affiliated School or Department).

      Don't Use Groups as Categories

      One of the most basic ways you can sort your Mercury content is by using Groups. However, since the purpose of groups is to control who can edit (and delete) content, you will have more control over which items show on your website by using manual feeds and talking with your counterparts in other groups about news or events you would each like to share.

      How to Safely Share Content with Other Mercury Groups

      If you want to share content between groups, you need to contact the group manager and make sure you both have the same understanding of what kinds of news/events to share and when. This is especially important if:

      • A group is using automatic feeds, as any content you share may automatically be added to their calendar or list of news items.
      • One of you edits or deletes a piece of content that the other group needs.

      Sharing Events with the Main Georgia Tech Calendar Site

      To have your event show on the main Calendar site, check the box labeled Include this event on the Campus Calendar (within the Categories and Keywords section).

      Canceled or Postponed Events

      If an event is canceled or postponed, rather than deleting it from the system, add the word “CANCELED:” or “POSTPONED:” to the beginning of the event "Title". This will prevent broken links and confused users who may be looking for updated event information. Currently, events are never removed from the main Calendar site, so this also helps clarify their status on that website.

      Sharing News with the Main Georgia Tech News or Research Horizons Sites

      Institute Communications

      First, contact an Institute Communications person from the Media Relations, Campus Communications, or the Research News teams. Tell them about story you have that you think would be great on one (or both) of these sites.

      Categories

      If research-related, check the box next to the most appropriate topic under "Core Research Areas".

      If not research-related, let Institute Communications know which of these categories your story best matches: Business and Economic Development, Campus and Community, Earth and Environment, Health and Medicine, Science and Technology, or Society and Culture.

      Create and Attach Media Files Correctly

      In addition, it is especially important than any media on a news story for one of these sites be correct in its:

      • Aspect ratio: a 16 by 9 ratio is needed
      • Order of the first and second images: the first image listed is used as the Thumbnail or small image, while the second image chosen under "Media" is shown at the top of the full story page for this news item on those sites. The only exception to this is that any story with a video will automatically use the video instead at the top of the full story page.

      Feeds in Mercury

      Feeds in Mercury afrank30 Tue, 08/04/2015 - 16:45
      Drupal Version
      Tags

      What is a Feed?

      A feed is a list of content items from Mercury. Feeds let you organize any content from Mercury — your own and others' — and then display it on other web sites. The two most common types of content you will find in feeds are events and news.

      Manual versus Automated Feeds

      Content can be organized into two types of feeds in Mercury:

      • As an arbitrary Manual Feed, where you have complete control but must make every change yourself
      • Via a selection of rules in an Automated Feed that you set up once and don't have to touch again (unless you want to adjust those rules)

      Examples of Automated Feed Usage

      Commonly, people use relative dates, limit them to just one type of content (such as events only), and then connect these to hg_reader blocks and pages on their web site.

      However, you can also use these to find related content, without connecting the feed to a website (thanks to Kathleen Moore for this idea!). For example, you could make an automated feed that helps you curate content you might add to a manual feed. It could search by keywords, or show content from other people's groups.

      Examples of Manual Feed Usage

      Commonly, people use this to control which news stories or events show up on the homepage of their website.

      The only drawback to a manual feed is that nothing is added or removed from them, without someone's intervention.

      Feed Readers

      Readers allow your web site to pull in the feeds you create and display them on your site. Georgia Tech's Institute Communications offers a Drupal module, HG Reader, for getting this set up.

      Feed Item Limits

      As of the September/October 2017 Mercury refresh, all feeds can now contain a maximum of 200 items.

      • For an automated feed, any items beyond 200 items will not be displayed.  
      • For a manual feed, any new items beyond 200 will not be added.

      Mercury Feeds Sub-Topics

      Finding the ID for a Feed in Mercury

      Finding the ID for a Feed in Mercury
      Category
      afrank30 Thu, 07/16/2015 - 12:03
      Drupal Version
      Tags

      In Mercury, a feed ID is a five- or six-digit number that uniquely identifies a single feed (or list) within Mercury.

      A feed ID is different from the ID for an individual news or event item.  Make certain you are getting an actual feed ID and not the ID for a single item within that feed.

      Where to Find the Feed ID

      First, you need to find a feed. Navigate into one of the groups you belong to in Mercury, and search the middle of the page for the "Group Feeds" section. Underneath it are listed any feeds already created for your group.

      Select the Title of one of your fields listed in this table (for example, "Events: GT - Past 1 and future 6 months"). This takes you to the page for that feed.

      The feed ID is the number shown in the URL (web address), after the phrase "node/", when viewing a feed in Mercury. For example, in the URL http://hg.gatech.edu/node/416041, the feed ID is "416041".

      Using Another Group's Feed

      If you want to use a feed from another group, all you need is this ID number and you can use that feed on your site, too! You are not required to have a Mercury account to include feeds on your site. If you do not have an account and wish to display an existing feed, contact the administrator of that group to get the feed ID number.

      Creating an Automated Feed in Mercury

      Creating an Automated Feed in Mercury afrank30 Tue, 12/30/2014 - 14:11
      Drupal Version
      Tags

      Getting Started

      1. Log in to Mercury (at http://hg.gatech.edu).
      2. Select the link for your group (example: "Office of Something Awesome") in the column on the right side of the screen.
      3. Select the green Create automated link in the Feeds section of the left column.

      Rule of Thumb

      Tailor your feed output (using the options under Show items where...) to the smallest set necessary for your needs.  The more items you include, the harder Mercury has to work to assemble your feed, and the slower your website will get each time it connects to Mercury to get an update of your feed.

      Consider limiting any archive feeds to no more than two years worth of news or events.  Chances are good that no one is really going to want to wade through anything more than that on your website.  If your unit's leadership wants to highlight specific news or events from an earlier time, just create a static "Historic Highlights" page and post the relevant information to that page so that interested site visitors can easily find it.

      Create Your Feed Filter

      NOTE: The filtering tools changed significantly after the September / October 2017 Mercury refresh.

      • For Item type is any of..., chose only those items types that you need.  A good practice is to create only single-type feeds (i.e. one feed for news, and a second feed for events).
      • For Group, choose the name of your group.  Otherwise, you'll be pulling items from every group in Mercury, which is never a good idea.
      • To limit items based on dates, use:
        • Event start for an events feeds
        • News dateline for a news feed
        Next, select a filter type:
        • after
        • on or after
        • before
        • on or before
        • between
        Next, enter your actual filter.  Below are some examples of commonly used filters:
        • now - the exact moment that the feed is being assembled
        • 2 months ago
        • 3 years ago
        • 2017-05-15 - A specific date in year-month-day format
        • For more possible date formats, please see the PHP Guide to Relative Date Formats
        As an example, 'News dateline' 'after' '1 year ago' will give you a feed of all news from the past year.

      At any time, you can select APPLY FILTERS to see what Mercury items you get.  If you don't get anything, then either you set up a rule wrong, or there just isn't any content yet that matches those rules.  (It's always helpful to have a least one item in the system that matches the feed you are creating, just to act as a sanity check that you have your filter rules entered correctly.)

      Feed Item Limits

      As of the September/October 2017 Mercury refresh, all feeds can now contain a maximum of 200 items.

      • For an automated feed, any items beyond 200 items will not be displayed.  
      • For a manual feed, any new items beyond 200 will not be added.

        Creating a Manual Feed in Mercury

        Creating a Manual Feed in Mercury dgivens8 Fri, 09/23/2016 - 17:26
        Drupal Version
        Tags

        A manual feed is a feed which all items are pre-selected/approved. For more information, see the documentation on automated versus manual feeds.

        Getting Started

        1. Log in to Mercury (at http://hg.gatech.edu).
        2. Select the link for your group (example: "Office of Something Awesome") in the column on the right side of the screen.
        3. Select the green Create manual link in the Feeds section of the left column.

        Name Your Feed

        Title the feed something descriptive that will allow you and others to identify it through a search.

        Create Your Feed Filter

        NOTE: The filtering tools changed significantly after the September / October 2017 Mercury refresh.

        A feed filter for a Manual Feed is strictly to help you find content to add to your feed.  It will have no effect on your actual feed.

        The filter rule that appears by default is “Item type.” Once you’ve selected a type, you can then use the “Add a rule” drop-down menu to add additional filter rules such as “Core research area” or “Keyword.”

        Once you’ve finished adding the desired filtering rules, select the Apply Filters button and you’ll see the available news items below.

        Move Content Into the Feed

        The list of news items you’ve filtered out now appears on the left side of the screen under your filters. Once you’ve looked through the available items and picked the news titles you want to appear in your feed, drag them to the “Feed items” box on the right side of the screen.

        Don't forget to Save your changes before navigating off to another page.

        Categories and Keywords

        Categories and Keywords
        Category
        afrank30 Tue, 08/04/2015 - 17:39
        Drupal Version
        Tags

        Mercury provides a variety of ways to categorize and tag your content, and understanding their meanings will help you to utilize them effectively.

        Core Research Areas

        Georgia Tech has organized its research into core areas of special interest, and encourages you to tag News items with these areas in Mercury.  These research area tags are used to help find stories:

        • By those reading our news sites, such as the main NewsroomResearch Horizons, and Research (which pull almost all their news from Mercury)
        • By Institute Communications staff, to filter stories from our many brilliant units to feature on these central news sites
        • By individual units to highlight their news stories based on topic (using Feeds)

        List of Research Areas

        Georgia Tech has organized its research into the following core areas of special interest:

        • Bioengineering and Bioscience
        • Cybersecurity
        • Data Engineering and Science
        • Electronics and Nanotechnology
        • Energy and Sustainable Infrastructure
        • Manufacturing, Trade, and Logistics
        • Materials
        • National Security
        • People and Technology
        • Public Service, Leadership, and Policy
        • Renewable Bioproducts
        • Robotics
        • Systems

        Categories

        Category tags allow for easier sorting of content items.  Event category tags will help visitors browsing events on the main Georgia Tech Events Calendar to narrow down the list to those types of events they are most interested in attending.

        News, Image and Video Categories

        • Institute and Campus
          • Alumni
          • Arts @ Tech
            • Community
            • Education
            • Exhibitions
            • Performances
            • Art Research
            • Student Art
          • Congressional Testimony
          • Economic Development and Policy
          • Institute Leadership
          • Special Events and Guest Speakers
          • Student and Faculty
          • Student Research
        • Research
          • Aerospace
          • Architecture
          • Biotechnology, Health, Bioengineering, Genetics
          • Business
          • Cancer Research
          • Chemistry and Chemical Engineering
          • City Planning, Transportation, and Urban Growth
          • Computer Science/Information Technology and Security
          • Digital Media and Entertainment
          • Energy
          • Engineering
          • Environment
          • Life Sciences and Biology
          • Military Technology
          • Music and Music Technology
          • Nanotechnology and Nanoscience
          • Physics and Physical Sciences
          • Policy, Social Sciences, and Liberal Arts
          • Robotics 

        Event Categories

        • Arts and Performance
        • Career/Professional development
        • Conference/Symposium
        • Other/Miscellaneous
        • Seminar/Lecture/Colloquium
        • Sports/Athletics
        • Student sponsored
        • Training/Workshop

        Invited Audiences (for Events)

        This option lets you indicate who your event is aimed at. You can choose more than one audience, if you'd like, by holding down Control/Command while clicking on each audience.  Setting the invited audiences allows people to narrow down which events they might be interested in when browsing events on the main Georgia Tech Events Calendar.

        You can choose one or more of the following audiences:

        • Undergraduate Students
        • Graduate Students
        • Faculty/Staff
        • Public

        Keywords

        Keywords allow you to tag Mercury content for later sorting.  This can be helpful when you need additional categories that aren't included in the shared Categories already offered.  Keywords:

        • Are not generally displayed on central news or events sites, and are more often used for your unit's web site.
        • Must be spelled and capitalized identically in order to be used for sorting and filtering.
        • Are entered as a comma-separated list of terms describing the item, e.g. "aircraft" or "5th street."
        • Should be kept as short and as plentiful as possible
        • Should not be a repeat of the item title.

        Adding a News Item to Mercury

        Adding a News Item to Mercury
        Category
        afrank30 Tue, 12/30/2014 - 16:23
        Drupal Version
        Tags

        Preparatory Steps

        Log In and Choose Your Group

        After logging in to Mercury, your first step to enter content is to select the appropriate group on the right-hand side of the Mercury site.

        Select the main group to which this content is relevant.

        Once your group is selected, you will be given numerous options to create content on the left-hand sidebar:

        Add Media (Optional)

        If your news item will include any images or videos, you have to upload those first, before adding a news item. Learn how to upload an image or upload a video to Mercury. 

        Beware of Copy and Paste!

        Microsoft Word and some other applications use several characters that do not work well on the Web. Common examples are ampersands (&), angled quotes (single and double) and long dashes (en and em dashes).

        For most long fields in Mercury, you can get around the vast majority of these issues by clicking on the paste from word button. However, this button is not available for short text fields without an Editor Toolbar (particularly of note: Title, subtitle, summary sentence and any field that might contain a name with apostrophes. If you cut and paste from Word into these fields, you may want to re-type any punctuation from the pasted text as a precaution. Another approach is to put your text into a plain text program first (Notepad for PC or Text Edit for Mac) and copy and paste into Mercury from there.

        Sharing With Georgia Tech News and Research Publications

        Please see the guidelines for sharing news with the main Georgia Tech News Site or the Research Horizons Site if you are preparing this news item to be shared with either group.

        Create Your News Item

        From the left-hand sidebar, select Create News or Create External News

        Required Fields

        Title

        Your news item might be shown in places other than your website. So, choose a Title that:

        • clearly explains what your news item is about to a general audience (try to highlight the most important thing about it).
        • is self-explanatory even when not on YOUR website.
        • is concise, around eight words, so it doesn’t run over when feeding into other places across various websites.
        • has a catchy or informative headline that will inspire the reader to actually read your news story. 
        • you will not need to change, as changing the title cause duplicates on the news site or break links to this story.

        Summary Sentence

        • Provide information that adds to the information already given in the Title, and use only 10 to 12 words at most.
        • This will show up on gatech.edu's GT News feed (if you share with their group).
        • This often displays below the headline, so don’t be repetitive.

        Dateline/Location

        These fields auto-populate with today’s date and Atlanta, GA — in most cases, leave as is.

        Contact

        If someone has questions, who can answer them? Or, who’s the author? 

        Include that person’s name, email address, and phone number.

        Groups

        If you want this article to show up in multiple places, select all the relevant groups.

        The news sites where this item will show up. Your group (example: "Office of Awesome") will automatically be chosen. As appropriate, you might also get permissions to share your news item with other groups (perhaps an affiliated School or Department). This allows you to syndicate the content to other sites.

        Default Workflow

        Change the workflow from “Draft” to “Published” so that your item shows up in news feeds.

        Unless you’re not finished, in which case, save as a Draft to come back to publish it later.

        Recommended Fields

        Body

        You can give a fuller description of the news item here. It can have lots of details, and multiple paragraphs are allowed. Avoid leaving the Body section blank. 

        This section should provide information about the news item itself, such as whether it’s part of a series, activities that will take place at the news item, or context of why a speaker is relevant to campus. If you are copying and pasting text, refer to the “Beware copy and paste” note above. Hyperlink websites in your text (e.g., if your text reads “clough.gatech.edu,” make sure that text is clickable). For longer URLs, hyperlink words to the website so the URL is not messy within the news item link (e.g., for a long application link, use the words “Apply online,” and hyperlink those words to the application URL). Be as specific as possible, but know that you can link to other pages for more information (such as agendas, directions, or speaker bios).

        Related Links

        Drop this area down and include any relevant websites — perhaps any organizations/Schools/Units associated with the story. 

        Repeat important links from the Body section here to make sure readers can find the information.

        Category

        The goal of these tags is to make your news item easier to find on OTHER news sites (especially the very large Newsroom site). Choose the category that best fits your news item. To select multiple categories, hold down the “Control” (ctrl) key while clicking each applicable category.

        Keywords

        These help your news item be associated with others that are about the same thing, and it also can be used to feed websites. Make sure you spell words correctly, place commas correctly, and try to use keywords that auto-populate as you type so you’re not creating too many new ones.

        Commas will separate each keyword, so some things may need to be altered to work as keywords (e.g., “School of Literature, Media and Culture” should be entered without commas, or else it will be processed as “School of Literature” and “Media and Culture.”)

        Core Research Areas

        If your news applies to one of the Core Research Areas, check the corresponding boxes accordingly. Your selections here should match those in the “Category" and "Keywords” sections. 

        Optional Fields

        Summary

        This appears in the news feed the day your news item occurs. Your summary should be one to two sentences in length, and can expand a bit from the Summary Sentence.

        You may also use the same copy from the Summary Sentence — these two never show up at the same time. Be aware that this does not fill the main body space on the news item listing itself; the Body field will do that.

        Subtitle

        Give a little more detail than what's in the Title, and do not repeat the Title.

        Media

        Type in the title of any image or video you have previously uploaded associated with this listing. Results will populate as you begin to type.

        File attachments

        This is an opportunity to attach files that do not fit into the image or video category, such as a PDF application, guidelines, or reports. However, this requires the user to download a file to be able to view it (unlike photos or videos items), so make sure anything you’re attaching here is worth the user’s time to download. News item flyers are generally better included as images rather than attachments.

        Adding an Event to Mercury

        Adding an Event to Mercury
        Category
        afrank30 Tue, 12/30/2014 - 15:49
        Drupal Version
        Tags

        Preparatory Steps

        Log In and Choose Your Group

        After logging in to Mercury, your first step to enter content is to select the appropriate group on the right-hand side of the Mercury site.

        Select the main group to which this content is relevant.

        Once your group is selected, you will be given numerous options to create content on the left-hand sidebar:

        Add Media (Optional)

        If your news item will include any images or videos, you have to upload those first, before adding a new event. Learn how to upload an image or upload a video to Mercury. 

        Beware of Copy and Paste!

        Microsoft Word and some other applications use several characters that do not work well on the Web. Common examples are ampersands (&), angled quotes (single and double) and long dashes (en and em dashes).

        For most long fields in Mercury, you can get around the vast majority of these issues by selecting the paste from word button. However, this button is not available for short text fields without an Editor Toolbar (particularly of note: Title, subtitle, summary sentence and any field that might contain a name with apostrophes. If you cut and paste from Word into these fields, you may want to re-type any punctuation from the pasted text as a precaution. Another approach is to put your text into a plain text program first (Notepad for PC or Text Edit for Mac) and copy and paste into Mercury from there.

        Create Your Event

        From the left-hand sidebar, select Create News or Create External News

        Required Fields

        Title

        Your event might be shown in places other than your website. So, choose a Title that:
        • clearly explains what your event or news item is about to a general audience (try to highlight the most important thing about the event).
        • is self-explanatory even when not on YOUR website.
        • is concise, around eight words, so it doesn’t run over when feeding into other places across various websites.
        Canceled or Postponed Event Titles

        If an event is canceled or postponed, rather than deleting it from the system, add the word “CANCELED:” or “POSTPONED:” to the beginning of the event "Title". This will prevent broken links and confused users who may be looking for updated event information. Currently, events are never removed from the main Calendar site, so this also helps clarify their status on that website.

        Summary Sentence

        • Give information that adds to the information already given in the Title, and use only 10 to 12 words at most.
        • This will show up on gatech.edu's GT Events Calendar or News feed (if you share with their group).

        Location

        You only need to enter information into the FIRST box. Type at least the Building and Room Number but, for events with an off-campus audience, consider adding the Full Address in case they need directions.

        Contact

        This is very helpful for your audience if they have questions, especially when your event is shown on OTHER CALENDARS (i.e. not yours). Include a specific name, department, email, and phone number.

        Invited Audience

        • Choose the audience for which this event is intended: the public, students, faculty/staff.
        • You can choose more than one audience, if you'd like, by holding down Control/Command while clicking on each audience.

        Event Category

        The goal of these tags is to make your event easier to find on OTHER calendars (especially the very large GT Events Calendar).

        There’s a checkbox labeled "Include this event on the Campus Calendar” (within the Categories and Keywords section). Including events on the campus calendar is as simple as checking this box. To exclude them from the campus calendar, leave the box unchecked.

        Groups

        The calendars where this event will show up. Your group (example: "Office of Awesome") will automatically be chosen. As appropriate, you might also get permissions to share your event or news item with other groups you belong to. This allows you to syndicate the content to other sites. Be sure to check with the managers in that group to clarify whether they want you to do this for their group, as their may be an approval process they would prefer.

        Default Workflow

        Choose "Published" or your item stays hidden and will not show up on any calendars or news feeds. Once published, anyone in the Mercury system can find your event and add it to their manual feeds.

        The Draft option is there for times when you need to save incomplete work and come back to it later, or to show to others before making it live.

        Event Time

        A calendar will pop up and allow you to select the Date, but you must type in the Time.

        Specify a From and To date/time for your event. The To date is not required, but to make your entry as useful as possible, please include a To date with an ending time if your event takes place during a specific time. Be sure to indicate AM/PM. You can check the box, if relevant, for an “All Day” event.

        Repeat

        These options will be useful if your event takes place over a series of days or several times in a specified time frame. A couple of examples:

        • An event happening over multiple days: If you have a three-day seminar that occurs February 1 - 3 from 9:00 a.m. to 4 p.m., you would select February 1 for the From date and 9:00 AM for the time. For the To date, you would also select February 1, but 4:00 PM for the time. Under the Repeat options, select “Every” in the Frequency drop-down menu and “Days” in the Period drop-down menu. In the Until field, you would select the day after the last date of the seminar: February 4. This will make your event repeat in the calendar each day through February 3.
        • An event occurring at a regular interval each week/month: Perhaps you have a recurring event that takes place on a specific day of the month, such as the second Monday or last Friday. You can find those options under the Advanced section of the Repeat options. Example: If a lecture series occurs on the second Monday of the month throughout the semester, you would enter the first time it occurs in the From and To fields, then select “Every” in the Frequency drop-down menu and “Months” in the Period drop-down menu. In the Until field, you would enter a date after the last lecture takes place, but before the second Monday of the next month. Then, in the Advanced options, select “Second Monday” under the Day of Week list. This will list your event in the calendar on the second Monday of the month within the range you selected. You can also add or exclude dates from a series. Say your March lecture is postponed a week; you can add the date for the March event in the field under the Except options, and provide the date it is rescheduled in the field under the Additional options.
        Repeat vs. Individual events (and Copying)

        One thing to note about using the Repeat options versus entering individual events for an ongoing series is that if you use Repeat, the event title will be the same every time it shows up in the calendar. When entering an event like the lecture series example, you may prefer to have a speaker’s name or subject in the title for each occurrence so that more details are available upon viewing the title. If this is the case, you will need to forego using the Repeat options and instead enter a separate event for each occurrence of the lecture series.

        If you want to make multiple copies of a similar event, you can use the "Clone" tab to make a nearly exact copy of an event, and then just update a few of the details.

        Optional Fields

        Summary

        This appears in the calendar feed the day your event occurs. Your summary should be one to two sentences in length, and can offer details not found in the Title or Summary Sentence.

        You may also use the same copy from the Summary Sentence — these two never show up at the same time. No need to include the date, time, or location here, as they have their own places. Be aware that this does not fill the main body space on the event listing itself; the Body field will do that.

        Body

        You can give a fuller description of the event here. It can have lots of details, such as times, agendas, etc. Multiple paragraphs are allowed.

        This section should provide information about the event itself, such as whether it’s part of a series, activities that will take place at the event, or context of why a speaker is relevant to campus. Avoid leaving the Body section blank. If you are copying and pasting text, refer to the “Text” note about using the "Paste from Word" button. Read through your text for duplicate information you’ve already specified, such as the date, time, and location, and delete those pieces. Hyperlink websites in your text (e.g., if your text reads “clough.gatech.edu,” make sure that text is selectable). For longer URLs, hyperlink words to the website so the URL is not messy within the event link (e.g., for a long application link, use the words “Apply online,” and hyperlink those words to the application URL). Be as specific as possible, but know that you can link to other pages for more information (such as agendas, directions, or speaker bios).

        More Location details

        You may specify phone number, URL, or email if you choose. 

        If your event is open to the public or at a location to which attendees may need a map, you can also reference map.gatech.edu. Select the name of your chosen building, then select the share link on the pop-up to get a direct link to that building on the map. (Tip: If you have trouble finding the share link for a building on the map site, check if your web browser is using any Ad blockers.)

        Related Links

        Select the arrow to expand this section. Include any relevant links, such as speaker bios, school or college websites, registration or application pages, or other links for more information. Repeat links from the Body section here to make sure readers can find the information.

        Keywords

        Begin typing relevant keywords here to see what has already been used. When possible, use the same phrasing, wording, capitalization and spacing as keywords that appear while typing, so that related events can be grouped together. Commas will separate each keyword, so some things may need to be altered to work as keywords (e.g., “School of Literature, Media and Culture” should be entered without commas, or else it will be processed as “School of Literature” and “Media and Culture.”)

        Media

        Type in the title of any image or video you have previously uploaded associated with this listing. Results will populate as you begin to type, with media from your group showing towards the top of this list.

        File attachments

        This is an opportunity to attach files that do not fit into the image or video category, such as a PDF application, guidelines, or reports. However, this requires the user to download a file to be able to view it (unlike photos or videos items), so make sure anything you’re attaching here is worth the user’s time to download. Event flyers are generally better included as images rather than attachments.

        Adding an Image to Mercury

        Adding an Image to Mercury
        Category
        afrank30 Tue, 12/30/2014 - 15:58
        Drupal Version
        Tags

        Step by Step Instructions

        1. First, edit the image, if needed, on your computer. Best practices for images are:
          • If large, consider re-sizing your image to exactly the size that will look good on the desktop version of your site.
          • Use a consistent aspect ratio for your images: we recommend a ratio of 16 by 9, unless your image will only be for headshots or for Hg Reader thumbnails, which use a square 1:1 ratio.
          • Choose a good name for your image (all lower case, use hyphens instead of spaces, avoid punctuation, short but descriptive).
          • Make sure your filename ends in either .jpg, .jpeg, .png, or .gif (all lower case).
        2. Select Create Image on the left side, and follow these instructions:
        3. Provide a basic title for the image, which will appear next to the photo once the event is posted.
        4. Select Browse or Choose File and find the image that you would like to include, then select Upload
        5. Select any appropriate categories from the list and enter any keywords for the image.
        6. Choose the appropriate group(s) in the Groups audience field.
        7. Select Save

        Image Naming for Ease of Access

        You can make it easier to find images in Mercury by using a simple pattern for the Title field, such as:

        • Organization name or abbreviation: Clough
        • Significant subprogram or subcategory for your organization: Art Crawl, or Students
        • Date image was created or uploaded: 2013
        • Short phrase describing image (1-4 words): Winners in photography

        In this example, your title for this image would be: "Clough Art Crawl 2013 - Winners in photography"

        Remember that this title field will be visible to the public, either as an image caption on some News sites or as alternative text for screen readers.

        Where to Add Images for News/Events

        On both the Create Event and Create News pages, you can add Images under the section called Media.

        To attach individual images, start typing the title of an image you've created into one of these Media fields.

        Adding a Video to Mercury

        Adding a Video to Mercury
        Category
        afrank30 Tue, 12/30/2014 - 16:02
        Drupal Version
        Tags

        Overview of Steps

        1. Upload your video to YouTube and add accessible captions.
        2. Choose a good name for your video.
        3. Select Create Video on the left side and follow these instructions:
        4. Enter a title for the video, which will appear next to the video within a news or event item.
        5. Enter the ID for the video in the YouTube ID field.
          • The ID can be found by clicking on the “Share” link below the display of your video on Youtube.com. The series of text and/or numbers after “http://youtu.be” is the ID. For example, in the YouTube Share link “http:// youtu.be/123XYZ,” the video ID would be “123XYZ.”
        6. Select any appropriate categories from the list and enter any keywords for the video.
        7. Choose the appropriate group(s) in the Groups audience field.
        8. Select Save.

        Video Naming for Ease of Access

        Make it easier to find videos when trying to add them to news items. Use a simple pattern for the Title field, such as:

        • Organization name or abbreviation: Clough
        • Significant subprogram or subcategory for your organization: Art Crawl or Students
        • Date image was created or uploaded: 2013
        • Short phrase describing image (1-4 words): Winners in photography

        In this example, your title for this video would be: "Clough Art Crawl 2013 - Winners in photography."

        Where to Add Videos for News/Events

        On both the Create Event and Create News pages, you can add videos under the section called Media.

        To attach individual videos, start typing the title of a video you've created into one of these Media fields.

        Tips and Tricks for Mercury

        Tips and Tricks for Mercury
        Category
        afrank30 Tue, 08/04/2015 - 17:17
        Drupal Version
        Tags

        This section is for tips and tricks to making Mercury easier to use.  Feel free to add to this section any tips or tricks you've discovered.


        Tips and Tricks Sub-Topics

        Quick Guide to Fields in Mercury Events and News

        Quick Guide to Fields in Mercury Events and News
        Category
        ab89 Mon, 01/28/2013 - 09:59
        Drupal Version
        Tags

        This page highlights the main fields (boxes to type text into) that need to be completed for each type of content in Mercury. The OUTLINE for this page is below:

        Always-required Fields for Both Events and News

        These are the fields you will ALWAYS have to enter for EVERY type of information (news, event) you put into Mercury:

        Title

        Your event, news item, or image might be shown in places other than your website. So, choose a Title that:

        • clearly explains what your event or news item is about.
        • is self-explanatory even when not on YOUR website.

        Summary Sentence

        • Provide information that adds to the information already given in the Title, and use only 10 to 12 words at most.
        • This will show up on the Georgia Tech Events Calendar or News feed (if you share with their group).

        Groups

        The calendars and news feeds where this information will show up. Your group (example: "Clough Commons") will automatically be chosen. As appropriate, you might also get permissions to share your event or news item with other groups you belong to (perhaps an affiliated School or Department).

        Default Workflow

        Choose "Published" or your item stays hidden and will not show up on any calendars or news feeds.

        Required Fields for Events

        Below are the additional required fields you should fill in for each event.

        Event Time

        A calendar will pop up and allow you to choose the Date, but you must type in the Time.

        Invited Audience

        • Choose whether your events is for: the public, students, faculty/staff.
        • You can choose more than one audience, if you'd like, by holding down Control/Command while clicking on each audience.

        Event Category

        The goal of these tags is to make your event easier to find on OTHER calendars (especially the very large GT Events Calendar).

        There’s a checkbox labeled "Include this event on the Campus Calendar” (within the Categories and Keywords fieldset). Including events on the campus calendar is as simple as checking this box. To exclude them from the campus calendar, leave the box unchecked.

        Optional Fields for Events

        It is not required, but it is highly recommended that you also fill in these other fields for events:

        Location

        You only need to enter information into the FIRST box. Type at least the Building and Room Number but, for events with an off-campus audience, consider adding the Full Address in case they need directions.

        Contact

        This is very helpful for your audience if they have questions, especially when your event is shown on OTHER CALENDARS (i.e. not yours).

        Body

        You can give a fuller description of the event here. It can have lots of details, times, agendas, etc. Multiple paragraphs are allowed.

        Optional Fields for News

        To best publicize a news item when you share it, especially on the GT Events Calendar/News feed, it is highly recommended that you also fill in these other fields:

        Category and Core Research Area(s)

        These tags help people (including Institute Communications) sort through the HUGE number of news items to find topics of most interest to them.

        Body

        This is where the text of your news article goes. Without it, your news article will just be a title and summary sentence.

        Fields for Images

        If you plan to use an image with your event or news item, create it FIRST, before creating said event/news.

        Title

        Make it easier to find images when trying to add them to news items. Use a simple pattern for the Title field, such as:

        • Organization name or abbreviation: Clough
        • Significant subProgram or subcategory for your organization: Art Crawl or Students
        • Date image was created or uploaded: 2013
        • Short phrase describing image (1-4 words): Winners in photography

        In this example, your title for this image would be: "Clough Art Crawl 2013 - Winners in photography."

        Image (Browse / Choose File)

        Upload the file for your image or picture.

        Where to Add Images for News/Events

        On both the "Create Event" and "Create News" pages, you can add images under the section called "Media."

        Start typing the Title of images you've created into these fields to attach individual images.

        Cloning Mercury Content

        Cloning Mercury Content
        Category
        afrank30 Thu, 12/15/2016 - 11:03
        Drupal Version
        Tags

        If an article you want to re-share is already in Mercury, it is recommended that you simply locate it and add it to one of your feeds.  However, sometimes you may need to duplicate that item, such as if the focus of the piece needs to be changed to work for your own unit's website.Image removed.

        Copying or Cloning Content

        1. Select the Clone Content tab at the top of an item's page in the Mercury system (http://hg.gatech.edu/)
        2. Change the Title field to remove the text "Clone of"
        3. Make sure the correct group is chosen under Groups audience
        4. At the bottom, change Workflow to Draft
        5. Select Save (but only after taking the above steps first).

        Mercury Developers Guide

        Mercury Developers Guide afrank30 Fri, 12/13/2013 - 16:55
        Drupal Version
        Tags

        This section provides help, tips and tricks for using the Mercury Reader (hg_reader) module for Drupal 7, or other techniques, for bringing Mercury news and events into your Drupal website.

        If you are looking for assistance with posting news and events to the Mercury server, we have several Mercury Users Guide.

        Methods for Bringing Mercury into Drupal

        Drupal sites on campus have three options for getting news and events from this campus repository:

        1. Using the Mercury (Hg) Reader module provided by Institute Communications (only available for Drupal 7 at this time)
        2. Using a custom module to grab XML Feeds of content, which can then be parsed and stored locally on your Drupal site.
        3. Using Feeds Extensible Parsers to bridge between a Mercury XML feed and Drupal's Feeds Importer.

        By far, the first option is the easiest one to implement, and is thus the recommended option as well.


        Mercury Developers Topics

        Mercury Reader Installation

        Mercury Reader Installation esembrat3 Fri, 02/22/2013 - 08:41
        Drupal Version
        Tags

        The Communications Team at Georgia Tech developed a module, Mercury Reader (hg_reader), to provide turnkey access to importing news and events from Mercury into your Drupal site. If you just want a simple news or events page or pages, and you don't need to amend the data once it comes out of Mercury, Mercury Reader is a powerful ally.

        Installation Instructions

        Install the module as you typically install modules (upload to /sites/all/modules, enable on the module configuration page.)

        Check module permissions to make sure the proper roles have access. The permission options include:

        • Administer Mercury Reader — A permission for users with a "Super Administrator" role (i.e., a role with access to advanced site configurations)
        • Manage Mercury Nodes — A permission for users with an "Editor" role (i.e., a user who does typical content management tasks)

        Next, either select an existing content type to serve as your "Mercury" content type, or create a new content type, and select the checkbox under Mercury settings of the content type's configuration settings.

        Create a new node of your Mercury content type, and provide the Feed ID number for your Mercury feed in the Mercury settings field set. You can also specify how many items to display from your feed. The Feed ID number for your feed is part of the URL for your feed in Mercury (i.e., for the URL http://hg.gatech.edu/node/1234 the feed ID would be "1234.") Save the node and you should now see Mercury items from your feed appear the body of the node.

        Mercury Reader Common Issues

        Mercury Reader Common Issues esembrat3 Fri, 02/22/2013 - 08:36
        Drupal Version
        Tags

        This page details common issues that are encountered with the Mercury (Hg Reader) module.

        Images Not Showing for Events on my Site

        If you are using the Mercury Reader (hg_reader) module on your site, then it is currently designed to display images for news items, but not for events. To change this, you'll need to edit the feed template (hg_feed.tpl.php).

        Theming Mercury

        Theming Mercury
        Category
        afrank30 Tue, 03/03/2015 - 11:56
        Drupal Version
        Tags

        Mercury Reader's out-of-the-box appearance can be customized to meet your unit's needs.  The sub-sections below describe different ways of custom theming Mercury blocks and pages on your Drupal 7 site.


        Mercury Theming Sub-Topics

        Editing Existing Mercury Reader Theme Files

        Editing Existing Mercury Reader Theme Files
        Category
        esembrat3 Fri, 02/22/2013 - 08:31
        Drupal Version
        Tags

        This page documents how to customize your Mercury feeds using changes to your local theming files, which are identified by the file-type ".tpl.php".  Both full item pages (/hg/item/item-ID) and feed lists in blocks and pages can be custom themed.

        To override the templates listed below, make a duplicate of the desired template in your local theme directory (usually located at sites/all/themes/YOURTHEME/templates), and modify as you see fit. Template-specific documentation is included in the templates themselves. Be sure to convert underscores to hyphens in your templates (use hg-feed.tpl.php instead of hg_feed.tpl.php.)

        There are three templates included in Mercury Reader:

        1. hg_feed.tpl.php - Controls the appearance of a feed
        2. hg_item.tpl.php - Controls the appearance of full item displays
        3. hg_media.tpl.php - Controls the appearance of the related media box shown on item pages.

        Custom Theming Examples

        Removing Images From All News Lists

        You could copy the hg_feed.tpl.php file to your theme's templates directory, and then alter the markup so that no thumbnail images are included in a list of news. This would change all lists of news in every Mercury block, or Mercury node on your site.

        Removing Images From a Specific List of News

        To do this, you'll need to first create a template file that corresponds to a class provided in the "Feed Classes" field that you added to your Mercury block, or Mercury node. For example, if you added the class "newslist," you'd need to copy the hg_feed.tpl.php file to your theme's templates folder, and then rename it hg-feed--newslist.tpl.php (note the use of hyphens instead of underscores in the template file.) You could then alter the hg-feed--newslist.tpl.php file to suit your needs, and any Mercury block or Mercury node that has the "newslist" class listed in its Feed Classes field will display its content based on the markup of the hg-feed--newslist.tpl.php file.

        Note: currently if you want to have a multi-word class in your Feed Classes list you'll need to use underscores instead of hyphens for the class, but be sure to stick with hyphens for the template file. This will be fixed in a future update to the Mercury Reader module.

        Restyling Mercury Feeds and Content With Only CSS

        If you don't want to mess with template files you can also just make use of the "Feed Classes" field to add CSS classes that will apply to a particular Mercury block or node, and then add your desired styling based on those classes to your subtheme's style sheets. All of the classes you add via the Feed Classes field will be output in the outer wrapper <div> of a Mercury feed, or item. For example, if you added "newslist" to the Feed Classes for a Mercury block, the outer <div> of that block would look like:

        <div class="hg-feed-wrapper newslist">

        Theming a Mercury Image

        Theming a Mercury Image
        Category
        afrank30 Tue, 03/03/2015 - 12:14
        Drupal Version
        Tags

        When using the Mercury Reader, you can reference an image attached to a news story or event and display it elsewhere in different sizes.  Please note, however, that the range of sizes available depends on the size of the image the story creator uploaded - if that person uploaded only a small image, you won't be able to get a larger version out of Mercury.

        You will first need to get the image node ID.  One way to do this is to right-click on the image on the story or event page, and open it in a separate tab or window.  Look at the URL of the resulting page - the long integer near the end of the URL is the ID number.  In the URL "/hg/file/41282/200xX_scale", the image node ID would be "41282".  The code after the integer (in this case, "200xX_scale") is the format of the image.  If you want to display this image somewhere else, but in a different size, just change that code to one of the other image style presets in Mercury

        Of course, this doesn't help if you wanted to change the display of the image when it is displayed in a node dynamically generated by Mercury Reader (when you are using just the reader, without making local copies of your news stories and/or events.)  If you want to change the default display of images in Mercury Reader's dynamically generated nodes, you'll have to create a custom template.  Here is an example of code you could use to make all images appear in the "200xX_scale" format:

        <img src="/hg/file/<?php print render($items[0]); ?>/200xX_scale" alt="<?php print($element['#object']->title); ?>" class="<?php print render($classes); ?> field-name-myfield-image-file" />

        Image Style Options in Mercury

        Image Style Options in Mercury
        Category
        esembrat3 Fri, 02/22/2013 - 08:20
        Drupal Version
        Tags

        Below is a list of preset image styles (mainly based on size) that you can use when theming Mercury items.

        • 100x133_scale_crop
        • 100x75_scale_crop
        • 100xX_scale​
        • 150x112_scale_crop​
        • 150x150_scale_crop​
        • 150x200_scale_crop​
        • 150x84_scale_crop​
        • 150xX_scale​
        • 1920x700_scale_crop​
        • 200x150_scale_crop​
        • 200xX_scale
        • 250xX_scale​
        • 300x400_scale_crop​
        • 400x225_scale_crop​
        • 400x300_scale_crop​
        • 400xX_scale​
        • 40x40_scale_crop​
        • 40xX_scale
        • 600xX_scale​
        • 80x80_scale_crop​
        • 80xX_scale
        • 860xX_scale

        Using the Mercury Reader API Functions

        Using the Mercury Reader API Functions
        Category
        afrank30 Tue, 03/03/2015 - 11:46
        Drupal Version
        Tags

        Module developers can utilize API functions within the Mercury Reader module to fetch data and files (including images) from the Mercury server.  This would allow you to write a custom module to format that data for your users without having to recreate all of the code needed to interface with the Mercury server.  All of the hg_reader API functions can be found in the hg_reader.api.php file, and some of the more useful ones are documented below:

        The "hg_reader_get_file" Function

        To fetch files (including images) from Mercury, we'll be using the hg_reader_get_file function (found in the hg_reader.api.php file). You must pass it three parameters:

        1. type: is this an 'image' or a 'file'?
        2. int: the unique Mercury ID number for the image/file that you are displaying (sometimes called the node ID)
        3. option: only required for images, where you can enter one of the preset image style options.

        Why Use hg_reader_get_file?

        Because hg_reader will cache the image as befits the friendly, fluffy little creature it is.

        What if I'm Not Using hg_reader to Retreive my Mercury News and Events?

        If you are pulling in Mercury content via Feeds and making local copies on your website, you can STILL use this function. All you need is to:

        • enable (turn on) the hg_reader module
        • create a Mercury block for each feed you are importing (you don't have to show these blocks on any pages: they are how you create a local hg cache that lets you leverage hg_reader's API)
        • make sure your import is capturing the node id number of those images (because you need an image's Mercury nid to use the above function)

        Example Code for Images

        In your template file for a field or content type, you can call an image in Mercury using this code like this:

        print hg_reader_get_file($type, $id, $option = 'original');

        Alternatively, to display a 200-pixel wide version of the image that accompanies your news item, you might use this code:

        print hg_reader_get_file('image', 232661, '200xX_scale'); 

        Function Code From API

        Below is the full code of the hg_reader_get_file function.

        function hg_reader_get_file($type, $id, $option = 'original') {
          switch ($type) {
            case 'image':
              // We still want to support the deprecated function signature.
              $format = (isset($_GET['f']) && $_GET['f']) ? check_plain($_GET['f']) : check_plain($option);
              echo hg_reader_file_helper($type, $id, $format);
              break;
            case 'file':
              $option = 'other';
              echo hg_reader_file_helper($type, $id, $option);
              break;
          }
        }

        Importing News and Events via Feeds Extensible Parsers

        Importing News and Events via Feeds Extensible Parsers
        Category
        esembrat3 Mon, 02/02/2015 - 13:49
        Drupal Version
        Tags

        Feeds Extensible Parsers is the module normally used to do XML and JSON imports of news and event data from the Mercury server.  (This module supersedes an older module called "Feed XPath Parser", which is no longer supported and should not be used.)

        Editor's Note:  While this method is being utilized by some units on campus, it can not be recommended due to the Feeds Extensible Parsers module still being in a beta release since April 2015, and not being covered by the Drupal organization's security advisory policy.  We strongly recommend that you try to utilize the built-in functionality of the Mercury Reader Module whenever possible, and only use Feeds Extensible Parsers as a last resort.

        Setting Up Feeds Extensible Parsers

        1. Install CTools and Job Scheduler (dependencies of "Feeds")
        2. Install the Feeds module
        3. Install the Feeds Extensible Parsers module.
        4. Go to the Feed importers on the Structure administrative menu to create a new importer that you will use to map Mercury content to your local news/event content types.

        But, before you get started with building importers you’ll want to first set up your content types with fields that match the basic structure of Mercury news/events, such as adding fields for a summary, summary sentence, related links, boilerplate, etc. For fields that can have multiple values be sure to also configure your local node’s field to do the same (such as with related links, or keywords.)

        For images associated with a Mercury item you can either map/store the node ID of the image (which would then require using hg_reader functions for building the display of the images,) or download the image directly to your site 

        Feeds Settings

        Basic Settings

        If you prefer to create a content type to use as an importer, you can assign one under “Attach to content type,” or you can choose to “Use standalone form.” The standalone form usually works for most purposes. All standalone importers can be found at yoursite.com/import

        Periodic import - If you want imports to run automatically then choose an interval. For most cases it’s best to have it automatically import only twice a day, and then manually override it if you want something to show up sooner.

        All other setting can be left as is.

        Fetcher

        • Fetcher - Select HTTP Fetcher.
        • HTTP Fetcher Settings - Leave as is (don’t check either option)
        • Parser - Select XML XPath parser

        Processor

        • Processor - Skip down to Processor (we’ll return to XPath XML processor settings after mapping) and select the Node processor option.
        • Node Processor Settings - If you plan to add additional fields to your news/event nodes that are not populated from Mercury you’ll want to set it to update existing nodes. If you plan to only include Mercury content in your local nodes you can opt for Replace existing nodes, but most users stick with the Update existing option.

          For Text format it’s best to select an input format that allows most block-level HTML tags, or at least the same options that you see in the body field of Mercury items. Select your content type that you want to map Mercury content to, the default author of your local nodes (typically a site administrator), and an Expire setting if desired (usually this is left at Never).

        Mapping

        • Node Processor Mapping - Now you’ll want to add the mapping for the fields of your local news/event content type that you plan to populate with Mercury content. For each field select the “xpathparser” option, then a field from the target drop-down, and select the Add button. Note that you’ll need to select a field to serve as a unique target. For this choose the “GUID” option for the target, and you’ll later map this to the item’s Node ID in Mercury.

        XML Parser Settings

        Now that you’ve identified the fields to be mapped you need to provide an XPath value for each field.

        Enter “node” for the Context field.

        For each field that you’ve added you’ll want to provide the appropriate value based on the XML tags in Mercury’s feeds. So for instance with your title field you’d enter “title”, for the body field “body,” etc.

        For the “field_image” above note that it’s set to use the “image_full_path” value. This will return the full path to the image file on Mercury, and since it’s mapping to an image field in the local content type it will pull a copy of the image down to your server and store it with your local node. However, you can not map image titles or descriptions from the Mercury version to the additional fields available with an image field type (such as the alt text, description, etc.) So to display the full details of a related image it would be best to instead map the image’s “nid” value in Mercury and use hg_reader functions to build the display of the image in your local content type where you could add a title and description as intended by the original contributor. If you went this route you would need to provide the XPath value as: hg_media/item/nid

        The same could be done if you were to set up a field in your local node to store video files uploaded to Mercury. Note that these days most users are uploading YouTube IDs instead of the actual video file, but you would still want to build the display of the YouTube video via its Mercury “nid” value so that you could display the title and description as intended by the original contributor.

        For related files that are uploaded with a Mercury item you can map them as actual files and download them to your server (use the “full_path” value), but you will lose the option of including the title provided for the file.

        You may instead choose to set up related files as a “link” field type in your local node so that you can include the provided title of the file. The Feeds module will allow mapping for both the title and link values of link fields (link fields are provided by the link module: drupal.org/project/link)

        Alternatively, you could set up separate media content types in your local site and map all media from your news and event feeds, but it’s preferred that you leverage the hg_reader functions as much as possible to display Mercury content.

        Note the “@id” entered for the “guid” field above. This is referring to the node ID that’s published in the XML feed as an attribute of the node element in the XML tree (i.e., ). This is stored as a unique value for your local news/event node and will help prevent duplicates being imported to your site (check out W3schools.com for more on the Xpath syntax: http://www.w3schools.com/xpath/)

        However, note that it’s only unique to the importer, so if you have two importers set up for two different Mercury feeds and an item is added to both of those feeds it will still be duplicated on your site.

        You may want to also map the “changed date” (Xpath value = changed) to your local nodes to help Feeds identify when an item has been updated in Mercury.

        Once you’ve got your importer set up you can go to /import on your site to view all importers created, and initiate a pull from Mercury (as well as delete items pulled in from Mercury.)

        Fields

        Each one-to-one mapping within XPath is composed of a few common types:

        • String literals are marked by "Text". Best used for static values for a field.
        • @attribute selects attributes on a tag (such as href, class, id).
        • value/ selects a tag.

        Pictures / Images

        Full Import

        Note: If the website in question is using OIT Web Hosting, you may have to contact OIT Web Hosting support to enable curl_init()

        To retrieve photos (with metadata) imported, follow the directions below:

        1. Install the Mercury Reader (hg_reader) module.
        2. If you open up hg_reader.api.php, you can read all about the Mercury API. The function in question is this:
        function hg_reader_get_file($type, $id, $option = 'original')
        /**
         * This function fetches files (including images) from Mercury.
         *
         * @param string $type
         *   Either "image" or "file"
         * @param int $id
         *   Either a Mercury image node ID or a Mercury file ID (note that this corresponds to node/files/
         *   item/fid within a node's XML.
         * @param string $option
         *   For images, the name of the Mercury ImageCache preset desired.  For files, this option will be automatically set to "other."
         */

        So in your own theme template file, if you insert:

        print hg_reader_get_file('image', 232661, '200xX_scale');

        You'll get a 200-pixel wide image of the chair of the physics department. Furthermore, hg_reader will cache the image as befits the friendly, fluffy little creature it is.

        XPath Import

        Another option is to simply import the image path URL using XPATH and the XML.

        • concat("http://hg.gatech.edu/",hg_media/item/image_path)

        Please note that this implementation may have firewall issues when viewing images from off-campus.

        For more information

        Forcing Updates in Mercury Reader

        Forcing Updates in Mercury Reader afrank30 Thu, 02/12/2015 - 09:14
        Drupal Version
        Tags

        Have you made a new event or updated one of your news items in Mercury, but those changes are not showing up on your website?

        This usually means you need to flush caches for Mercury on your site, forcing it to go check for the latest items and updated information.  Flushing caches just means wiping clean the temporary files Drupal produces to help speed up your website and rebuilding them with the latest settings, content, and configurations. You can learn more on drupal.org's article on clearing caches.

        You can flush caches two different ways:

        • Log into your site (NOTE: you may need Administrator privileges to complete the following steps)
        • Navigate to the Mercury block that is out of date, or to a news or event item's individual page
        • Select the grey button that says "Flush this item from the cache". You will find this link directly underneath the page title and above the body text on the page, as shown below.

        Configuring Mercury Reader Blocks

        Configuring Mercury Reader Blocks esembrat3 Fri, 02/22/2013 - 08:34
        Tags

        This page details the common ways that blocks are configured to take full advantage of Mercury's rich feature-set.

        Show only Current Events in a Block

        • When you create a feed in http://hg.gatech.edu/, be sure to set Event Start Date to the following:
          • "Is greater than or equal to"
          • "now"

        New events not showing?

        If you notice your front page's events are out of date, add “?clearcache=1” to the end of the URL in the address box of your browser, so you have http://MYSITE.gatech.edu/?clearcache=1.

        Selecting Specific Mercury Items in a Block

        Create a page or add a block, You will see a pair of boxes on the page edit form: "Feed ID," and "Maximum items." 

        • Feed ID: The feed ID is the five- or six-digit number shown in the URL when viewing a feed. You can find this within Mercury at http://hg.gatech.edu, for a feed that you or someone else has created. For example, the Georgia Tech homepage feed is available at http://hg.gatech.edu/node/42142, and the feed ID is 42142. You are not required to have a Mercury account to include feeds on your site. If you do not have an account and wish to display an existing feed, contact the administrator of that feed to get the ID number.
        • Maximum items: The maximum number of items you wish to display, or 0 for unlimited.

        When you save the page, you should see the feed items listed below the body copy, if there is any. Each title will link to the full item at /hg/item/item-ID.

        Re-order or Reverse events

        If you notice your block or page is showing events backwards, check the "Reverse sort" checkbox on the Mercury configuration form.

        Experimental and Deprecated Mercury Projects

        Experimental and Deprecated Mercury Projects klp Thu, 03/03/2016 - 17:59

        GT Calendar

        GT Calendar afrank30 Thu, 11/07/2013 - 10:13

        GT Calendar Configuration/Usage

        GT Calendar Configuration/Usage afrank30 Tue, 06/24/2014 - 15:11

        GT Calendar Installation

        GT Calendar Installation afrank30 Tue, 06/24/2014 - 14:18

        Tutorials, Guides, and Videos

        Tutorials, Guides, and Videos esembrat3 Mon, 10/27/2014 - 12:55
        Drupal Version
        Tags

        Drupal resources, tutorials, and documentation available online (both free and paid).

        Resources Free to the Georgia Tech Community

        Resources Available for Purchase

        • http://drupalize.me - Built by Lullabot, focused on being more detail-oriented.

        • http://buildamodule.com/ - Chris Shattuck's tutorials that focus on training, not developing.

        • Acquia - a prominent Drupal support agency - offers training sessions for module development, layout and theming, panels, and site building. (A 2-day module development course may cost $900, a 5-day site building and layout essentials course may be closer to $2,000).

        • OSTraining - a training company with an excellent reputation and offers on-site Drupal training sessions. They have a local office, could bring their experts to campus, and actively participate in the local development community.

        Conferences and Camps

        Conferences and Camps esembrat3 Tue, 09/03/2013 - 08:13

        This page lists conferences and smaller 'camp' sessions that members of our Drupal community often attend.

        There is also a more comprehensive list of web development related conferences on the Georgia Tech Webmasters website.


        Conference and Camp Listing

        Past Conferences

        Past Conferences klp Mon, 01/25/2016 - 12:39

        DrupalCon Austin - June 2014

        DrupalCon Austin - June 2014 esembrat3 Wed, 05/21/2014 - 15:17

        DrupalCon Austin 2014 - Around Town (Sightseeing and Food)

        DrupalCon Austin 2014 - Around Town (Sightseeing and Food)
        Category
        esembrat3 Wed, 05/21/2014 - 15:21

        As with every DrupalCon event, half of the excitement of being in a new city is taking in the sights and sounds between sessions and before/after the conference.

        Food & Drink

        Sights & Sounds

        DrupalCon Austin 2014 - Networking and Social Events

        DrupalCon Austin 2014 - Networking and Social Events
        Category
        esembrat3 Wed, 05/21/2014 - 15:23

        Chat with other Drupalistas, discuss the opportunities of working in higher education, and spread your Drupal knowledge near and far. 


        Activity Sub-Pages

        DrupalCon Austin 2014 - 06/03 PhaseOne Meetup

        DrupalCon Austin 2014 - 06/03 PhaseOne Meetup esembrat3 Thu, 05/29/2014 - 11:36

        We got an invite from Phase2 to a party they're throwing on Tuesday night.

        Details

        • Date: Tuesday, June 3rd 2014
        • Time: 9pm - onwards
        • Location: Container Bar

        Anyway, they said the more the merrier, so let me know if any of you want to go and I'll include you on the RSVP.

        DrupalCon Austin 2014 - 06/04 Education Industry Meetup (Sponsored by Acquia)

        DrupalCon Austin 2014 - 06/04 Education Industry Meetup (Sponsored by Acquia) esembrat3 Tue, 05/27/2014 - 09:00

        Join your peers on Wednesday, June 4th, 5:00pm - 6:30pm to network and learn how similar educational sector organizations are succeeding with Drupal 

        This event is free and you do not need a conference pass to attend.

        RSVP

        RSVP on the Acquia website.

        Location

        Brass House.

        DrupalCon Austin 2014 - 06/04 Forum One Meetup

        DrupalCon Austin 2014 - 06/04 Forum One Meetup
        Category
        esembrat3 Thu, 05/29/2014 - 11:30

        Drupal extraordinaire (and ex GT employee) Derek Moon ( http://forumone.com/staff/derek-moon/ ) has invited the GT Drupal community to an after-party hosted by his new comfy digs at Forum One.

        Details are below:

        Where: Brass House, 115 San Jacinto Blvd, Austin, TX 78701
        When: Wednesday June 4, 2014. 6-8 pm CDT
        Why: Live music, light food, and a free drink or two!

        I should note that Brass House is also the same place that the Acquia Education Networking event (also on Wednesday, 06/04, from 5-6:30pm) is being held. So stop by, knock two social events off in one go, and catch up with Derek!

        Should be a good warm up for Adelle's Board Game Night.

        Registration

        RSVP at EventBrite.

        DrupalCon Austin 2014 - Session Planning

        DrupalCon Austin 2014 - Session Planning
        Category
        esembrat3 Wed, 05/21/2014 - 15:19

        Having trouble selecting a session at DrupalCon? Can't decide between two? Help the GT Drupal community crowdsource the best sessions for GT Drupalistas to attend in Austin.  

        Tuesday Sessions

        Wednesday Sessions

        • More?

        Thursday Sessions

        DrupalCon Portland - May 2013

        DrupalCon Portland - May 2013
        Category
        afrank30 Wed, 03/13/2013 - 10:39

        This page details the Georgia Tech community efforts and plans for DrupalCon 2013 in Portland, Oregon.

        Plans at DrupalCon

        For those who may not have heard of DrupalCon, Drupal.org has an article: What is DrupalCon?

        DrupalCon 2013 Session Schedule (PDF

        Eating

        List of Restaurants (on Pinterest)

        Addendum from Eric H. on places to go...

        A volunteer at my wife's work (Habitat for Humanity) who recently moved here from Portland shared some great recommendations (below), plus a guide he and his wife put together for their out of town guests at their wedding.

        Coffee

        • Stumptown Annex on SE Belmont, free coffee cuppings (tastings) daily at 3:00
        • Water Ave Coffee,  SE Water Ave
        • Sterling Coffee, NW 21st
        • Barista, NE Alberta

        Beer

        • Cascade Brewing, SE Belmont, amazing sour beers
        • Green Dragon, SE Belmont, Crazy selection of beer
        • The Horse Brass, SE Belmont, Awesome selection of beer and the best halibut fish and chips anywhere
        • Gigantic Brewing, SE 26th Ave, Small out of the way micro brewery
        • 5th Quadrant, N Williams, Must try their Lompoc Strong Draft

        Food

        • Yoko's Sushi, SE Gladstone, Tiny neighborhood sushi joint, best sushi I've ever had
        • Toast, SE 52nd, Great breakfast, try the Badass Sandwich
        • The Woodsman Tavern, SE Division
        • Pok Pok, Thai food, SE Division
        • Little T's, SE Division, best bakery in town
        • Lardo, SE Hawthorne, crazy good sandwiches
        • Bunk Bar, SE Water Ave, awesome sandwiches
        • The Farm*, SE Burnside, great NW cuisine

        *I went to this restaurant when I was in Portland for WebVisions in '08 -- great place, and not a far cry from a true "Portlandia" experience.

        Approved Outside Web Development Vendors

        Approved Outside Web Development Vendors esembrat3 Thu, 01/08/2015 - 11:50
        Drupal Version

        The Georgia Tech Webmasters Resources site has the most up-to-date information on using Georgia Tech approved suppliers for Drupal web development on campus.

        Georgia Tech Drupal Handbook Editorial Guide

        Georgia Tech Drupal Handbook Editorial Guide

        The following guidelines have been established to provide as much consistency between articles in the handbook as possible.  In all cases, proper accessibility of all content is paramount.

        Page Titles

        Write page titles using the gerund ("-ing") format, like so:

        • Creating a New Page
        • Updating Drupal Site Modules
        • Installing Drupal on OIT Web Hosting

        Avoid personal pronouns whenever possible to put the focus on the technical content as opposed to the person who will be carrying out the procedures in the content.

        Headings

        Headings within articles should start with Heading 2 and sub-headings should follow in numerical order (3, 4, 5, 6).

        Headings should only be used when there is significant content that makes sense to be grouped under a descriptive heading.  Avoid using headings above a single line or two of content - something that short can likely stand on its own without a heading or be combined into another section of the page.

        Additionally, headings should only be used when there is more than one section of content under a parent section, as the purpose of headings is to identify sub-sections.  There is no need to use a heading to separate an introductory paragraph from a single block of main content - just insert a horizontal line (HR HTML tag) if you want a visual separation there.

        Tags

        Tags can no longer be added on-the-fly when adding or updating a page.  Instead, contact a site manager will if you think a new tag should be added to the tag taxonomy.  Managers should avoid adding tags that are synonyms for existing tags, as this dilutes the tagging system and can make it harder to find all related content, as inevitably multiple synonyms will never be added consistently to all related pages.

        For consistency's sake, tags should be in the plural whenever that makes sense (e.g. "user roles" instead of "user role").

        Syntax Formatting

        • Paths to administrative control panels should be given in both menu path and URL path format like so:

          Configuration -> Development -> Performance (/admin/config/development/performance)

          Note the use of bold on the menu path, and the "Program Code" format for the URL path.

        • Use the "Program Code"  format (AKA the "code" HTML tag) for anything that is PHP or shell script code, and use the "Formatted" format (AKA the "pre" HTML tag) along with "Program Code" when providing more than one line of code in an example.

        • Also use the "Program Code"  format for any filesystem paths or URL paths.

        • Use standard double quotes (") as the primary quote character (avoid stylized quotes), and the single quote (') as your secondary quote character.  Double quotes are easier to see and help users to spot important text being grouped by quotes.

        • Highlight in bold the names of buttons, fields, and other on-screen objects that users will be looking for when carrying out instructions.  Many users will want to quickly reference instructions while carrying out a procedure, and being able to visually parse out the key button, field, etc. names can greatly speed up this process.  Object names highlighted in bold do not need to be quoted as well, as the bold markup will effectively group those words together.

        Acronyms and Module Names

        With this handbook being a technical reference, many acronyms will inevitably be used.  Standard accessibility guidelines should be applied to all acronyms:  on the first usage, write out the full phrase or name and then give the acronym in parenthesis.  After that, you can then use just the acronym.

        Note: "GT" should always be spelled out as Georgia Tech, except in those rare cases where it is part of an official unit or product title.  For example, "GT Account Username" is an acceptable usage, as that is the official name for campus user accounts. 

        Similarly, when referencing modules, give the full human-readable name of the module followed by the machine name in parenthesis, like so, and on first use, make the human-readable name a link to the module's primary page (usually on the Drupal.org website):

          Entity Reference (entityreference)

        Note:  While it is common practice for Drupal module and theme names to not capitalize any word other than the first, for presentation's sake please use standard capitalization rules and capitalize all important words in a title.

        Proper Name Usage

        Please use the following forms for the given product or service names for consistency and clarity:

        • Drupal  (Always capitalize the "D")
        • OIT Web Hosting  (Don't leave off the "OIT" or condense to "webhosting")
        • GT Account Username  ("GT Account" can be used after the first occurrence in a section, but do not shorten to "GTAccount")
        • Mercury (Hg) Reader (Always include 'Mercury' spelled out in the name with 'Hg' in parenthesis)

        For Further Reference

        If you have any stylistic questions not addressed here, you can refer to the Georgia Tech Editorial Style Guide.

        root Wed, 07/12/2017 - 11:25