Editing Project:Observatory Users Manual (section)

==== How to create and manage an Info or Talk page ====
Here’s how to create an Info page (aka a Talk page) for Collaborative Research Articles and other content. This is a note to the public soliciting their input for a query on the text of an Article or other content. You will insert a placeholder first and fill it in immediately after.
 
===== How to insert an Info or Talk page into an Article or other main page content =====
 
====== Insert a blank placeholder pop-up icon in the Article ======
# In the Article/main page you’re editing’s Edit mode (Visual editing, not Source editing), put your cursor in the exact placement in the text where you want to insert the pencil icon and click.
# Click '''the Comment icon''' (a speech bubble with a plus sign inside) in the Edit top toolbar of the Visual Editor to insert a pencil icon where your cursor was left in the text.
# Click the blue '''Save changes''' button on the page.
#* You now have a placeholder with an empty pencil icon to fill out. It will appear red until you create an Info page for it (and won’t appear on a Public site page if left unfinished); after you create a page for it, it will turn black.
# '''Refresh''' your browser on the page (this is the easy solution if nothing happens when you click the icon in the next step).
# Go to the spot where the new red pencil icon is and hover over it. Click “'''Create'''” in the bottom left of the pop-up.
 
====== Create the Info or Talk page connected to the placeholder pop-up icon ======
Fill in the Info page form fields:
# '''Pop-Up Heading'''
#* This will appear as both the title of the Info page and the header in the top blue part of the pop-up on the Article page.
#* You can either select something preexisting from the dropdown menu (recommended; many Pop-Up Headings already exist), or create a new one that will be both used in your case and added as a dropdown option for others to use. This field works like the Tags field on Articles with typing and a dropdown menu, except that you can only have one selection in the field.
#*# You can start '''looking through preexisting options''' in one of two ways:
#*## Click in the text box and '''scroll through preexisting options alphabetically'''. This is unwieldy if you have a good keyword instead, but this will give you a general sense of preexisting options to choose from.
#*## Start '''typing a keyword''' that would be in the Pop-Up Heading in the text box (such as Citation, Fact-Check, Illustration, Map, Add a Section…).
#*# '''Click on the preexisting option that applies to your query in the dropdown menu.''' It will appear in the text box as a gray-background button. If you change your mind, replace it by clicking the x on the left side of the button (or clicking in the field, selecting all, and backspacing) and repeat the steps above to find something fitting.
#*# If no preexisting option applies to your query, you can '''create a new option''' by typing it in exactly as it should appear in the pop-up, and then clicking the new dropdown option directly below the text field. Note that your new Pop-Up Heading option will be available to you and all other Users after you Save the Info page.
#*#* Follow the rules of preexisting options: look at other Pop-Up Headings and follow their lead. Keep your new Pop-Up Heading short, and use [[Project:Style Guide/Editorial Process#Headline-Style Capitalization|headline-style capitalization and punctuation]]. (Unlike for Headlines, no verb is required for Pop-Up Headings.)
#*# After you’re done typing, '''click the dropdown menu item''' or hit enter; otherwise, your Pop-Up Heading will be lost if you click outside the field after typing something in, and the vague default (“Collaborative Research”) will be inserted instead.
#* If you leave this field blank before Saving the Info page form, the vague default (“Collaborative Research”) will be inserted instead. If you see “Collaborative Research” as the Pop-Up Heading/Info page title later, you can always go back in and Edit the Info page form to add the Pop-Up Heading later. You might want to search for “Collaborative Research” on a page’s See All Queries page to find accidentally blank Pop-Up Heading fields to fill in.
# '''Prompt Type'''
## This controls the text that appears in the white part/body text of the pop-up. It will not appear on the Info page. Keep it short (one or two short sentences). '''Think of it as a pop-up subheading.'''
## Choose from Manual or Predefined using the radio buttons.
### '''Manual:''' Select Manual, and then type your desired text into the text box that appears. You can use the Visual Editor if you want to include links or bold or italic formatting.
###* Remember: it’s a pop-up, so it should be short! You can put more detail in the Talk field.
###* '''Type in your Manual Prompt below:''' Summarize the Talk field (the full query text) in one or two short sentences here. If your Talk field contents above the <nowiki>{{CollabPost}}</nowiki>} template are short, you may copy them here, adapting the text for the context of only being visible in the pop-up on the Article page if necessary. For example:
###** Strip links, especially internal links to the Article page. It is recommended not to include any links in this field, or to keep them limited, in order to encourage researchers to open the query through the emphasized links of the Pop-Up Heading, right-facing arrow, or Open link.
###** Do not include any templates in this field (for example, <nowiki>{{CollabPost}}</nowiki> templates).
### '''Predefined:''' Click inside the dropdown text field that appears after selecting Predefined, below the text “Click to choose from the Predefined text options (hover to preview at right).” The available options will appear in the dropdown menu. Scroll through and hover over each one to see a preview at right of what will appear for each. If you pick one and want to preview others, click the x button or delete everything in the field and hover over the options (you may type to search).
# '''Quoted Text (this is a fragment of the original content for discussion; it is optional)'''
#* This is where you might copy-paste text from the Article page near the pop-up icon that’s relevant to the query. It has Visual Editor built in that should allow copy-pasting normally even with rich text like links and italics, but if there are more complicated rich text elements such as section headings and footnotes, you can copy the source code from the Article (we recommend changing Info page tags <nowiki>{{i|</nowiki><span style="color:#e83e8c;">UUID</span><nowiki>}}</nowiki> into interquery links <nowiki>[[Info:</nowiki><span style="color:#e83e8c;">UUID|visible text</span><nowiki>]]</nowiki> if any appear in your selection) and paste it into this form field in code mode.
# '''Talk'''
## This is where we put more information about what we are soliciting feedback about. You can use the Visual Editor for this field. It becomes the body of the Info page, so it can be as long and complex as you want.
##* One example of an Illustration Query that is a good sample to recreate is [[Info:5ec6f361-e25e-47ce-943d-cebf8c3d617d|this one]]. Note the use of interquery links <nowiki>[[Info:</nowiki><span style="color:#e83e8c;">UUID|visible text</span><nowiki>]]</nowiki><nowiki> rather than pop-ups {{i|</nowiki><span style="color:#e83e8c;">UUID</span><nowiki>}} on an Info page.</nowiki>
##* Remember, the Prompt field will not appear on the Info page (only the pop-up), so it is very common to repeat what was in the Prompt field here if you want the same text to appear in the pop-up as on the Info page.
## '''CollabPost''' (Info page button for Contact form)
### Every Info page needs to add the <nowiki>{{CollabPost}}</nowiki> template at the bottom (information on including more than one is explained with the following two asterisks*). This inserts a green-background ribbon with text and a button leading readers to a Contact page form to answer the question asked on that specific Info page.
### '''To insert a CollabPost template into the Info page Talk field:'''
#### Add a line break at the bottom of your Text field below the normal text. Click your cursor at the end where you want to insert the CollabPost line.
#### In the Visual Editor ribbon at the bottom of this field, click the '''envelope icon''' at right (two to the right of the “Cite” button or open-quotation mark icon). If you hover over it, it says “Collaborator form.”
#### The default CollabPost template text and button text will be inserted.
#### If you’d like to change the text to '''customize''' to your query:
##### Click anywhere in the green text/button part of the Talk field for a pop-up to appear.
##### Click the '''“Edit”''' button to open the template pop-up.
##### '''Filling in CollabPost template fields:'''
###### The defaults are generally fine, but if you make customizations, click “'''Apply changes'''” in the CollabPost template pop-up after making changes to any of the following three CollabPost template fields ('''Button text''', '''Prompt text''', and/or '''Hashtag'''). Then Save the page.
###### If you want to customize the button text, edit what is in the '''Button text''' field.
######* The default button (including if you remove all text here or never alter it) is to show “'''Reply'''” with an '''arrow'''.
###### If you want to customize the green text at left, edit what is in the '''Prompt text''' field.
######* The default green text (including if you remove all text here or never alter it) is: “'''Suggest an edit or addition for this query. Join the research!'''”
###### *'''Hashtag''' field (checkmark at left in the CollabPost template menu) is optional to check or change:
######* Do this only if you are using multiple CollabPosts on the same page or have some other reason to mark emails filled out via this form with your specific query:
######*# Check the Hashtag checkbox at left to indicate you will use it (uncheck it if you change your mind later).
######*# Fill in the newly appeared Hashtag field with a keyword/keywords (without spaces, punctuation, or special characters including #). (The default is “'''collaborativeresearch'''.”)
######* Note that Hashtags are visible to the public in the Collaborative Research Contact form (as readonly).
######* A Hashtag is a tool for Authors and editors to recognize the source of a query that led a reader to fill in the form. Imagine you have two occurrences of the CollabPost on the same page and need to know which one triggered the post. You can assign ''a'' to one occurrence and ''b'' to the other, making it easy to tell them apart when you receive an answer (you probably want to be specific and use keywords instead of letters). The Hashtag field is not suggested by default when using the “Insert”→“Template” menu in Visual Editor. You can simply leave it out if there is only one CollabPost on the page, or if the context that triggered the post is not important to you.
###You can insert multiple* CollabPost templates per Info page if you have more than one query on the page and want people to have more than one Contact form about each; see “Hashtag field” above if you insert more than one.
###You can always '''edit''' the contents of a CollabPost by editing the page (via “Edit with form” mode), then clicking anywhere in the green ribbon so “Template” pop-up appears, then clicking the “'''Edit'''” button.
# '''Save page'''
## Save your newly created Info page.
##* or: use the “Cancel” button to cancel your edits (this is only if you want to abandon your changes).
##** Note that if you click the “Cancel” button next to the “Save” button to abandon your edits, if nothing happens, that’s because you opened in a new tab and your browser doesn’t know what page to open with a “Back” button. Simply close the tab if you wish to cancel/abandon your edits in this case.
# You will '''automatically be redirected to the Info page you just created''', and on the Article page where the pencil icon appears, this pencil icon will automatically be updated to display as black instead of red, indicating it now links to your newly created Info page!
#* '''Refresh''' the Article page in your browser if the pop-up does not appear when you hover over the pencil icon (this is normal). You may need to use a keyboard shortcut for a hard refresh (ignoring the cache) rather than the browser refresh button for a soft refresh if refreshing multiple times does nothing. Keyboard shortcuts for hard refreshes are:
#*# Mac: command+shift+r
#*# PC: control+shift+r (OR control+F5)
 
