DRAFT Working in the SF.gov CMS

Owned by Amy Martin
Last updated: Feb 21, 2024 by Sharon Huang
13 min read

https://docs.google.com/presentation/d/1zJaxBKnTZbDgH9b4J2139W_Sur67nOHzKmxOIdRUD10/edit?usp=sharing (Slides)

https://sfgovdt.jira.com/wiki/spaces/SFGOV/pages/3401744385

https://sfgovdt.jira.com/wiki/spaces/SFGOV/pages/3402498049

Logging in

Logging into the practice site is a little different from logging into SF.gov.

Once you are logged into SF.gov, as long as you’re in that same browser (for example, Chrome), you will have edit access to any SF.gov page you go to. I can open another tab and go to SF.gov, and I’ll see edit options.

You’ll get logged out after a certain amount of idle time–I always get logged out over the weekends–but you should be able to work on SF.gov all day once you’re logged in.

Governance

In a nutshell, “governance” on a website means “who works on what, and how.” There’s a lot to consider with website governance, and you’ll talk about it a lot within your department.

What if someone edits a page, and then it turns out they should not have?

  • You can undo those changes using revision history.

  • Click the Revisions tab

  • You can Revert to any previous version using these buttons.

Editing a page

Let’s say you’ve found a page that’s yours to edit, and you are ready to start.

We talk a lot about front end vs back end on websites. 

The front end is what you see live on the web:

The back end is the editor interface. It’s what you see when you click in to edit on the page.

  • Click Edit

It looks really different!

First, most of what you need is on the left side of the screen. The information on the right might come up later, but we don’t need to worry about it right now. You can click on the X to hide it and make your screen a little less cluttered.

You can see what Content type the page is in the upper left corner–right after the word “Edit.” 

This page is a Transaction.

This particular page doesn’t look exactly like the diagram here, but I can show you how the sections match up:

  • This is the Title and Description

  • This dark blue section is Need to know

  • Below that, this whole very long section on the left is What to do

  • And on the right, there are sidebars in light blue for Get Help and Related

  • This page does not include a Custom Section

  • There is also no “Why this transaction is good for San Francisco” section on this particular page.

  • At the very bottom, we see Departments related to this page.

  • Here is the Special Cases section

When you open an SF.gov page to edit, it will look different, but what you see will roughly correspond to the sections in that Content Type.

Let’s look at this page in the back end.

Going down the page, look for headings that correspond to sections. 

  • Here are Title and Description.

  • What to know before you start is the Need to know section. You can see Cost and Application deadline within it.

  • Next is what to do. This can be a long section, and you can see there are lots of things nested under the What To Do heading. We’ll come back to those. 

  • Under this Supporting Information heading, I see Special Cases and Custom Section.

  • Next, in Contact and Related Information, I can add Ways to Get Help (which are contact information),

  • And in Related, 

    • I can add the Related Departments that will display at the bottom of the page,

    • And then the SF.gov pages that will show in the Related sidebar.

    • In this Related section, you can only link to other pages on SF.gov. That’s because of the relational structure of the site, which is covered in SF.gov concepts and structure. I’ll talk a bit later about how to link to pages and websites that are not on SF.gov.

  • Here is Why is this transaction good for the community, the last unfilled section on the page.

You don’t have to do that anatomy exercise for every page you edit. I find it really useful when you’re getting started, or when you’re thinking “what am I even looking at?!”

It can also help you figure out where to find the part of your page you’re trying to edit when you’re looking at the super-different back end.

Now we’re going to look at the elements of an SF.gov page in the editor interface, and how to use each one.

Click into a text field

Next to Title and Description, there are text fields. Text fields are boxes where you can click and type.

These have some helpful information around them:

  • Character count. Titles can only be 65 characters long, and Descriptions can only be 110 characters. These counters keep track and tell you when to stop!

  • Asterisk for required content. Just like anywhere else on the internet, you have to put something into any fields that have this red asterisk, or you won’t be able to save your page.

  • Help text. This is tiny text under the element you’re working on that gives you advice. Sometimes I zoom in on the page to read it better!

We’ll skip Language–most of you won’t have the option to edit translations at first, so you won’t see this.

Collapsed fields

I can see that there’s text in this Cost section, and when I look at the live page, yup, there it is. But this isn’t a text field; I can’t click on it to edit. Why?

That’s because this is a Collapsed field. 

To edit it, I have to click on this button over here, Edit. 

When I do that, the collapsed field expands. There’s not only a text field, but a choice to make about the type of cost. 

When I’m done working in this section, I can Collapse it again.

Any time you see the Collapse button, you can squish that section closed, and it will save everything inside as is. It’s a handy thing to know when you’re working on a very full page.

Radio buttons

Let’s open this collapsed field up again.

Under Cost type, you have to choose one of these circular selectors–and you can only pick one, not more than one. This type of multiple choice element is called radio buttons.

