Navigation:
Documentation
Archive



Page Tree:

Child pages
  • How to build a site like Bamboo DiRT using the Drupal content management system

This wiki space contains archival documentation of Project Bamboo, April 2008 - March 2013.

Skip to end of metadata
Go to start of metadata

Bamboo DiRT is a directory-style site built using Drupal 7. Other than using Display Suite to modify the way each of the entries is displayed, and using Views to override the default search and taxonomy displays, it's fairly simple.

 

Installation

Use the standard Drupal installation profile.

Modules

Uncheck (disable) the core Toolbar module, whose functionality will be replaced by Administration Menu, and install and enable the following:

  • Standard modules (general-purpose modules that you're likely to install on most sites)
    • Administration menu: provides easy access to all areas of site administration and configuration
    • Administration menu toolbar style: replaces Toolbar
    • Chaos Tools: a prerequisite for Views
    • Views Content Panes: allows you to display Views within Panels
    • Link: provides a link field
    • Fieldgroup: allows you to group fields together, and display them in different ways (e.g. collapsible group of fields, tabs, etc.)
    • Node Reference: creates a field that can refer to nodes already in the database
    • References: enables Node Reference and User Reference
    • User Reference: creates a field that can refer to users
    • Pathauto: allows you to define patterns for nicer-looking URLs
    • Panels: lets you create pages that have sub-regions (e.g. columns)
    • Panel nodes: the sub-module of Panels that actually lets you create a node with regions
    • Token: prerequisite for Pathauto
    • Views: generates lists, tables, and other displays of the data in your database
    • Views UI: needed to create Views using the Drupal UI
    • Backup and Migrate
  • Specialty modules (modules that provide more specific functionality)
      • Display Suite: allows you to more heavily modify how node pages are displayed
      • Display Suite Extras
    • Display Suite Search
    • Display Suite UI
    • Image Caption Formatter: displays the contents of the image title field below an image
    • Noderefcreate: allows the user to refer to nodes that do not already exist when entering data into a node reference field, and creates those new nodes
    • Flag: enables one or more "flags" for nodes, users, and/or taxonomy terms (e.g. could be used to implement something like a "Facebook like" or "flag as inappropriate" toggle)
    • Autocomplete Widgets: provides an auto-complete option text fields in a content type
    • Automatic Nodetitles: automatically generates the Drupal title for a node; often configured to use values from other fields
    • Chosen: provides a more intuitive interface for multi-select lists
    • Entity API: required by Term Merge module
    • Link Checker: checks the site for broken links
    • Contact: allows project contact people and potential collaborators to get in touch with one another easily, without publishing email addresses
    • Real name: replaces the username with the user's actual name, wherever it appears (e.g. user profile, users' blog posts, etc)
    • CAPTCHA: implements a verification system to reduce spam bots' creating fake accounts
    • reCAPTCHA: add-on to the CAPTCHA module that implements the reCAPTCHA service
    • Mollom: another module that provides CAPTCHA-based and text analysis-based spam deterrence
    • Honeypot: adds a human-invisible field to forms and uses timestamps to deter spam
    • Libraries: prerequisite for a number of modules that depend on jQuery libraries to provide visual effects
    • Revision All: automatically saves changes to node contents as new revisions
    • ShareThis: adds a ShareThis widget to facilitate sharing on social media sites
    • Google Analytics: enables visitor tracking using the Google Analytics service.
    • Tagadelic: generates a tag cloud based on the terms in each of your taxonomies.
    • Taxonomy Manager: provides an interface for managing taxonomy terms, including bulk addition/deletion, rearranging hierarchies, etc.
    • Term Merge: allows you to clean up your taxonomies by merging dispreferred terms into the preferred variant (e.g. "Word Press" to "WordPress"). Particularly useful for free-tagging vocabularies.
    • Lightbox2: displays larger versions of images in an overlay
    • Superfish: provides nested menus that drop down when the user hovers over the parent term

Taxonomies

Create the following vocabularies (using the Administration menu, Structure > Taxonomy > Add vocabulary).

