Editor Documentation for Buck Online Learning Platform Drupal Site

This is a basic guide for Buck content editors working with the OLP Drupal site that contains projects and resources. We'll cover how to get into the site, how to view all the content currently in the site, and how to add new content and edit existing content.

Logging In

You should see a "Log In" link in the upper right corner of the site (depending on how it's currently styled). If for some reason you don't see a login link, you can always access the login screen by going to the basic site URL and adding "/user/login" to the end (e.g., if the site is at https://example.com, you would go to https://examples.com/user/login).

Forgot password

If you've forgotten your password, you may click the Forgot password link, or visit the basic site URL with "/user/password" at the end (e.g., if the site is at https://example.com, you would go to https://examples.com/user/password). This will take you to a form where you input either your site username, or the email address associated with your account. The site will email you a reset password link: click this and put in a new password in the resulting form.

Basic concepts

Nodes and Views

Nodes: Drupal's basic unit of content is called a node. You can think of a node as equivalent to a single page on the site, although that's not a strict equivalency in all cases. Each blog post, article, project, etc., is a node. Nodes each have a unique numerical node id, or nid, which is how the system tracks content. If you know the node id for a specific piece of content, you can always access that node by going to "node/{nid}" (where {nid} is the numerical node id). However, to make the site more user-friendly and search-engine friendly, nodes are also assigned human-readable paths, like "/document/sample-document".

Views: To help users find the content they want, this site makes use of lots of Views. A view is essentially just a listing of content, organized by some logic that makes sense for a given context. For instance, the Announcements area on the home page is a listing of all content with the type "announcement," sorted by a date field, and limited to a certain number of results -- so older announcements won't be listed in this View. You won't be able to directly edit Views, but it will be helpful to understand what they are. The main resource and project listing pages are Views, with specific filters and facets, to help users find the project and resource nodes they want to visit.

Content types and fields

Content types: The site supports multiple types of content, each with some special qualities. When you're adding content (a node), you can choose whether you want to create a basic page, an announcement, a resource, or a project (as this project evolves, there will likely be more choices here). Once you create a node, it will always be the same content type, although most of its other properties can be edited, so make sure you're starting with the right type!

Fields: Each node has all its data stored in fields. Each separate content type has its own fields unique to that type -- a project has some project-specific fields like Driving Question and Consider Your Students, while a resource has its own special fields like Video Embed Code and Resource Type. Fields may be short or long text fields, numbers, date/time, files or images, links, or references to other Drupal entities (like other content, users, taxonomy terms, etc.).

Special fields: There are some built-in fields which pertain to all content types. One useful field you'll be working with a lot is "Status," which specifies if a piece of content is published or not. Unpublished content is visible to admins and editors, but not to regular users. Two related fields are available in Promotion options: "Sticky" and "Promoted." These are used in Views of content, to determine which should make it to the home page and which should sort to the top of lists.

Taxonomy

This site uses taxonomy extensively to help categorize and organize content. We have several different vocabularies, each with its own focus. For instance, the "resource type" vocabulary categorizes resources by whether they're videos, articles, rubrics, planning forms, etc. The "grade level" vocabulary specifies what grades a project is aimed at. "Tags" is a unique vocabulary that holds various descriptive words and phrases that are relevant to a given piece of content; what makes it unique is that you can easily add new tags while editing a piece of content.

The various options in a vocabulary are called terms. If you had a vocabulary called "Colors," the terms might be "red," "yellow," "blue," and "green." A given node will likely have terms from multiple vocabularies. Depending on how the fields are set up, it's possible to even have multiple terms from the same vocabulary: a project can be suitable for grades 3-5, so it would be associated with the terms "3rd", "4th," and "5th" from the "Grade Level" vocabulary.

Files/images

The site supports editor-uploaded files. Generally, a file on the site will be associated with a specific node. You might create a resource node, and upload an image and a PDF document, both of which are associated with that particular node. Images are just another type of file -- the difference is we display them on node pages, rather than offering them as downloadable links.

Content management

There are three main ways you can view content on the site. You can use the built-in Drupal content tool, which lets you view all content on the site, of any type, published or not. You can use the Resource Management view, which shows more detail about resources only, and allows you to perform some bulk operations on multiple resources at once. Or you can actually browse the site the way a user would see it. This last method will only show published content, but you can edit most pages by clicking the "Edit" tab that shows up on the page when you're logged in as an editor.

Drupal content screen

The default way of listing all the content on a Drupal site is with the Content screen (/admin/content, or just click the main Content link in the top menu). When this page opens, by default it will list all content on the site in a paged table, sorted in descending order by most recently edited. To help you narrow down this list to what you're looking for, several filters are available. You can search the title of the content (this is case-insensitive and supports partial matches, so "based" will return nodes with the title "Project-Based Learning"). You can also limit the results by content type, published status, and language (although we currently don't have non-English content).

Actions: There are some bulk operations available to editors and admins here. These are actions that can apply to multiple nodes at once. For instance, you might use filters to show unpublished Video nodes, and then select several of those to publish at once. Most of these actions are related to the "Published status", "Promoted to front page", and "Sticky" options for content. Just make sure you know what you're doing before you delete 50 nodes at once! There is no easy way to undo these operations.

To work with individual nodes from this screen, you may click the Title to view the node as a user would, or click the three dots under Operations, and choose Edit to jump directly to the node's edit page.

Also note that you can sort the listing of nodes by clicking on column headers. Clicking on Title will alphabetically sort by title, and clicking again will reverse-sort (Z to A).

Resource management dashboard

You can get to this from the top menu, under Content (Content -> Resource Management). This is a View developed specifically to help editors review and manage resources on the site. It's similar to the Drupal content screen, but it provides a little more information specific to resources, to make it easier to identify which content you're planning to modify. Another feature of this View is that you can select more than just the nodes on the current page. For instance, you could filter to only show Blogs, select all on the current page, and then click "Select all 655 results in this View" (or however many are available). This would let you perform a bulk operation on every single blog post, even though there are far more than would fit on a single page.

To just edit individual nodes from this screen, choose the Title to view the node, or click the "edit" link to jump directly to the node's edit page.

Also note that you can sort the listing of nodes by clicking on column headers. Clicking on Title will alphabetically sort by title, and clicking again will reverse-sort (Z to A).

Browsing the site

Sometimes it is helpful to review content from the user's perspective. Going to Resources or Projects in the top menu and choosing some filters will show you exactly what users will see. If you click into a node and notice that it needs to be updated, you can just click the Edit tab at the top of that node page. This will get you into the edit screen.

Adding and Editing content

Adding new content: We've talked about editing existing content, but how do you add new content? It's pretty straightforward: in the top menu, under Content, just go to Add Content, and choose the content type you'd like to add. Once you're in the edit screen, adding content is pretty much the same as editing existing content.

Editing existing content: It's easy to make sweeping changes through the 2 bulk operations screens detailed above -- you can unpublish 30 nodes at once, or make a handful of nodes "sticky" with a single operation. But more detailed edits will require going to a particular node's edit page, to make changes to text fields, files, taxonomy terms, and more. Generally this screen can be accessed from the tabs across the top of a node page.

Revisions

One thing to bear in mind is that the site is configured to capture each batch of edits you make to a node as a revision. This means there is a recorded edit history for each node, including changes you made to fields. You can compare differences between revisions, and roll back to an earlier one if necessary. When saving a node, you may optionally add a "revision log message" in the "Revisions" vertical tab near the Save button. To access existing revisions, look for the Revisions tab on any node.

Text fields

Short, unformatted text fields: These are pretty straightforward, in that they don't support any styles or HTML tags. Title fields (and "description" on resources) are a good example.

WYSIWYG long text fields: There are a lot more options for these. You'll get a small editor with a few styling commands: bold, italic, link, ordered and unordered lists, etc. There is also a source button, which shows what actual HTML markup is being entered into the field from these button pushes.

Important to note is the Text Format dropdown below each long text field. All text you enter into Drupal is "sanitized" -- we don't want people entering malicious code that damages the site, or unintentionally "fancy" code that breaks the style guides. So, Basic HTML just allows a few simple tags that should play nicely with the overall site design. If you do need more extensive control, though, you can switch to Full HTML mode. Not only does this give you more buttons to control your markup, it refrains from stripping out class names, embedded styles, and other advanced features you may want to use. So if you go into the Source mode and add some embedded styles, they'll actually show up for users. One thing to watch out for is that if you paste text from an RTF-aware source like Microsoft Word, you may be unintentionally pasting a lot of style information and hidden markup. In Basic mode none of this would be rendered for users, but in Full HTML mode, it will affect the presentation.

Images/files

Images and files may be uploaded into the appropriate fields for projects and resources. You may also remove a file from a node by clicking the Remove button next to the file in a node's edit screen. For images, you must include Alternative Text. This is text that's displayed when visually impaired users view the site with a screen reader. It is not required to add Title text for images.

Taxonomy terms (tags/categories)

Projects and resources are each associated with different vocabularies. For instance, resource type is only available for resources, while grade and subject terms are only available for projects. Tags (or keywords) is really the only shared vocabulary. To assign vocabulary terms to content, you'll be using two different types of field: for predefined vocabularies like Resource Type and Grade Level, you'll pick from a list of checkboxes. For open-ended vocabularies (Tags/Keywords), you'll have a text box where you can enter terms. If you start typing, you'll get a pick list of terms that contain the characters you've already typed (if you start typing "pro", you might see "Projects" and "Professional Development"). If you enter a term that doesn't already exist in the system, you'll be adding that term when you submit the node form -- so make sure you're not entering a slight variation of a term that already exists! Enter multiple terms delimited by commas. If a term in your list is a new one that will be created, it won't show a term ID, while existing terms will display the ID -- e.g., "Assessment (313)."