Since this one is required (red asterisk), we have to pick one.

Text field with formatting (WYSIWYG editor)

Here’s a text field, but look! We can add some formatting here. It’s a text field with formatting, also known as a WYSIWYG editor–”What you see is what you get.” It’s called that because however you format your text in this box, that’s how it’s going to look on your website.

As you can see, your options for formatting are very limited in this text field. That’s because the end result is going to show up here [show heading], and there’s not a ton of variety you can put in this space–but you can use bullets or numbers, bold, and add links.

Again, when you finish in this section, you can Collapse it.

Add buttons

Let’s go to the next section on the page, What to do, to take a closer look at Add buttons in the SF.gov CMS. 

On a Transaction page, a What to do section includes a bunch of options for how a user gets that transaction done: online, by phone, in person, by email, by mail, or “Other,” which you can customize. Most Transaction pages use just a couple of these options. Here’s the Transaction to Get a birth certificate for someone over 3, which shows an online, in person, and by mail option.

Back to our example page–The author has focused on online options. Within that section, they’ve added multiple Steps and Callouts.

A Step looks like a section of text with a heading.

A Callout is this block with the light blue background and the i symbol. It’s meant for an alert, something the user must see before they do the transaction.

We know how to edit these now. But how did they add them in the first place?

There are buttons that let you Add Steps and Callouts. This button has a dropdown arrow to expand the options

  • Click Add and choose Step

  • Expand the dropdown. There are a lot of choices here too! That’s because these are the choices for ALL the options, not just online.

Let’s practice by adding an in-person option.

  • Click Add next to in person and choose Step

  • I’ll make this Step title “Apply in person”

  • Select Add address

  • To add an address, you can search in Existing addresses like this, but you can also add a new address.

  • Let’s save the page to see how it looks.

If you add a component, you have to either fill it out or remove it or you won’t be able to save the page.

Drag and drop to change order

People often ask about changing the order of sections. The major sections on pages cannot be reordered, however, inside those sections, you can reorder any elements that have this hamburger symbol next to them–like this.

Building relationships with other content in the CMS

You’ve heard by now that SF.gov is a relational CMS. Here’s where we start to see what that means. 

Relational content refers to anything on SF.gov that’s saved and shared for editors to pull up and reuse on their own pages. Relational content includes:

  • Any SF.gov page

  • Addresses

  • Images

  • Files, like PDFs

We can create relationships between our page and other content on SF.gov, and part of that content will display on our page.

Tagging other pages

Here’s another page element: a taggable field. It’s a text field, but there’s a little circle on the far right end.

When you start to type in a taggable field, it will auto-populate with pages available in the SF.gov CMS. Click on the title you want, and you’ll see a number in parentheses appear at the end of the title. When you see that, that means another page has been tagged. That creates a link to the other page.

The title and description for the linked page will display on your page.

Add an address

Addresses are one of the pieces of relational content on SF.gov. That means that when you enter an address into the SF.gov CMS, it’s saved and shared, and users can pull it up and use it on multiple pages. 

It also means that if you modify an address, the change will show up everywhere that address displays.

To add an address:

  • Click Add address

  • Use Existing address if you have entered an address before for your department or location

    • Look up your place

    • Select

    • Click Attach address

  • Use New address if you have never entered an address for your department or location

    • Fill out the fields

    • Click Save and attach address

To change an address:

  • Click Edit

  • You can either Remove or Edit the attached address

    • If you choose Edit, it will edit this address everywhere it display on SF.gov. Make sure the address is “yours” to change.

    • If you’re unsure or know the location isn’t “yours,” click Remove, then add a new address.

Add an image

I’m going to save this page and open another one because I want to show you how to add an image to a page.

You cannot add images to every page on SF.gov. This is because images increase load time for web pages, and for users on phones, they use more data too. SF.gov is for everyone, and that includes people whose devices load web pages slowly and who have limited data plans.

Images are addable on pages where an image can improve the user experience, rather than just being decorative. For example, images are required on Location pages, because those pages help people find a building.

To add an image:

We’ll use an image I’ve already selected for this page. 

Follow our Image guidance. Do not use images with text. 

  • Enter the name of the image

  • Click Choose File to find your image

    • This is a standard file picker. It will go to your computer and look at your files for the image. 

  • Add alternative text. This is for people using a screen reader. The screen reader will read the alt text to tell the person what the picture is. A picture without alt text excludes people who cannot see, so alt text is required.

  • If you know who took the photo, add that person’s name to Artist or photographer. You can enter a screen name if you’re using a photo from an online source and that’s all you have.

  • If you got the photo from a free online photo source, add a link to the original photo.

  • If you got the photo from Flickr Creative Commons, choose the Creative Commons license type from the dropdown menu. If you got it elsewhere, you can skip this. 

  • Click Save and attach image.

For more about using images on SF.gov:

Add a file

You can attach downloadable files, including PDFs, to some Content Types.