===== How to edit the contents of an Info or Talk page =====
# You can go back in and edit the page if necessary at any time.
#* From the Article page: Click either “Open” or “Edit” in the bottom left of the pencil icon pop-up when viewing the Article page.
#* From the Talks report (“'''See All Queries'''”/the All Queries page) for any Article:
#*# Click “'''[open]'''” at right of any Info page item in the list to open its individual Info page.
#*# Click “Edit with form.”
#*#* When editing an Info page, usually you need “Edit with form” (especially if what you want to change is in the pencil icon pop-up text); use “Edit” or “Edit source” only for Info page edits requiring advanced code (such as to replace links).
#*#* In “Edit” and “Edit source” mode, please ignore/do not touch the Widget part of things that seems locked (those are better edited in the form)—just edit what’s in the text below the close–double curly brackets <span style="color:#e83e8c;"><nowiki>}}</nowiki></span>.
 
===== How to change the UUID of the Info or Talk page referenced in the Article body =====
If you need to change which Info page is linked to in a pop-up on the Article page…
# Open the Info page you want to replace the current one with.
## Click the gray “'''Copy UUID'''” button.
## A pop-up should appear confirming successful copying to your clipboard: “UUID copied to clipboard!”
## Click “'''OK'''” to close the pop-up.
# Open the Article page, click “Edit” to unlock “Visual Editing,” and then click on the pencil icon whose referenced Info page you want to change.
# A pop-up should appear that says “Template” and “Generated from: I.”
# Click the “'''Edit'''” button at the top right of this pop-up.
# In the '''field “UUID”''' delete the text that was there before (the old Info page UUID referenced) and paste in what was copied to your clipboard (the Info page UUID you want to change to).
# Click “'''Apply changes'''” at top right.
# Click “'''Save changes'''” on the Article page.
# '''Refresh''' your browser tab.
# The Info page pop-up should now link to the Info page you desire.
 
