search

ua-snap / snap-drupal

2 stars 0 forks source link

readme

SNAP Drupal

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.

Deploying updates to 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

Local development instance with Docker

Setup Docker containers

  1. Install Docker if you have not already.

  2. 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.

  3. 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

Stop Docker containers

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.

Start Docker containers

Stopped Docker containers can be started with the following command:

docker-compose up

Remove Docker containers

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

Compiling styles

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

Site structure and configuration notes

Navigation

Move "navigation" block to the "header" section of the site layout. Disable the title of the block by setting it to <none>.

Setting up Media module

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.

Setting up Date and Link modules

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.

Configuring CKEditor

Remove image button from Filtered HTML profile

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.

Update CKEditor (July 2014)

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.

Edit CKEditor Profile (full)

Basic setup

Security: defaults

Editor appearance

Advanced content filter: enabled

Cleanup and output

CSS

Setting up IMCE file browser module

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

Configuring Collaborators view

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.

Configuration of home page content/template

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.

Setting up Projects entity references

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" &#x2192 "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.

Setting up Community Charts

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.

  1. Database: In MySQL, create a new database and user, then load the etc/charts.sql.bz2 SQL dump into that user. Assign sufficient permissions to the user to allow read access from localhost.
  2. Fonts: Unpack and copy all the TrueType fonts from 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.
  3. Scratch and web-visible directories: create directory/directories that will be used for scratch space as well as the location that Apache will serve the generated files from. They can be the same directory.
  4. Make sure ImageMagick is installed for the chart export feature to work: sudo yum install ImageMagick
  5. Configuration. Copy the src/Config.php.example file and update the database configuration and the directory locations from the prior step.

Setting up People

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.

Setting up the Articles content type to enable publishing of Articles on the Home page

  1. In Structure > Content types, Edit tab, edit the Article content type:
    • Edit tab, lower left block:
    • Publishing options: uncheck "Published"
    • Display settings: Uncheck 'display author and date information"

Manage Fields tab:

Manage display tab, Default mode:

Manage display tab, Teaser mode:

Install Views Slideshow, Views Slideshow:Cycle, Libraries modules

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:

View: Featured Projects settings Display as Block Title: Featured Projects Fields:

Install Menu Block module

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:

Create menu block in Structure > Blocks:

Install and configure Lightbox2 module

The Lightbox2 module is a simple, unobtrusive script used to overlay images on the current page.

Edit Basic Page content type to work with Lightbox

Install and configure External links module

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.

Install and configure Read More module

This module allows you to move the "Read more" link from the node's links area to the end of the teaser text.

Configure jCaption module for image captions

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).

Install and configure Minify module

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.

Install and configure AdvAgg CSS/JS aggregation 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).

Production configuration notes

Apache Setup

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

Enabling Clean URLs

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.

Adding .htaccess file to Git repository

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

Drupal core upgrade (Production)

  1. Change directories to the Apache document root:

    cd /var/www

  2. Backup website files to your home directory:

    sudo cp -rp snap ~/snap_backup

  3. 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.

  4. Remove "snap_old" directory from previous upgrade, if it exists:

    sudo rm -fr /var/www/snap_old

  5. Download the new Drupal core tar.gz file:

    wget -O /tmp/drupalcore.tar.gz 'http://ftp.drupal.org/files/projects/drupal-7.##.tar.gz'

  6. 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

  7. Change file ownership to the "drupal" user and group:

    sudo chown -R drupal:drupal /var/www/drupalcore

  8. Remove the "sites" directory that came with extracted files:

    sudo -u drupal rm -fr /var/www/drupalcore/sites

  9. 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

  10. 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.

  11. 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

  12. Run the Drupal update script by accessing this URL from your web browser and clicking Continue, etc:

    https://www.snap.uaf.edu/update.php

  13. 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

  14. If all went as planned, Drupal will report that it's using the new Drupal core on this page:

    https://www.snap.uaf.edu/#overlay=admin/reports/updates