Categories

You'll need to pre-populate the Categories taxonomy with the terms you want to use to classify tools. For Bamboo DiRT, we wanted to be able to present the category information either using abstract categories (e.g. "annotation", in the interface where a user adds a tool) or using a task-based framing (e.g. "take notes/annotate resources", on the front page). After creating the Categories taxonomy, using the Administration menu, go toStructure > Taxonomy > Categories > Manage fields. Add a field named "Task", field type "Text", with widget "Text field". Now, when you add terms to the taxonomy, a field will be available for adding text for a corresponding task.

Cost

Bamboo DiRT uses a scale of 1-5 dollar signs to indicate tool cost. Each term in this taxonomy is one or more dollar signs, and includes a description of what quantity of what price range that translates to. For example, the description for the term $ indicates $26 - $50.

Developer

Tool developers exist in the database as taxonomy terms. Because the developer field in the tool content type is set up as a free-tagging field, all you have to do is create this taxonomy, and it will be populated as tools are added. 

License

Like "Developer", the "License" taxonomy was developed for use as a free-tagging field, to save us from having to do a survey of licenses used by digital research tool software. One consequence is that we had to do a fair amount of consolidation after the first few hundred tools were entered, to merge, for example, "GPL", "GNU GPL" and "GNU General Public License". Arguably, we've probably already captured most of the variation that we're likely to see, and we could eliminate the risk of further cleanup being needed by modifying the tool content type to treat the "License" taxonomy like the "Category" taxonomy. For the time being at least, it's still a free tagging vocabulary, because there would be greater administrative overhead in responding to requests to add new licenses to the list of options.

Tool status

For the most part, tool status could be indicated just as effectively using a text list field within the tool content type. The reason we chose to use a taxonomy was because of the term description field, which gives an opportunity to clarify what each of the status options means. The tool status taxonomy needs to be pre-populated with options, because it won't be configured as a free-tagging vocabulary.

Tags

If you used the standard Drupal installation, your site will already have a taxonomy called "Tags". You don't have to do any additional configuration, and you will be using it when you build the content type.

Content type

Bamboo DiRT makes limited use of the default "Basic page" and "Article" content type that come pre-configured with the standard Drupal installation, but the vast majority of the site's contents belong to the content type used to store information about research tools. For historical reasons (we originally were going to include listings for digital collections, too), the content type is called "Item" on Bamboo DiRT, but there's no reason not to call it something else.

  • Go to Structure > Content Types > Add content type
  • Name the content type however you like, and keep the other default settings (displaying author/date information, open comments).
  • Don't fill in anything yet under "Automatic title generation" (which appears if you've enabled the Automatic Nodetitles module) – first you need to add some fields, then come back to this page.
  • Hit Save and add fields at the bottom of the page, and add the fields as listed in the table below:

Fields

FieldField typeWidgetNotes
NameTextAutocomplete for existing field dataRequired field
StatusTerm referenceSelect listUses "Tool status" taxonomy
CategoriesTerm referenceSelect listUses "Categories" taxonomy, unlimited values
WebpageLinkLinkNo title
PlatformList (text)Check boxes/radio buttonsUnlimited values, don't forget to pre-populate with options
DeveloperTerm referenceAutocomplete term widget (tagging)Uses "Developer" taxonomy, unlimited values
CostList (text)Check boxes/radio buttonsUnlimited values, don't forget to pre-populate with options
Cost bracketTerm referenceCheck boxes/radio buttonsUses "Cost" taxonomy, unlimited values
LicenseTerm referenceAutocomplete term widget (tagging)Uses "License" taxonomy, unlimited values
DescriptionLong text and summaryText area with a summaryDefault body field
Depends onNode referenceAutocomplete text field with createContent types that can be referenced: Tool
TagsTerm referenceAutocomplete term widget (tagging)Uses "Tags" taxonomy, unlimited values