===== Deleting an Info or Talk page =====
If you need to delete an Info page that you abandoned and that should not be Published, ask an administrator. Send them the link to the old Info page and tell them that you’ve replaced it and that it should be deleted. (Before you do this, double-check you or others haven’t used it elsewhere! If you aren’t sure of this, ask your editor/administrator to check before they delete it.) It may be automatically Pushed if this is not done before the Article affiliated with the Info page is Published.
 
===== How to create an All Queries page =====
Once you have inserted all Info pop-up icon placeholders on the Article page or chapter subpage, you are ready to create the All Queries page. (You don’t need to fill in the Info page form fields yet.)
 
# On the Article page, hover over any Info pop-up icon. (If nothing happens, try a hard-refresh.)
# Click “See All Queries” at the bottom right of the pop-up. A new All Queries page Draft will open in a new tab.
#* All Info page UUIDs on the Article page are automatically copied to your clipboard. (To verify: paste into TextEdit or Notes—you should see a series of 32-character alphanumeric strings.)
#* Use a normal left-click; right-clicking to open in a new tab may not copy the UUIDs.
# Click “create this page” to open “Source editing” mode in a new tab.
# Paste the UUIDs from your clipboard below <span style="color:#e83e8c;"><nowiki>{{Queries|<!-- insert info uuids below --></nowiki></span> and above the closing <span style="color:#e83e8c;"><nowiki>}}</nowiki></span>.
# Click “Save page.”
#* The page will reload. The new URL (Queries:page UUID) is where queries for the Article will appear.
# After creating Info pages, hard-refresh the All Queries page to see Info pages with completed forms populate.
#* Uncreated Info pages will appear as errors on the Editorial site and will not appear on the Public site until they are created (and Pushed by an administrator).
 
