Editing in Drupal

Overview

This page gives basic guidelines on how to edit web pages in the Gubser Group Drupal environment.

Logging in

Step 1 is to log in. To do this, go to phy.princeton.edu/cas, and you will be asked for your Princeton username and password. If you are refused by CAS, please see Regina Savadge. Be careful when editing in Drupal, because as soon as you save changes they go live.

Once you are logged in, go to the page you want to edit (either by manually entering the URL or navigating to it). You should see "View", "Edit", and "Revisions" tabs.

When you're all done editing in Drupal, you can log out by clicking your username at the top of the page and selecting "Log Out". (If you need to see the standard site tools, click instead on "Manage" instead of on your username.)

Site tools

BEFORE you edit or create a page, familiarize yourself with these site tools.

  • Content. This tool is near the top of the page. It shows files and is searchable. For example, searching for Gubser brings up pages whose titles include Gubser. I don't see how to search the full text of pages.
  • Structure. This tool is next to Content. Clicking on it gives you a list of functionalities. Main menu is the one that seems to be most useful because it lets you revise menu structure. Be careful with this tool, because you can easily make a change that is visible site-wide!
  • View tab. This is the default tab shown when you're logged in, and it shows the content of the page as it will appear.
  • Edit tab. This is the tab that you use the most to change content.
  • Revisions tab. You can use this tab to compare the current version of the page with a past version, or revert to a past version.
  • Customize this page. This tool is near the bottom of the screen, and it helps when you want to make a more sophisticated layout or include an image gallery.
  • Change layout. This tool is also near the bottom of the screen, and you use it to create a custom layout if you don't want just one block of text plus an optional featured image.

Editing an existing page

Editing an existing page is pretty easy: Having logged in and navigated to it, you click on the "Edit" tab, click "Source" in the editing menu, and start typing. It's better to edit the source directly, because then you see the actual html and don't get tripped up by idiosyncrasies of the GUI, for instance the use of non-breaking spaces or the insertion of paragraphs consisting of a single non-breaking space. Only remember to enclose everything you do in the correct html tags: p tags for paragraphs, li tags for items, etc.

When you have finished editing, click "Save" near bottom right, and your changes go live immediately.

Above all, proofread what you write as soon as you save it! Going live with a mistake is no big deal, let's just try to catch those mistakes ASAP.

Creating a new page

At first glance this looks easy: Having logged in, you click on Add Content near the top of the page, select Basic Page, add a title, and start typing. BUT THERE IS A HIDDEN GOTCHA! By default, the page you create will be just a numbered node. For instance, this page is node/7261, and you can see the node number by hovering with your mouse over the "Edit" tab and looking at the bottom left corner of your browser window. If you leave a pages as just a node, then there is no obvious way to find it in future! So there are three additional CRUCIAL STEPS to making a new page:

  • After giving a title to your new page, check "Provide a menu link" to the right of the editing window. Your page title should be chosen so that it's a suitable link title. (So keep those titles short! 21 characters max.
  • Choose a Parent link. If you don't do this, your new page will be a top-level page available from the Department Home Page. Don't go more than two layers deep under Gubser Group. For example, gubser-group/little-book-of-string/chapter-1 is OK, but any deeper would not be.
  • Add a link to your new page to the Site map, and INCLUDE the NODE NUMBER, since if menu structure gets changed and you need to find your page, the node number is your best bet.

When creating the "Research" subpage, I encountered an unexpected problem: the gubser-group/research path already had an (unpublished) page associated to it. So the new "Research" page I created had a strange URL, gubser-group/research-0. The resolution was to delete both pages and then create a new one.

I have a couple of unsolved problems at this stage:

  • Subpages of Gubser Group sometimes didn't show up in the menu when I first created them. That problem seems to have solved itself; maybe the menu just takes some time to refresh?
  • There must be some method to list pages within a site that lets you figure out what pages are where, for instance what pages are children or descendants of the Gubser Group home page. How can we do this?

Custom layouts