The fields above are by far the most commonly used ones, and might be the only ones you want to include when creating a similar site. Bamboo DiRT contains the following additional fields, which appear in a Horizontal tabs group (which you can create if you've enabled the Fieldgroup module) called "Additional information". This contains two Horizontal tab item sub-groups, which contain the fields themselves..

FieldField typeWidgetNotes
Additional informationHorizontal tabs groupN/A 
ScreenshotsHorizontal tab itemN/A 
ScreenshotImageImageEnable Title field
TechnicalHorizontal tab itemN/A 
DocumentationLinkLinkNo title
APILinkLinkNo title
Technical notesLong textText area (multiple rows) 

Once you've added and saved all the fields you want, go back to the Edit tab for your content type, to make a few additional configuration tweaks, as described below.

Automatic title generation

To reduce the number of duplicate entries, we use a combination of Autocomplete Widgets and Automatic Nodetitles. The "title" field that people see when they add an entry to the site isn't Drupal's Title field-- it's just a text entry field that uses an autocomplete widget to search for pre-existing nodes with the same title. Drupal's requirement that every node must provide some data for its Title field is met by Automatic Nodetitles.

If you've used the field configuration listed above for the title field that uses the autocomplete widget, select the Automatic Nodetitles option "Automatically generate the title and hide the title field", and under Pattern for title, enter

[node:field-name]

This results in a fairly sensible arrangement, where the data that users put into the visible title field is copied to Drupal's required Title field behind the scenes, without them having to enter the title twice. You could use any field data, or combination of field data, to appear in Drupal's required Title field – for example, if you want to highlight the tool status, you could enter

[node:field-name] ([node:field-status])

to get tool profiles with a title that looks like "AwesomeTool (beta)". That said, you probably don't want Drupal's required Title field to draw on data that changes (e.g. a tool going from beta to active). The configuration we use for our automatic URL aliases uses Drupal's Title field as part of the URL path, and the name of the tool should be stable over time.

Comment fields

One of the tabs at the top of the content type editing interface is for "Comment fields". By default, Drupal includes provides a title and body field for every comment (the title field can be turned off under "Comment settings" in the "Edit" tab), but in Drupal 7 you can create additional fields that will appear as part of the comment creation/editing form. Bamboo DiRT comments include the following three fields:

FieldField typeWidgetNotes
TypeList (text)Check boxes/radio buttonsOptions for comment type are "review", "tips" and "uses"
External linkLinkLinkNo title; used when the comment is being used to point to an external review or discussion of a tool.
VersionTextText fieldN/A

Pathauto

Go to Configuration > Search and metadata > URL aliases > Patterns. The default path used on DiRT is

[node:title]

The tool content type path is

resources/[node:title]

Flags

Go to Structure > Flags to set up the three "flags" associated with the tool content type, using the settings below. These are markers used to indicate that a tool is good for beginners (is either set to on or off for the tool), that a particular user uses the tool (can be set to on or off for each user), and that a tool is a duplicate entry (is either set to on or off for the tool).

Settings for all flags:

  • Flag access (flag/unflag): authenticated user
  • Bundles: Tool
  • Display options: Display link on node teaser, display link on node page
  • Link type: Javascript toggle
NameTitleGlobalFlag link textFlagged messageUnflag link textUnflagged message
beginnersGood for beginnersYesGood for beginnersYou've indicated that this resource is good for beginnersNot so good for beginnersYou've indicated that this resource is not so good for beginners
useUseNoI use this I don't use this  
duplicateDuplicateYesMark as duplicateYou have marked this as a duplicate entryUnmark as duplicateThis is no longer marked as a duplicate 

Views

Bamboo DiRT makes heavy use of the Views module, both to generate new content listings (e.g. a list of tool categories), and to override the way that Drupal displays its taxonomy terms. Views are also used in conjunction with the Display Suite module to display comments differently than Drupal does by default, and also to display the users who have contributed to a tool entry.

Views for use with Display Suite

Comment table

The comment table provides an alternate way of displaying comments associated with a particular tool.

  • View name: Comment table
  • Show Comments of type Categories
  • Check the box for creating a block:
    • Block title Comments
    • Display Table of fields
    • Items per page: 15, check "use a pager"

Continue and edit.

  • Under "Fields" (left column), remove "Comment: Title" and add the following fields:
    • Comment: External link; uncheck "create a label"
    • Comment: Comment; label "Link/comment"
    • Comment: Type
    • Comment: Author
    • Comment: Post date
  • Under "Format" (left column), click on "Settings" next to "Table":
    • Set "Author" (ascending) and "Post date" (descending) as sortable
    • Select "Post date" as the default sort
  • Toggle down "Advanced" in the far right column
  • Under "Contextual filters" (right column), add "Comment: Nid"; provide default value: Content ID from URL

Contributors

The contributors table shows every revision of the tool profile, along with the user who made the revision. 

  • View name: Contributors
  • Show Content revisions sorted by newest first
  • Check the box for creating a block:
    • Block title Contributors
    • Display Table of fields
    • Items per page: 100, check "use a pager"

Continue and edit.

  • Toggle down "Advanced" in the far right column
  • Under "Relationships" (right column), add "Content revision: User"; you don't need to customize any of the settings there.
  • Under "Fields" (left column), remove "Content revision: Title" and add the following fields:
    • User: Name; use relationship "revision user"; label "Contributor"
    • Content revision: updated date -- this should already be present in the View
  • Under "Format" (left column), click on "Settings" next to "Table":
    • Set "Contributor" (ascending) and "Post date" (descending) as sortable
    • Select "Post date" as the default sort
  • Toggle down "Advanced" in the far right column
  • Under "Contextual filters" (right column), add "Content: Nid"; use relationship "Get the actual content from a content revision"; provide default value: Content ID from URL

Prerequisites

This View shows other tools that require the tool that the user is currently looking at. For example, if the user looks at WordPress, this View will show WordPress plugins that are also listed as tools in the database.

  • View name: Prerequisites
  • Show Content of type Tool
  • Check the box for creating a block:
    • Block title Resources that use %1 (the value of "%1" will be set by the contextual filter that will be set up on the next screen)
    • Display Unformatted list of fields
    • Items per page: 15, check "use a pager"

Continue and edit.

  • Toggle down "Advanced" in the far right column
  • Under "Relationships", add "Content: Depends on", and check "Require this relationship"
  • Under "Contextual filters", add "Content: Depends on", provide default value, and select "Content ID from URL"
  • Under "Fields", add "Content: Categories", "Content: Tags" and "Content: Body"; uncheck the "Create a label" box for each of them.

Views that override default displays

Taxonomy term

This View already exists – you just have to enable it and then edit it. On the list of Views, scroll down until you see "Taxonomy term", and click "enable". When the page reloads, it will be available for you to edit like any View you created yourself.

  • Toggle down "Advanced" in the far right column
  • Under "Relationships" (right column), add "Flags: node flag counter"; enter identifier "use", and select the flag "Use".
  • Under "Relationships" (right column), add "Flags: node flag"; enter identifier "beginners", select the flag "Good for beginners" with "any user"
  • Under "Filter criteria" (left column), add "Content: Platform", check the "Expose this filter" button, and label it "Platform"
  • Under "Filter criteria" (left column), add "Content: Cost", check the "Expose this filter" button, and label it "Cost"
  • Under "Filter criteria" (left column), add "Content: Has taxonomy terms (with depth)". 
    • Select the vocabulary "Tags" and the selection type "Dropdown". 
    • Check the "Expose this filter" button, and label it "Mentioned at", then select a number of options from the list on the right (DiRT uses "DH Answers", "DHCS", "dh_developers", "HASTAC" and "ProfHacker"). 
    • Select "Limit list to selected items".
  • Under "Sort criteria" (left column), by default, there are two options: "Content: Sticky (desc)" and "Content: Post date (desc)". Remove both of them by clicking on each one, and hitting the "Remove" button".
  • Under "Sort criteria", add "Content: Title", expose it to visitors, and sort ascending.
  • Under "Sort criteria", add "Content revision: updated date", expose it to visitors, label it "Updated", and sort ascending.
  • Under "Sort criteria", add "Flags: flag counter", expose it to visitors, use the relationship "counter", label it "Most used", and sort ascending.
  • Under "Sort criteria", add "Content: comment count", expose it o visitors, label it "Most commented", and sort ascending.

Other Views

Categories

The categories view displays a bulleted list of taxonomy terms from the "Categories" vocabulary, with the number of tools in the category in parentheses.

  • View name: Categories
  • Show Taxonomy terms of type Categories
  • Check the box for creating a page:
    • Title Categories
    • Path categories
    • Display HTML list of fields
    • Items to display: 0 (this means display all items)
  • Check the box for including a menu link
    • Menu: Main menu > Tools
    • Link text: by Category

Continue and edit.

  • Toggle down "Advanced" in the far right column
  • Under "Relationships" (right column), add "Taxonomy term: Content using Categories"; you don't need to customize any of the settings there.
  • Under "Other" (right column), and click on "No" next to "Use aggregation". Check the box for aggregation that appears.
  • Under "Fields" (left column), add "Content: Nid"
    • Aggregation type: Count DISTINCT
    • Uncheck "create a label"
    • Set the "thousands marker" to none
    • Prefix: (
    • Suffix: )
  • Under "Format - Show" (left column), click on "Settings" (which should be next to "Fields")
    • Under "Inline fields", check both boxes ("Taxonomy term: Name" and "(field_categories) COUNT(DISTINCT Content: Nid)")

New and updated

This page displays the most recently added, and the most recently updated, tools.

  • View name: New & updated
  • Show Content of type Tool
  • Check the box for creating a page:
    • Title New & updated
    • Path new-updated
    • Display HTML list of titles (linked)
    • Items to display: 15
  • Check the box for including a menu link
    • Menu: Main menu > Tools
    • Link text: New & updated

Continue and edit.

  • Toggle down "Advanced" in the far right column
  • Under "Relationships" (right column), add "Content revision: user"
  • Under "Fields" (left column), add the following fields:
    • Content: Categories -- check the "exclude from display" box
    • Content: Title-- this should already be listed, but click it to check the "exclude from display" box
    • Global: Custom text-- in the text box, put in [title] for [field_categories]; NOTE: this will only work if the "Content: Categories" and "Content: Title" fields appear ABOVE "Global: Custom text" in the fields list
    • Content revision: updated date, choose a Custom date format, and put in j M Y
    • User: Name -- select the "revision user" relationship
  • Under "Format" (left column), click on the "Settings" next to "Fields". Check the boxes so that "Content revision: Updated date" and "(revision user) User: Name" appear inline (next to one another), and specify a separator (Bamboo DiRT uses a single hyphen)
  • Under "Sort criteria" (left column), delete "Content: post date" (if you click on it, there'll be a "remove" option at the bottom of the box that appears). Add "Content revision: updated date"

We had a request for an RSS feed, so people could keep an eye on new tools added to the directory. Here's how to add an RSS feed to the View, once you've built it.

  • Under "Displays" (at the very top of the View configuration screen), click "Add" and select "Feed".
  • Under "Feed settings" (center column), put in a path. Also, select the other manifestations of the View (e.g. pages, blocks, etc.) that the Feed will be "attached to"-- which amounts to an RSS icon appearing in the corner of the View's display.

Duplicates

The duplicates view is a list of entries that have been marked as duplicates. It is only visible to individuals on the curatorial/steering committee.

  • View name: Duplicates
  • Show Content of type Tool
  • Check the box for creating a page:
    • Title Duplicates
    • Path duplicates
    • Display Unformatted list of titles (linked)
    • Items to display: 0 (this means display all items)
  • Check the box for including a menu link
    • Menu: Board members
    • Link text: Duplicates

Continue and edit.

  • Toggle down "Advanced" in the far right column
  • Under "Relationships" (right column), add "Flags: node flag"
    • Flag: Duplicate
    • By: Any user
  • Under "Page Settings" (middle column), click on "Access restrictions: Permission" and change it to "Role", then select the roles you want to be able to access the page; Bamboo DiRT uses "board".

Edit comments

One side effect of using views to display comments, instead of Drupal's built-in comment display functionality, is that it removes the user's ability to edit their own comments. To make up for it, this View is available for authenticated users, and lists all the comments they've made, along with an edit link.

  • View name: Edit Comments
  • Show Comments
  • Check the box for creating a page:
    • Title Edit comments
    • Path comments/edit
    • Display Table of fields
    • Items to display: 0 (this means display all items)
  • Check the box for including a menu link
    • Menu: Main menu > Contribute
    • Link text: Edit your comments

Continue and edit.

  • Toggle down "Advanced" in the far right column
  • Under "Contextual filters" (right column), add "Comment: author uid"
    • Provide default value: User ID from logged-in user
  • Under "Field" (left column), add the following fields:
    • Comment: Post date
      • Change the label to "Date"
      • Choose a custom date format, and enter j M Y
    • Content: Title; choose the relationship "Content" and put in the label "Item"
    • Comment: Edit link; change the label to "Edit"
  • Under "Format" (left column), click on "Settings" for "Table"
    • Select "Date" (descending) as the default sort
    • Select "Date" (descending) and "Content (Item)" (ascending) as sortable

Display Suite

Display Suite provides you with more options for how to display nodes, beyond just toggling on/off labels, or hiding and showing fields. DiRT uses Display Suite to provide a tabbed interface for tool nodes. These tabs include fields from the node, and a couple of Views described above.

Adding fields to Display Suite

In order to have the Views available as options when configuring the node display, you have to add them as a Display Suite field. Go to Structure > Display suite > Fields > Add a block field.

  • Comment table
    • Label: Comment table
    • Entities: Node
    • Block: View: Comment table
    • Layout: Default
  • Contributors
    • Label: Contributors
    • Entities: Node
    • Block: View: Contributors
    • Layout: Default
  • Prerequisites (derivative resources)
    • Label: Derivative resources
    • Entities: Node
    • Block: View: Prerequisites
    • Layout: Default

Go to Structure > Display suite. Click on "Manage display" next to "Tool". At the bottom of the page, you'll see "Layout for tool in default" highlighted, and a drop-down list under "Select a layout". Using the drop-down list, choose "One column" (the first option under "display suite"). Save (at the very bottom of the page).

Once the page reloads, you'll see a lot of new fields appear, under the heading "Disabled". You'll need to add a few more, to pull in the Views you've created. In the bottom left corner of the screen, choose "Custom fields", then "Add a block field" for each of the following three blocks:

  • Comment table
    • Label: Comment table
    • Entities: Node
    • Block: View: Comment table
    • Layout: Default
  • Contributors
    • Label: Comment table
    • Entities: Node
    • Block: View: Contributors
    • Layout: Default
  • Prerequisites (derivative resources)
    • Label: Derivative resources
    • Entities: Node
    • Block: View: Prerequisites
    • Layout: Default

You'll also need to create a new group (using the "Add new group" field at the bottom of the list of disabled fields), and sub-groups:

LabelFormatStatus
DisplayHorizontal tabs group-
DescriptionHorizontal tab itemOpen
ScreenshotsHorizontal tab itemClosed
CommentsHorizontal tab itemClosed
TechnicalHorizontal tab itemClosed
Derivative resourcesHorizontal tab itemClosed
ContributorsHorizontal tab itemClosed

Now, assign all of the following items to the region "Content" (if it's not assigned already), and arrange the fields and groups in the following nested order, using drag-and-drop:

  • Title
  • Links
  • Display (group)
    • Description (group)
      • Status
      • Description
      • Webpage
      • Platform
      • Depends on
      • Developer
      • Cost
      • Cost bracket
      • License
      • Categories
      • Tags
    • Screenshots (group)
      • Screenshot
    • Comments (group)
      • Comment table (custom Views block)
    • Technical (group)
      • Documentation
      • API
      • Technical notes
    • Derivative resources (group)
      • Derivative resources (custom Views block)
    • Contributors (group)
      • Contributors (custom Views block)
  • No labels