Notes about what appears on All Queries pages:
 
* Info page form contents that appear on individual Info pages (as opposed to in Info pop-ups) are the same on All Queries pages:
** Pop-Up Heading
** Quoted Text (if any)
** Talk
** (Note: Prompt field contents do ''not'' appear on All Queries pages.)
* On All Queries pages, footnotes do not all appear at the bottom; instead, each footnote pops up only when a footnote numeral is clicked (see: [[Project:Observatory Users Manual#Pop-up bibliographical footnotes on All Queries pages: Copy-paste trick|Pop-up bibliographical footnotes on All Queries pages: Copy-paste trick]]).
 
====== Keep All Queries pages updated after edits to Info pages ======
If you add, delete, or replace Info pop-up icons on an Article page or chapter subpage that already has an All Queries page, you must manually update the UUIDs on that All Queries page—they won’t update automatically.
 
# On the edited Article, hover over any Info page pop-up. (Hard-refresh if nothing happens.)
# Click “See All Queries” at the bottom right of the pop-up. The current Info page UUIDs are automatically copied to your clipboard.
# On the All Queries page, click “Edit source.”
# Replace the old UUIDs with the updated UUIDs from your clipboard, below <span style="color:#e83e8c;"><nowiki>{{Queries|<!-- insert info uuids below --></nowiki></span> and above the closing <span style="color:#e83e8c;"><nowiki>}}</nowiki></span>.
# Click “Save page.”
# Check that the expected updates are reflected on the All Queries page.
 
====== About repeated Info pages: Multiple uses of the same UUID ======
'''Re-using UUIDs within a single Article'''
 
You may re-use an Info page UUID multiple times within an Article; for example, using the same UUID in a footnote citation, an in-text citation, and a bibliography section of the body text. If any instance requires unique content, use a different UUID and copy the relevant form field content. You can link between two Info pages so editors can check related entries together.
 
Note: If the same UUID appears multiple times on an Article page, only the first instance will appear on the All Queries page. (Two separate UUIDs with the same or similar content are a different case—both will appear.)
 
'''How to re-use Info page IDs within a single Article'''
# Open the Info page you want to re-use and copy its UUID (everything after Info: in the URL).
# Open the Article/chapter in “Edit” mode.
# Insert an Info page placeholder in the usual way.
# Click on the pencil icon.
# Click the “Edit” button in the pop-up.
# Replace the UUID in the form.
# Click “Apply changes.”
# Save the page.
'''Don’t re-use UUIDs across multiple Articles or chapters'''
 
We recommend '''not re-using the same UUID across multiple Article pages or chapter subpages'''. Because an individual Info page’s “Return to the Host Page” button links only to the page where the Info page was originally created, it won’t navigate back correctly. (For example, if an Info page is created in Chapter 2 and then re-used in Chapter 3, its “Return to the Host Page” button will always go to Chapter 2, even if it was accessed from Chapter 3.)
 
Instead, create new Info page placeholders with separate UUIDs and copy the relevant form field content into each. You can link between related Info pages so editors can check them together.
 
===== Pop-up bibliographical footnotes on All Queries pages: Copy-paste trick =====
Footnotes (bibliographical footnotes or other kinds of notes in footnotes) on “See All Queries”/All Queries pages work differently than on other kinds of pages: they open as pop-ups at the bottom of the page instead of triggering a jump page anchor link to an all-footnotes space (there is no all-footnotes space at the bottom of an All Queries page). This needs to happen for All Queries pages so that the various fields in individual Info pages displayed there don’t trigger <span style="color:#e83e8c;"><nowiki><references /></nowiki></span> that conflict with the numbered order of footnotes at the bottom of a page.
 
If you need to copy text from a pop-up footnote on an All Queries page, here’s how:
 
On a Mac:
 
# Click the footnote.
# Select the text, but before lifting your finger off the mouse at the end of your selection, add the control key (control+click over your selected text).
# A context menu should appear with the option to “Copy”; click “Copy.”
 
On a PC:
 
# Click the footnote.
# Highlight the text. The text will automatically be copied.
# To paste, use a middle click.
 
===== How to batch-Push Info or Talk pages, or All Queries pages, associated with any page (such as Collaborative Research Articles) =====
Since the Editorial and Public sites are separated, your editor has to Push Info pages and All Queries pages in a new Collaborative Research Article or other page with Info pages to make the Info pages Published or to make updates appear on the Public site. If you don’t see the Info pop-ups or pages you expect to on the Public site, kindly remind your editor they need to Push the Info page(s) as well. (In case they need further reminding, they have a “'''Copy Info pages for Pushing'''” dropdown item in their top menu “Admin” button to do it in a batch.)
 
===== Custom TOCs on Article pages: How to customize the table of contents in the sidebar =====
On Article pages/chapter subpages, you might want to add a line to the top of the sidebar’s TOC to point people to an All Queries page or an anchored link. The <nowiki>{{Custom TOC}}</nowiki> template adds special navigation links to the top of the Contents tab in the sidebar, above the section headings in the table of contents. A common use is to add links to All Queries or General Queries pages for any Article/page or chapter/subpage.
 
For example, [[The Creation of Order/Summer: Balancing Self-Expression With Group Order/4. Alphanumeric Notation and the Calendrical-Musical Kosmos|here in Chapter 4 of ''The Creation of Order'']], click the “Contents” tab in the sidebar to see the custom TOC links (under “Click on the following links to”) to jump to the Key Concepts part of the chapter page (“jump to a glossary of key concepts for this chapter”) or to open the All Queries or General Queries pages.
 
[[File:Custom TOC.png|alt=a screenshot showing a two-tab interface (Author / Contents), with the Contents tab active. It lists three clickable links: 1. Jump to a glossary of key concepts for this chapter 2. See general queries for this chapter, including its stub nature and possible areas of expansion, bibliographical notes, and illustration notes 3. See all other queries for this chapter|none|thumb|650x650px]]
 
To add a custom TOC, open the Article or chapter subpage in “Source editing” mode. Add the template at the top of the page:
 
:<nowiki>{{Custom TOC|[[</nowiki><span style="color:#e83e8c;">Page title goes here</span><nowiki>|</nowiki><span style="color:#e83e8c;"><nowiki>Text you want to display goes here.</nowiki></span><nowiki>]]}}</nowiki>
 
If you are linking to a Queries page, you would include the Queries: namespace before the UUID:
 
:<nowiki>{{Custom TOC|[[Queries:</nowiki><span style="color:#e83e8c;"><nowiki>UUID goes here</nowiki></span><nowiki>|</nowiki><span style="color:#e83e8c;"><nowiki>Click here to see all queries for this chapter.</nowiki></span><nowiki>]]}}</nowiki>
As with anywhere on the Observatory where you’d use a page title as an internal link:
 
* Include the namespace with a colon before the page title for any page outside the Mainspace (i.e., not an Article, Author, Source, or Guide), such as Classics, Project, Queries, Info, or Recipe pages.
* Include the path if it is a subpage (for example, a link to [[The Creation of Order/Summer: Balancing Self-Expression With Group Order/5. Music, Temperament, and Social Concord|Chapter 5 of ''The Creation of Order'']] would look like this: <span style="color:#e83e8c;"><nowiki>{{Custom TOC|[[The Creation of Order/Summer: Balancing Self-Expression With Group Order/5. Music, Temperament, and Social Concord|Click here to open Chapter 5.]]}}</nowiki></span>).
 
If you are linking to multiple pages in the custom TOC, you can add numbered or unnumbered bullet points and line breaks in between the <span style="color:#e83e8c;"><nowiki>{{Custom TOC|</nowiki></span> and the closing curly brackets <span style="color:#e83e8c;"><nowiki>}}</nowiki></span>; here is an example of a numbered list:
 
:<nowiki>{{Custom TOC|Click on the following links to:</nowiki>
 
:<nowiki># [[The Creation of Order/Summer: Balancing Self-Expression With Group Order/4. Alphanumeric Notation and the Calendrical-Musical Kosmos#Key Concepts|jump to a glossary of key concepts for this chapter]]</nowiki>
:# <nowiki>[[Queries:5188|see general queries for this chapter, including its stub nature and possible opportunities for expansion, bibliographical notes, and illustration notes]]</nowiki>
:<nowiki># [[Queries:4035|see all other queries for this chapter]]}}</nowiki>