Sometimes it's good to have a page with a custom layout. This is not for the faint of heart, and it may be that a table within a basic layout will serve your purpose sufficiently. Here's the procedure to put together a custom layout. Beware, the process seems to be a little unreliable, and you have to be ready to back up, delete everything you did, and try again until you get it right.

  • After creating the page as a Basic Page in the manner explained above, but before inputting any content, click "Change layout" and choose the layout you want. Click "Save as Custom" and you should be taken back to the main view of the page.
  • Click "Customize this page" and delete any existing panes. Click "Save" near the bottom. The point of this is to start with a totally clean slate. You should now be back to the main view of the page. You should see the title of the page, and then nothing at all below the "View" tab.
  • Click "Customize this page" and click on the plus sign to add a pane in one of the content areas. IMPORTANT: In this first step, choose the content area that's going to be edited the most often, because editing other content areas is going to be unobvious to Drupal beginners.
  • Click "Existing node" from the long list on the left side of the screen.
  • Enter the Node ID of the page you've just created. Check "Override title" and leave blank the text field that pops up. Set Build Mode to "Full Content". Click "Add" near upper right. This should bring you back to the "View" tab, and you then click "Save". You should now be back once again to the main view of the page, and you should see nothing at all below the "View" tab. If you failed to follow these steps precisely, you probably will see some unwanted repetition of the page title, and you have to go through the steps again of deleting any panes and making one in "Full Content" mode linked to the Node ID of the page you've created.
  • Now click the "Edit" tab and enter the main content into the text window. This content will appear in the pane you created in the previous step.
  • Now for the tricky part: You need to supply additional panes for your layout and populate them with content. The best way to go about this is to first create Basic Pages for each content area, give them some descriptive title (e.g. Gubser Group header pane) but DON'T provide a menu link or specify a parent page; instead you're going to pull them into your custom layout page. REMEMBER to record your node numbers and add them to the site map; otherwise there's no obvious way to find this page again!
  • Say you've got a Basic Page created that you want to pull into your custom layout. Go back to your custom layout page and click "Customize this page". Click on the plus sign in the content area you want to populate. Click on "Existing node", enter the node number of the Basic Page you want to pull content from, click on "Override title", leave blank the text field that pops up, set Build Mode to "Full Content", and click "Add". So, just like the earlier step of populating the main content field from the node of the custom layout page, except you're using a different numbered node. Continue as above by clicking "Save", and you should see your new content---without the descriptive title from the previous step.
  • A good point to note is that you don't have to populate every pane category in your layout. In particular, if a pane category like Header is full width, then having no panes in that category is no problem. This is not so true when a pane is partial width because then probably there will be a conspicuous blank space.

Adding images

The main options are an image gallery or a stand-alone image. Either way, you also need a way of preparing suitable images to specification.

Preparing suitable images

Good formats to use (though not the only one possible) are PNG and JPG.

  • If you start with vector graphics (e.g. most PDFs), try to stay with vector graphics as long as possible as you manipulate the image, since at the end you're going to bit-map it into PNG, and there's no reason to do that twice if you can help it.
  • Crop the image suitably; this can be done e.g. using macOS's Preview (command-K under Tools).
  • Overleaf > Projects19 > website > website.tex gives an example of how to use graphicx, TikZ, and the geometry package to read in an image, place it on a white background, mask it if you didn't crop perfectly, even combine images, rotate, shadow, etc., and then output a file which is (at least very close to) a desired aspect ratio, e.g. 8:3.
  • JPG and any other format that graphicx understands can be handled in the same way. Whitespace padding to obtain exactly the desired aspect ratio is particularly desirable, because otherwise Drupal seems to crop clumsily.
  • Once you run pdflatex on website.tex to get a PDF of the desired size and shape, Preview can save it as a PNG. (You may need to use Preview to delete other pages first, or print to PDF the page you want.)
  • If you are just inserting an image into a page (not an image gallery), you may be able to get away with using the image as is, or just bit-map it and go.

Image galleries

Here's how to create an image gallery

  • Click "Manage > Add Content".
  • Select "Image Gallery".
  • Under "Attach Media", click "Browse". Use the media browser to upload the first image to be featured in the image gallery.
  • Click "Next". Now enter the caption for each image, if possible with a link to the arXiv.org paper from which it came. Make sure to enter alternative text and title text for each image. Click "Save".
  • When you're ready, click "Publish" to add your image gallery to Drupal's available image galleries. Drupal will assign a node number to your image gallery. As always, record this node number in the site map!

When adding additional images to an existing gallery, most of the same steps apply. An important point to keep in mind is that any change to an image has to be saved twice: Once in the pop-up media browser, and then again in the image gallery view.

Image galleries can be added to an existing page as follows:

  • Click "Customize this page".
  • Click the plus sign to add a new pane.
  • Select "Image galleries" from the menu, choose between the available aspect ratios (8:3 and 16:9) and click "add".
  • Enter a title and select the image gallery to be displayed from the drop down menu. Click "add".
  • Place the pane in the desired location on the page and click "Save as Custom".

Stand-alone images

On the home page, I have a stand-alone image, inserted using the content editor, using the little mountain icon. I tried adding a clickable caption when I inserted the image, and this had an undesired side effect: A faint horizontal bar appeared below the caption. So I used no caption, and instead added a paragraph element containing the caption directly below the image.