But before I show you how to do that, let’s talk about it.

Even when you put a PDF on a website, it doesn’t act the same as an HTML web page.

Why?

A simple way to say it is that web pages are coded to have a structure. Internet browsers can read that coding and respond to the structure of a web page. One thing that is possible because of that structure is that a screen reader can read the page to a person who can’t read it visually.

Most PDFs are not coded to have any structure. They are almost like images. You can add tags and make other changes to PDFs to give them structure, but at that point, you’re doing basically the same amount of work  (if not more!) you’d need to do to make that text into a web page.

What happens when a screen reader tries to read a PDF? Let’s watch this example.

Inaccessible PDF example read with screen reader

A person who is blind can read the web pages on your website, but they can’t probably read your PDFs. Not unless you do a lot of extra work to make each PDF accessible. 

In 2016, a blind person sued Domino’s Pizza for being inaccessible because they could not order a pizza from their website using a screen reader. The case went to the Supreme Court, which ruled against Domino’s in 2019, establishing the legal precedent that websites must be accessible per the Americans with Disabilities Act.

That said, we know that sometimes you’re between a rock and a hard place, and you need to post a PDF. 

One more accessible option is to do both. You can make a page that has the text of a PDF on it, and attach the PDF to that page. The Civil Service Commission has done this on their Rules pages.

Rule 114

Here is how to upload a PDF:

  • The page must have a Documents section. This might be within Resources. On a Transaction page, like this one: A document can be added as a Step in a place that makes sense, like the option to mail a form.

  • Click Attach a document

  • Add a title for the document. This should be a natural language title, not the file name, so a screen reader can read it.

  • Use the “Choose file” button and file picker to add your PDF.

  • You can skip the other fields, but it’s good to add a description–a short summary of what the document says.

  • I recommend adding a tag for your Department. It’s possible to look for files by Department, and it could help you find yours later.

  • Save and attach document

We also have a recorded training on PDFs on SF.gov.

Saving and pushing live

You can save a draft of your page at any time while you work on it. The public cannot see draft pages. 

Send link to draft page for approval

No one who’s not logged into SF.gov can see draft pages unless you give them a preview link. Here’s how you get a preview link:

  • After your draft page is saved, click the Preview links tab

  • Select English

  • Click Generate

  • Now, you can copy and paste this url and send it to anyone. They’ll be able to see it without needing any kind of login.

Drafts and more drafts

For a page that’s never been published, this dropdown menu will show Draft. Continuing to save in Draft will keep the page unpublished.

For a page that has been published, you can save a draft of changes you have made before pushing those changes live. Change the dropdown menu to Draft. Your page will still be Published and live, but the changes you’ve just made and saved won’t show for the public.

When you save a page and the dropdown menu says Published, the page and any changes you’ve made are live. Congrats! Your page is on the web!

Publishing

If you’re ready to push the page live–Publish it–change the dropdown from Draft to Published and Save.

Locking and unlocking pages

When you open a page in Edit, it is locked to you. No one else can edit the page unless you unlock the page or save it. 

Someone else can break your lock. That does mean any unsaved changes you had will be lost. Make sure you save or unlock your pages when you finish working on them.

If you open a page to work on it and see someone else has it locked, you should ask them if it’s ok to break their lock unless it’s been longer than a week. After that amount of time, it’s pretty safe to assume the other person just forgot they had the page open.

Revert to previous version

Let’s look at the Revisions tab near the top of the screen. 

Any time you save a change, no matter how small, to a page, that version of the page gets added to a list of versions you can see under the Revisions tab. 

You can restore any prior version of a page at any time by using the Revert button.

How do you know which version of a page you want?

Sometimes you just want to undo your most recent changes. If so, you can just restore the previous version of your page.

Leave revision notes

Another option, though, is to leave Revision Notes as you edit pages. 

  • Open the page in edit

  • Look at the top right of the screen. There’s a text field with the heading Revision log message.

  • When you edit a page, write a note here about what you changed.

  • Look at the Revisions tab. You’ll see that note next to the version where you made that change.

Create a new page

So, now you know an awful lot about editing existing pages. But what if you want to create a new page?

You have two choices.

Duplicate an existing page

You can duplicate, or copy, most page types on SF.gov, then replace the contents to make a new page. 

Here’s how to Duplicate a page:

  • Click the Duplicate tab

  • Edit Title and other fields

  • Save

Start from scratch

You will use all the same page elements to build a new page from scratch that you do to edit an existing one. The differences are:

  • You must choose a content type for your new page

  • You’ll start with all empty fields

  • You must make sure your page is connected to the rest of your site–that it’s not an “orphan page”

Again, we’re not going to cover choosing content types in this training, but here are the basics again:

Starting with all empty fields on your page might look different, but it’s still using the skills we’ve learned today–you’ll just do more adding than editing.

To learn more about connecting your page to the rest of your site, make sure you take the SF.gov concepts and structure training.