This README contains first-time dev setup instructions as well as a narrative section describing how to configure Drupal, through its GUI, to create the content types/views/etc as required to support development.
cerberus.snap.uaf.edu
To pull the latest code from the master
branch of this repository and recompile the Sass stylesheets, do this on your local machine:
ssh -t username@cerberus.snap.uaf.edu update_drupal.sh
Install Docker if you have not already.
Grab SNAP website files and database dump, save them to your ~/Downloads
folder. These directions assume these files are named snap.sql
and files-snap.bz2
respectively.
Clone this repository and extract the Drupal files into their proper location:
git clone https://github.com/ua-snap/snap-drupal.git
cd snap-drupal
# Put the database into a folder where it will be ingested.
mv ~/Downloads/snap.sql database/
# Add site files and proper settings for local dev.
tar -jxvf ~/Downloads/files-snap.bz2 --strip-components=1 -C files/
# Compile styles (see below for more details)
cd themes/snap_bootstrap && bower install && compass compile
# Launch containers and disable IP restrictions
# NOTE -- sometimes the name of the Docker image (snap-drupal_drupal_1) may be different.
# Use `docker ps` to find the right name of the image..
docker-compose up &
docker exec -i snap-drupal_drupal_1 php /usr/bin/drush.phar -y dis restrict_by_ip securepages
The Docker containers can be stopped at any time with the following command:
docker-compose stop
This is useful if you need to start the Docker containers for a different website.
Stopped Docker containers can be started with the following command:
docker-compose up
If something goes wrong with your Docker containers and you would like to go through the setup instructions again, you will first need to remove your existing Docker containers for the AK CSC website with the following commands.
docker-compose down --rmi all
Install Compass. Compass is used for the SASS development. Bower is needed to pull in some dependencies. Depending on your environment, you may need to install a few other things first.
The first time you compile the styles, do this (from your snap-drupal
folder):
cd themes/snap_bootstrap
bower install
compass compile
During normal development, it's easy to have Compass recompile when you make changes:
cd ~/docker/snap-www/sites/all/themes/snap_bootstrap
compass watch
Move "navigation" block to the "header" section of the site layout. Disable the title of the block by setting it to <none>
.
It turned out to be very important to install a particular version of the Media module (7.x-2.x-dev). The recommended release on the module's page is 7.x-1.4, but this version requires an old version of the File Entity module to work properly, and this older version of File Entity lacked the ability to set custom link labels in Media fields. So:
Download version 7.x-2.x-dev of the Media module here:
https://drupal.org/project/media
Download version 7.x-2.0-alpha3 of the File Entity module here:
https://drupal.org/project/file_entity
And download and install any other dependencies as needed.
Download the Date and Link modules from here:
https://drupal.org/project/date https://drupal.org/project/link
Extract them into the sites/all/modules directory and enable the following modules from the Modules page:
Date and Link will now be available field types when creating/editing a Drupal content type.
Remove the image button from CKEditor's Filtered HTML profile since the Filtered HTML input format by default is not able to embed images. From the Configuration page, go to:
CKEditor -> Profiles -> Filtered HTML -> edit -> Editor Appearance -> Toolbar
And move the image button from the "Used buttons" section down to the "Available buttons" section.
Backstory: Sometimes weird and problematic tags like this appear in the underlying HTML when editing text with the rich text editor (CKEditor): TEXT Apparently this is actually a problem with Webkit (and Google's fork of it, Blink) and CKEditor has hitherto left the problem unaddressed, expecting the browsers to clean up their own mess. A new version of CKEditor, 4.4.1, was released May 2014 that appeared to finally fix most of this problem with the rest to be fixed in their next release, 4.4.2. We installed 4.4.1 in May; 4.4.2 (full version) was installed July 2014.
Basic setup
Security: defaults
Editor appearance
Advanced content filter: enabled
Cleanup and output
CSS
Download IMCE module, extract it into sites/all/modules, and enable it from the Modules page. Then from the Configuration page, change the following settings:
CKEditor -> Profiles -> Full HTML -> edit -> File Browser Settings:
File browser type (Link dialog window): None File browser type (Image dialog window): IMCE File browser type (Flash dialog window): IMCE
IMCE -> Role-profile assignments:
administrator: User-1 authenticated user: User-1
Advanced options
config.allowedContent = true;
config.height = '500px';
Create a block-level view that displays all content of type Organization. Then, configure the view this way to get the logos displayed as links:
Then, you can add the block to the relevant page.
The home page overrides the theme default template, in templates/page--front.tpl.php
, and content that may be more dynamic is put into a block that is displayed in the "Content" section of the home page.
First, we need to add a new display mode for the Collaborator content type. Go to Structure → Content Types → Organizations → "Manage Display" tab → "Teaser" sub-tab (upper right). Move the Collaborator Logo to be displayed, and hide the other fields and the label. Set Format to "Image Link Formatter", click the settings gear and "Link image to" → "Website (field_website)".
Next, edit the Projects content type. Create a new field of type "entity reference", name "Collaborators", and when the screen pops up to configure that field, leave most things default but set the # of allowed values to (say) 10, choose type "Select List", and in the Entity Selection area, check "Organizations".
On the "Manage Display" tab, change the Collaborators field to "Rendered Entity", then click the settings gear on that row. Change the view mode to "Teaser" to match the configuration we did above, and uncheck "Display Links". Save.
Still in the "Manage Display" tab of Projects, create a new field group with label "Right Sidebar", label group_right_sidebar
and format "Div". Drag Image, Downloads, and Collaborators field under it (this is a bit slippery). Click the settings gear and change "Fieldgroup settings" to "Open", Effect to "None", "Show Label" to "No". Click Update, then Save.
Now we configure the "Teaser" view of the Project so it can be used on the page that lists all projects. Structure → Content Types → edit Projects → Manage Display tab → Teaser subtab button. Drag Project Image field above Description, change "Label" to Hidden, change format to Image Link formatter, click the settings gear, change "Link image to" Content, click Update then Save.
Finally, we create the view for the projects page. Go to Structure → Views → Add new view. View name "Projects", show content of type Project sorted by title, uncheck "Create a Page", check Create a Block, display format Teaser with links / without comments, 100 items per page, don't enable the pager. On the next configuration page, under the "Fields" section, verify that it shows both "Website" and "Collaborator Logo" fields; click the "Website" field and configure it to be "Hidden," save, then click the "Collaborator Logo" field and change the Formatter to "Image Link Formatter". Add it to the existing Projects page by going to the admin menu Structure → Blocks and drag the View: Projects block into the Content area; click to edit it and put <none> for the title, then change it to only display on page 'projects'. Save.
Community Charts is a standalone webapp that is set up to run from the modules
directory, though it's not a Drupal module—it's there so it's in our source control; implementing as a Drupal module would conflict with a number of existing libraries and would require some reworking of the source.
This non-module dwells in sites/all/modules/snap_community_charts
. All steps below need to be done on the relevant Drupal server/Vagrant instance.
etc/charts.sql.bz2
SQL dump into that user. Assign sufficient permissions to the user to allow read access from localhost.etc/Lato.zip
into the /usr/share/fonts
directory, then run fc-cache
to rebuild the font cache. Use fc-list
to verify that various Lato fonts have been installed.sudo yum install ImageMagick
Set up the taxonomy for staff categories. Main menu Structure > Taxonomy > Add Vocabulary. Name it "Staff Categories". Add 6 terms: Leaders, Faculty, Affiliated, Students, Staff, Alumni.
Go to Configuration > (People section) Account settings, then click on the "Manage Fields" tab at the upper-right. Note, those tabs may be hidden by the Shortcuts toolbar; if so, disable the Shortcuts module. Add a new field "Title", type Text, make it required & leave other settings default. Add new field "Biography", type Long Text, make it required, change text processing to "Filtered Text" and leave other settings default. Add a new field "Display Email", type Text, make it required and leave other settings default. Add new field "Staff Category", type Term Reference, widget default (check box/etc); on next screen, configure field to Vocabulary Staff Categories; make field required and default to Staff for convenience; leave other settings default.
Switch to the "Manage Display" tab, ensure Title, Biography and Display Email are visible, and move the History and Staff Category blocks to Hidden. Switch all labels to "Hidden." Save.
Now we create block views for each staff category. For each staff category: Structure > Views > Create View. Title "Staff Category - [category name]", ex. "Staff Category Leadership". Show: "Users" sorted by "Unsorted"; create a block, not a page. Save & Continue editing. Configure the view this way:
1. Title: set to [staff category], ex. Leadership.
2. Filter Criteria > Add > User: Staff Category > Apply > Selection type Dropdown > Continue > Operator Is One Of, pick [staff category name], ex. Leadership, do not expose filter to visitors, Apply.
3. Fields > Add > User: Picture > Apply. Uncheck "Create a Label," leave other things default. Apply.
4. Fields > Add widget, select Rearrange > drag Picture to be above Name. Apply.
5. Save the view.
6. Rinse and repeat: create a view for each of the other 4 staff category types (Faculty, Students, Staff, Alumni).
7. Once all 5 new views have been created: Structure > Blocks > move View: Staff Category [category] (all 5 of them) to Content block, Save Blocks then click Configure for that block, Block title: [category], Show Block On Specific Pages -- only the listed page: [target page for people], Content types / Show block for specific content types, choose people.
Manage Fields tab:
Manage display tab, Default mode:
Manage display tab, Teaser mode:
Views Slideshow provides a View style that displays rows as a jQuery slideshow. This is an API and requires Views Slideshow Cycle or another module that supports the API.
Related installs/dependencies:
Views Slideshow: Cycle. Adds a Rotating slideshow mode to Views Slideshow. Requires the jQuery Cycle Plugin, available at [http://malsup.com/jquery/cycle/download.html] - you will be prompted to install this plugin if you try to enable Views Slideshow: Cycle; instructions are given in the Drupal prompt/warning window.
Libraries: Required for Views Slideshow: Cycle and houses the jQuery Cycle plugin.
View: Featured Projects settings Display as Block Title: Featured Projects Fields:
Provides configurable blocks of menu trees starting with any level of any menu. Access through Structure > Blocks > Add Menu Block. Help for configuration can be found at /admin/help/menu_block
Example given for the Projects/UAS-RITA project:
The Lightbox2 module is a simple, unobtrusive script used to overlay images on the current page.
External Links is a small module used to differentiate between internal and external links. Using jQuery, it will find all external links on a page and add an external icon indicating it will take you offsite or a mail icon for mailto: links.
This module allows you to move the "Read more" link from the node's links area to the end of the teaser text.
Provides a caption for images from the alt or title attribute using jQuery. This module uses whatever text a content creator puts in the "Title" field for the image. So you just have to make sure "Enable Title field" is checked for the image field you use. Then you go into the jCaption configuration settings to add the selectors you want to be captionized. jQuery handles the rest.
Content types that have Image fields include Article, Organizations, and Projects. HOWEVER we don't want captions to appear for Organization logos, so disable Alt and Title fields for the logos in the Organizations content type (Collaborator logo element).
Minify is designed to improve the website performance. This module provides the mechanism to render the page using minified version of HTML and JavaScript files. Minified HTML is generated using regular expression, and JavaScript files are generated using GOOGLE Closure Compiler webservice. Minify also works perfectly with Boost module.
AdvAgg allows you to improve the frontend performance of your site and get better PageSpeed results from Google Analytics. Several modules to enable after install; enable all of them except Async Font Loader (site does not use external fonts).
To allow Apache to use the .htaccess file that comes with Drupal, change the following line in Apache's httpd.conf file inside the <Directory "/var/www/snap"> section:
AllowOverride All
To:
AllowOverride None
Then restart Apache so this change takes effect:
sudo service httpd restart
Clean URLs will not work unless the "AllowOverride All" directive has been set in the Apache configuration file. Refer to the Apache Setup step for more details. You can confirm that clean URLs are working by going to a Drupal page WITHOUT "?q=" in the URL. E.g.:
http://cerberus.snap.uaf.edu/about
Also, you must create a symbolic link to the .htaccess file found in this Git repo like below:
cd /path/to/drupal/
ln -s /path/to/drupal/sites/all/misc/.htaccess .htaccess
After you have confirmed that you can access a page in this way, visit the following page WITHOUT "?q=" in the URL (or this won't work):
http://cerberus.snap.uaf.edu/admin/config/search/clean-urls
Check the "Enable clean URLs" box and click the "Save configuration" button. From now on, Drupal will use clean URLs by default.
Drupal comes with an .htaccess file in the Drupal root directory. Our repository starts in the /sites/all directory. So, to set up the .htaccess file for version control (used for redirects, for example), we copied Drupal's .htaccess file into the /sites/all/misc directory and replaced the original path with a symbolic link:
cd /var/www/snap
sudo -u drupal rm .htaccess
sudo -u drupal ln -s sites/all/misc/.htaccess
Change directories to the Apache document root:
cd /var/www
Backup website files to your home directory:
sudo cp -rp snap ~/snap_backup
Backup website database to your home directory:
mysqldump -u drupal -p snapdb -r ~/snap_backup.sql
The database password can be found in /var/www/snap/sites/default/settings.php
.
Remove "snap_old" directory from previous upgrade, if it exists:
sudo rm -fr /var/www/snap_old
Download the new Drupal core tar.gz file:
wget -O /tmp/drupalcore.tar.gz 'http://ftp.drupal.org/files/projects/drupal-7.##.tar.gz'
Make sure you are still in the /var/www directory before extracting the tar file. Files extracted directly into the /var/www directory will inherit the "httpd_sys_content_t" SELinux context. Apache will not be able to serve files without this context.
sudo tar zxvf /tmp/drupalcore.tar.gz
To make the rest of this documentation easier and less accident prone, change the extracted directory's name to remove the version number:
sudo mv /var/www/drupal-7.## /var/www/drupalcore
Change file ownership to the "drupal" user and group:
sudo chown -R drupal:drupal /var/www/drupalcore
Remove the "sites" directory that came with extracted files:
sudo -u drupal rm -fr /var/www/drupalcore/sites
Double check that nothing important was added to the .htaccess file in this Drupal core update:
diff /var/www/snap/.htaccess /var/www/drupalcore/.htaccess
If this diff reveals anything other than SNAP-specific additions, take note and investigate if we need to copy the changes into our custom .htaccess file. If no changes need to be copied, or after they have been copied, make sure to delete the new Drupal core's .htaccess file:
sudo -u drupal rm /var/www/drupalcore/.htaccess
This step will break the website if something goes wrong, so be very careful and make sure you are free of distractions. Think about this command carefully before performing it and have a backup plan ready. This step combines three small steps into one so they can run one after the other instantly, essentially eliminating any website downtime. First, we rename the old SNAP website directory to "snap_old". Second, we rename the new Drupal core directory to "snap". Third, we move the "sites" subdirectory out of "snap_old" and into "snap":
sudo mv snap snap_old && sudo mv drupalcore snap && sudo mv snap_old/sites snap/
If something goes wrong, remember you backed up the website files to your home directory in Step 1.
Set up symbolic links inside our new website directory:
cd /var/www/snap
sudo -u drupal ln -s sites/all/misc/.htaccess
sudo -u drupal ln -s /files
sudo -u drupal ln -s sites/all/themes/snap_bootstrap/snap.ico favicon.ico
sudo -u drupal ln -s /var/www/attachments /var/www/snap/attachments
Run the Drupal update script by accessing this URL from your web browser and clicking Continue, etc:
Clear all caches from here to make sure what you're seeing reflects the new Drupal files:
https://www.snap.uaf.edu/#overlay=admin/config/development/performance
If all went as planned, Drupal will report that it's using the new Drupal core on this page: