diff --git a/docs/guides/classic-ui/index.md b/docs/guides/classic-ui/index.md new file mode 100644 index 000000000..3a03d063b --- /dev/null +++ b/docs/guides/classic-ui/index.md @@ -0,0 +1,14 @@ +--- +myst: + html_meta: + "description": "User Guide for Plone 6 Classic UI" + "property=og:description": "User Guide for Plone 6 Classic UI" + "property=og:title": "User Guide for Plone 6 Classic UI" + "keywords": "Plone, Classic UI, user, guide" +--- + +```{toctree} +:maxdepth: 2 + +working-with-content/index +``` diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-collections.md b/docs/guides/classic-ui/working-with-content/adding-content/adding-collections.md new file mode 100644 index 000000000..729494db4 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/adding-content/adding-collections.md @@ -0,0 +1,43 @@ +# Adding Collections + +Collections (formerly called Smart Folders) are virtual containers of +lists of items found by doing a specialized search. + +See the later section of the manual {doc}`../using-collections/index` + +Choose "Collection" in the *Add new...* menu for a folder to start defining your collection: + +```{figure} adding-collections_add-menu.png +:align: center +:alt: add new collection menu image +``` + +Select **Collection** from the drop-down menu, and you'll see the *Add Collection* panel: + +```{figure} adding-collections_add-form.png +:align: center +:alt: collection form +``` + +Apart from the usual fields, the interesting part starts with the **Search terms** + +```{figure} collection-criteria.png +:align: center +:alt: true +``` + +You can pick all *meta-data* that Plone has on content items as criteria. +By combining more criteria, you can create sophisticated queries, which will be automatically updated. + +Your collection can search for all items of types `Page` and `News Item` that have a Tag of `Sport`, created in the last 3 months. +Or all `Events` that have a Start date in the next month. + +The possibilities are endless, and Plone will always show the results according to the criteria. + +If you create a new content item later with the tag of "Sport", it will automatically show up in the collection you have just defined. + +## History + +Collections have been around under various names. They used to be called "Smart Folders" in earlier versions of Plone, and you may find references to that in older documentation. It may even be that your site has so-called "Old Style collections" enabled as well. + +See the later section of the manual {doc}`../using-collections/index` diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-collections_add-form.png b/docs/guides/classic-ui/working-with-content/adding-content/adding-collections_add-form.png new file mode 100644 index 000000000..524041b11 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/adding-collections_add-form.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-collections_add-menu.png b/docs/guides/classic-ui/working-with-content/adding-content/adding-collections_add-menu.png new file mode 100644 index 000000000..9d39ca345 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/adding-collections_add-menu.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-content_add-menu.png b/docs/guides/classic-ui/working-with-content/adding-content/adding-content_add-menu.png new file mode 100644 index 000000000..fe546dc74 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/adding-content_add-menu.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-events.md b/docs/guides/classic-ui/working-with-content/adding-content/adding-events.md new file mode 100644 index 000000000..001cd9e76 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/adding-content/adding-events.md @@ -0,0 +1,55 @@ +# Adding Events + +Plone web sites have a built-in system for managing and showing calendar events. + +Use the *Add new...* menu for a folder to add an event: + +```{figure} adding-events_add-menu.png +:align: center +:alt: add-new-menu.png +``` + +Select **Event** from the drop-down menu, and you'll see the rather large *Add Event* panel: + +```{figure} adding-events_add-form.png +:align: center +:alt: Adding events form +``` + +From the top, we have the following fields: + +- *Title* - **REQUIRED** +- *Summary* +- *Event starts* - **REQUIRED** +- *Event ends* - **REQUIRED** +- *Whole Day* +- *Open End* +- *Recurrence* +- *Event Location* +- *Attendees* +- *Contact Name* +- *Contact Email* +- *Contact Phone* +- *Event URL* +- *Event body text* (visual editor panel) +- Change note + +```{note} +Only three fields, title and start and end date and time, are required. +``` + +Although this is a large input panel, if you are in a hurry, type in the title and the start and end times and save. +Of course, if you have the other information, you should type it in. + +One part of the panel needs a bit more explanation: the event start and end times. +Both these can be set using a handy pop-up calendar. This will show when you click on the date. + +Setting an event to be "Whole day" will remove the start and end times. + +But there are many more options: you can set an event to be "Open-ended" if you don't know when the end date is, or if it is an ongoing activity that you would still like to show as an event. + +For repeating events, use the "recurrence" link. You can set when, and how often, your event will repeat: daily, weekly, every third Tuesday of the month until 2017, etcetera. You can specify that an event should repeat a certain number of times, or until a certain date. + +```{note} +**IMPORTANT:** Your event will not show on the main web site calendar until it has been **published**. +``` diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-events_add-form.png b/docs/guides/classic-ui/working-with-content/adding-content/adding-events_add-form.png new file mode 100644 index 000000000..2f4939c07 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/adding-events_add-form.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-events_add-menu.png b/docs/guides/classic-ui/working-with-content/adding-content/adding-events_add-menu.png new file mode 100644 index 000000000..dc323f386 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/adding-events_add-menu.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-files.md b/docs/guides/classic-ui/working-with-content/adding-content/adding-files.md new file mode 100644 index 000000000..65d99cb3f --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/adding-content/adding-files.md @@ -0,0 +1,27 @@ +# Adding Files + +Files of various types can be uploaded to Plone web sites. + +Choose file in the *Add new...* menu for a folder to upload a file: + +```{figure} adding-files_add-menu.png +:align: center +:alt: add-new-menu.png +``` + +Select **File** from the drop-down menu, and you'll see the *Add File* panel: + +```{figure} adding-files_add-form.png +:align: center +:alt: true +``` + +Click the *Browse* button to navigate to the file you want to upload from your local computer. Provide a title (you can use the same file name used on your local computer if you want). +Provide a *description* if you want. When you click the save button the file will be uploaded to the folder. + +Example file types include PDF files, Word documents, database files, zip files... -- well, practically anything. +Files on a Plone web site are treated as just files and will show up in contents lists for folders, but there won't be any special display of them. +They will appear by name in lists and will be available for download if clicked. + +There are specialized add-on tools for Plone web sites that search the content of files, or can provide a preview of for instance PDF or Office files. +If you are interested in this functionality, ask your Plone web site administrator. diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-files_add-form.png b/docs/guides/classic-ui/working-with-content/adding-content/adding-files_add-form.png new file mode 100644 index 000000000..f8eb94ffb Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/adding-files_add-form.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-files_add-menu.png b/docs/guides/classic-ui/working-with-content/adding-content/adding-files_add-menu.png new file mode 100644 index 000000000..91f83c355 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/adding-files_add-menu.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-folders.md b/docs/guides/classic-ui/working-with-content/adding-content/adding-folders.md new file mode 100644 index 000000000..cad60c298 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/adding-content/adding-folders.md @@ -0,0 +1,45 @@ +# Adding Folders + +Adding folders to a Plone web site is the basic way of controlling the organization of content. + +You have undoubtedly created folders (directories) on your computer's hard drive. +Personal computers use a hierarchy of folders to structure and organize the programs and files on the hard drive. +In Plone folders are essentially used the same way, except that they are created on a Plone web site, for organizing content in Plone's built-in storage system. + +Folders are added by clicking the **Add new...** drop-down menu. +Select **Folder** from the menu: + +```{figure} adding-folders_add-menu.png +:align: center +:alt: add-new-menu.png +``` + +You should now see the *Add Folder* screen: + +```{figure} adding-folders_add-form.png +:align: center +:alt: true +``` + +Fill in the **Title**, which is required, as indicated by the red dot. +The **Summary** is optional; you can always come back to the edit panel if you need to add a description of the folder. +Summaries are useful when a site visitor uses the search tool included with Plone - results will display with both the Title and Summary of the item. + +You also notice tabs along the top: + +- *Default*, for entering the Title and Description fields, +- *Categorization,* for specifying categories that apply to the folder + (you may know these as *keywords*), +- *Dates*, for setting the time period when the folder should be + available for view on the web site, +- *Ownership*, for specifying the creator and/or contributors for the + content item, +- *Settings,* for allowing comments about the item, enabling {ref}`rst_prev-next-links`, + and choosing whether it shows in the navigation menu for the web + site. + +These tabs are standard, so you'll see them when you click other content types. +We will cover these tabs in another section of this user manual. + +Be sure to click **Save** at the bottom of the page when you are finished. +This will complete the folder creation process. diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-folders_add-form.png b/docs/guides/classic-ui/working-with-content/adding-content/adding-folders_add-form.png new file mode 100644 index 000000000..2bb9adcc2 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/adding-folders_add-form.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-folders_add-menu.png b/docs/guides/classic-ui/working-with-content/adding-content/adding-folders_add-menu.png new file mode 100644 index 000000000..6e550c41c Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/adding-folders_add-menu.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-images.md b/docs/guides/classic-ui/working-with-content/adding-content/adding-images.md new file mode 100644 index 000000000..5c8350aaf --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/adding-content/adding-images.md @@ -0,0 +1,47 @@ +# Adding Images + +Adding images to a Plone web site is a basic task that may involve a little work on your local computer, but is essential, because photographs, maps, and custom graphics are so important on web sites. + +{doc}`preparing-images-for-the-web` + +```{note} +Remember to use web-standard file formats for all images. +Acceptable formats include: JPG, JPEG, GIF, and PNG. + +Do not use BMP or TIFF formats as these are not widely supported by web browsers, and can lead to slower websites.\*\* +``` + +When you are ready to upload an image, use the *Add new...* drop-down menu. + +```{figure} adding-images_add-menu.png +:align: center +:alt: add-new-menu.png +``` + +After clicking to add an **Image**, you'll see the *Add Image* panel: + +```{figure} adding-images_add-form.png +:align: center +:alt: Adding images form +``` + +The Title and Description fields (field, as in "data input field") are there, as with adding a Folder, and at the bottom there is a place to upload an image. +Let's look at the three input fields individually: + +- *Title* - Use whatever text you want, even with blanks and + punctuation (Plone handles web addressing). +- *Description* - Always a good idea, but always optional. Leave it + blank if you want. +- *Image* - The Image field is a text entry box along with a Browse... + button. You don't have to type anything here; just click the Browse + button and you'll be able to browse you local computer for the image + file to upload. + +For images, at a minimum, you will browse your local computer for the image file, then click **Save** at the bottom to upload the image to the Plone web site. + +You'll have to wait a few seconds for the upload to complete. +A preview of the uploaded image will be shown when the upload has finished. + +Images and files that you upload into Plone have their IDs (URLs) based on the title that you give to the image (instead of the file name of the image or file). + +However, if you leave the title empty, the name of the item will default to the name of the file. diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-images_add-form.png b/docs/guides/classic-ui/working-with-content/adding-content/adding-images_add-form.png new file mode 100644 index 000000000..14eacdb45 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/adding-images_add-form.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-images_add-menu.png b/docs/guides/classic-ui/working-with-content/adding-content/adding-images_add-menu.png new file mode 100644 index 000000000..7d8acca89 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/adding-images_add-menu.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-links.md b/docs/guides/classic-ui/working-with-content/adding-content/adding-links.md new file mode 100644 index 000000000..38dbde87a --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/adding-content/adding-links.md @@ -0,0 +1,32 @@ +# Adding Links + +In addition to links embedding within pages, Links can be created as discrete content items. +Having links as discrete items lets you do things like organizing them in folders, setting keywords on them to facilitate grouping in lists and search results, or include them in navigation. + +Add a link by clicking the menu choice in the *Add new...* menu: + +```{figure} adding-links_add-menu.png +:align: center +:alt: add-new-menu.png +``` + +You will see the Add\*Link\* panel: + +```{figure} adding-links_add-form.png +:align: center +:alt: Adding links form +``` + +Good titles for links are important, because the titles will show up in lists of links, and because there tend to be large numbers links held in a folder or collection. + +Paste the web address in the URL field or type it in. +There is no preview feature here, so it is best to paste the web address from a browser window where you are viewing the target for the link to be sure you have the address correct. + +## The Link Object in Use + +A link object will behave in the following ways, depending on your login +status, or permissions. + +- **If you have the ability to edit the link object**, when you click on the link object you'll be taken to the object itself so that you can edit it (otherwise you'd be taken to the link's target and could never get to the edit tab!) +- **If you don't have the ability to edit the link object**, when you click on the link object you'll be taken to the target of the link object. Likewise, if you enter the web address of the link object + directly in your browser, you'll be taken directly to the link's target. The link object in this case acts as a *redirect*. diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-links_add-form.png b/docs/guides/classic-ui/working-with-content/adding-content/adding-links_add-form.png new file mode 100644 index 000000000..b813ab4e8 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/adding-links_add-form.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-links_add-menu.png b/docs/guides/classic-ui/working-with-content/adding-content/adding-links_add-menu.png new file mode 100644 index 000000000..adb0d0a73 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/adding-links_add-menu.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-new-content.md b/docs/guides/classic-ui/working-with-content/adding-content/adding-new-content.md new file mode 100644 index 000000000..7de8aa873 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/adding-content/adding-new-content.md @@ -0,0 +1,101 @@ +# Adding New Content + +A general overview of how to add new content items in Plone, including definitions of each standard content type + +New content items are added via the **Add New . . .** drop-down menu: + +```{figure} adding-content_add-menu.png +:align: center +:alt: add-new-menu.png +``` + +Adding content in Plone is done *placefully*, which means you should navigate to the section of your Plone website where you want the new content to reside **before** you use the **Add New . . .** drop-down menu. +You can of course cut, copy, and paste content items from one section to another if needed at any later time. + +## Content Types + +In Plone, you can use a number of **Content Types** to post certain kinds of content. +For example, to upload an image you must use the **Image** content type. +Below is a list of the available content types in order of their appearance, and what each are used for: + +Collection + +: Collections are used to group and display content based on a set of **criteria** which you can set. Collections work much like a query does in a database. + +Event + +: An Event is a content type specifically for posting information about an event (such as a fundraiser, meeting, barbecue, etc). + This content type has a function which allows the site visitor to add the event to their desktop calendar. This includes applications such as: Google Calendar, Outlook, Sunbird and others. + To add a single event to your calendar, click on the iCal link next to the "Add event to calendar" text in the main view of the event item. + + ```{figure} events-summary-chart.png + :align: center + :alt: events-summary-chart.png + ``` + + You can also get all the events in a folder in one go (currently only available in iCal format). + To download the iCal file, append *@@ics_view* to the end of the URL of the folder or collection containing the events. + For example, if you want to get all the events from the *events* folder in the root of your site,go to *http://example.com/events/@@ics_view*. + +File + +: A File in Plone is any binary file you wish to upload with the intent to be downloaded by your site visitors. Common examples are PDFs, Word Documents, and spreadsheets. + +Folder + +: Folders work in Plone much like they do on your computer. You can use folders to organize your content, and to give your Plone website a navigation structure. + +Image + +: The Image content type is used for uploading image files (JPG, GIF, PNG) so that you can insert them into pages or other page-like content types. + +Link + +: Also referred to as the 'Link Object'; do not confuse this with the links you create with the visual editor on pages or other content types. + The Link content type is often used to include a link to an external website in Navigation and other specialized uses. + +News Item + +: This content type is similar to a Page, only a News Item is specifically for posting news. + You can also attach a thumbnail image to a News Item, which then appears in folder summary views next to the summary of the News Item. + +Page + +: A Page in Plone is the basic content types. + Use Pages to write the bulk of your web pages on your Plone website. + +Note: Depending on what add-on products you have installed, you may see more options in your **Add New . . .** drop-down menu than appear here. +For information about those additional content types, refer to the Product documentation for the add-on in question. + +## Title + +Nearly all content types in Plone have two fields in common: **Title** and **Description.** + +The **Title** of content items, including folders, images, pages, etc., can be anything you want -- you can use any keyboard characters, including spaces. +**Titles** become part of web address for each item you create in Plone. +Web addresses, also known as URLs, are what you type in a web browser to go to a specific location in a web site (Or, you would click your way there), such as: + +www.mysite.com/about/personnel/sally/bio + +or + +www.mysite.com/images/butterflies/skippers/long-tailed-skippers + +Web addresses *do* have restrictions on allowed keyboard characters, and spaces are not allowed. +Plone does a good job of keeping web addresses correct by using near-equivalents of the **Title** that you provide, by converting them to lowercase, and by substituting dashes for spaces and +other punctuation. + +The web address of a given item is referred to as the **short name** in Plone. +When you use the **Rename** function, you'll see the short name along with the title. + +The fields will vary according to the content type. +For instance, the Link content type has the URL field. +The File content type has the File field, and so on. + +## Description + +The **Description** appears at the top of pages, just under the Title. +Descriptions are often used to conjunction with a variety of Folder and Collection views (such as Standard and Summary). +The Description also appears in search results via Plone's native search engine. + +The Description is just plain text, without any form of mark-up. This is to keep it inline with the {term}`Dublin Core` standard, a long-established way of categorizing information. diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-news-items.md b/docs/guides/classic-ui/working-with-content/adding-content/adding-news-items.md new file mode 100644 index 000000000..ae3e105e2 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/adding-content/adding-news-items.md @@ -0,0 +1,29 @@ +# Adding News Items + +Plone web sites have a built-in system for publishing news items. + +Use the *Add new...* menu for a folder to add a news item: + +```{figure} adding-news-items_add-menu.png +:align: center +:alt: add-new-news-item-menu.png +``` + +You will see the *Add News Item* panel: + +```{figure} adding-news-items_add-form.png +:align: center +:alt: true +``` + +The standard fields for title, description, and change note are in the panel, along with a visual editor area for body text and image and image caption fields. +You can be as creative as you want in the body text area, and you can use the insert image (upload image) function to add as much illustration as needed. +The images you upload for the news item will be added to the folder in which you are adding the news item. + +The *Lead Image* and *Lead Image Caption* fields are for adding an image to be used as a representative graphic for the news item, for posting in news item listings. +The image will be automatically resized and positioned. +Use the **Body Text** to insert an image in the actual body of the News Item. + +```{note} +**IMPORTANT**: News items will not appear in the main web site news listing or news portlet until they are **published.** +``` diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-news-items_add-form.png b/docs/guides/classic-ui/working-with-content/adding-content/adding-news-items_add-form.png new file mode 100644 index 000000000..4af35c56c Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/adding-news-items_add-form.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-news-items_add-menu.png b/docs/guides/classic-ui/working-with-content/adding-content/adding-news-items_add-menu.png new file mode 100644 index 000000000..79c361e9a Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/adding-news-items_add-menu.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-pages.md b/docs/guides/classic-ui/working-with-content/adding-content/adding-pages.md new file mode 100644 index 000000000..af2728905 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/adding-content/adding-pages.md @@ -0,0 +1,44 @@ +# Adding Pages + +Pages in Plone vary greatly, but are single "web pages," of one sort or +another. + +To add a page, use the *Add new...* menu for a folder: + +```{figure} adding-pages_add-menu.png +:align: center +:alt: add-new-menu.png +``` + +Select **Page** from the menu, and you'll see the *Add Page* screen: + +```{figure} adding-pages_add-form.png +:align: center +:alt: Adding pages form +``` + +The **Title** and **Description** fields are there at the top. Fill each of them out appropriately. There is a *Change note* field at the bottom, also a standard input that is very useful for storing helpful memos describing changes to a document as you make them. +This is useful for pages on which you may be collaborating with others. + +The middle panel, **Body Text**, is where the action is for pages. +The software used for making Pages in Plone, generically called *visual editor* and specifically a tool called TinyMCE, is a most important feature allowing you to do WYSIWYG editing. +WYSIWYG editing -- *What You See Is What You Get* -- describes how word processing software works. +When you make a change, such as setting a word to bold, you see the bold text immediately. + +People are naturally comfortable with the WYSIWYG approach of typical word processors. We will describe later in this manual. + +## Markup languages + +Your site-administrator may also enable so-called markup languages. +If you are the sort of person who likes to enter text using so-called mark-up formats, you may switch off the visual editor under your personal preferences, which will replace it with a simplified textentry panel. +The mark-up formats available in Plone are: + +- [Markdown](http://en.wikipedia.org/wiki/Markdown) +- [Textile](http://en.wikipedia.org/wiki/Textile_%28markup_language%29) +- [Structured Text](http://www.zope.org/Documentation/Articles/STX) +- [Restructured Text](http://en.wikipedia.org/wiki/ReStructuredText) + +Each of these works by the embedding of special formatting codes within text. +For example, with structured text formatting, surrounding a word or phrase by double asterisks will make that word or phrase bold, as in \*\*This text would be bold.\*\* +These mark-up formats are worth learning for speed of input if you do a lot of page creation, or if you are adept at such slightly more technical approaches to entering text. +Some people prefer such formats not for speed itself, but for fluidity of expression. diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-pages_add-form.png b/docs/guides/classic-ui/working-with-content/adding-content/adding-pages_add-form.png new file mode 100644 index 000000000..52c1e76b0 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/adding-pages_add-form.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/adding-pages_add-menu.png b/docs/guides/classic-ui/working-with-content/adding-content/adding-pages_add-menu.png new file mode 100644 index 000000000..fe546dc74 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/adding-pages_add-menu.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/basicpropertiestabs.png b/docs/guides/classic-ui/working-with-content/adding-content/basicpropertiestabs.png new file mode 100644 index 000000000..f1cc31d5f Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/basicpropertiestabs.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/collection-criteria.png b/docs/guides/classic-ui/working-with-content/adding-content/collection-criteria.png new file mode 100644 index 000000000..ff5921781 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/collection-criteria.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/datessettings.png b/docs/guides/classic-ui/working-with-content/adding-content/datessettings.png new file mode 100644 index 000000000..ee594a008 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/datessettings.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/editpagecategorization.png b/docs/guides/classic-ui/working-with-content/adding-content/editpagecategorization.png new file mode 100644 index 000000000..1986f906d Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/editpagecategorization.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/events-summary-chart.png b/docs/guides/classic-ui/working-with-content/adding-content/events-summary-chart.png new file mode 100644 index 000000000..e6b6ce97a Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/events-summary-chart.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/image_resizing.png b/docs/guides/classic-ui/working-with-content/adding-content/image_resizing.png new file mode 100644 index 000000000..3928129a2 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/image_resizing.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/index.md b/docs/guides/classic-ui/working-with-content/adding-content/index.md new file mode 100644 index 000000000..7d7f77e6e --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/adding-content/index.md @@ -0,0 +1,21 @@ +# Adding Content + +How to add basic content types to Plone web sites + +```{toctree} +:maxdepth: 2 + +adding-new-content +adding-folders +whats-in-a-web-name +adding-images +adding-pages +adding-files +adding-links +adding-events +adding-news-items +setting-basic-properties +restricting-types-in-a-folder +preparing-images-for-the-web +adding-collections +``` diff --git a/docs/guides/classic-ui/working-with-content/adding-content/menu-restrictions.png b/docs/guides/classic-ui/working-with-content/adding-content/menu-restrictions.png new file mode 100644 index 000000000..c8d8a450f Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/menu-restrictions.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/ownershippanel.png b/docs/guides/classic-ui/working-with-content/adding-content/ownershippanel.png new file mode 100644 index 000000000..216dfcff6 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/ownershippanel.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/preparing-images-for-the-web.md b/docs/guides/classic-ui/working-with-content/adding-content/preparing-images-for-the-web.md new file mode 100644 index 000000000..3c3af63fb --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/adding-content/preparing-images-for-the-web.md @@ -0,0 +1,36 @@ +# Preparing Images for the Web + +Preparing images for the web is an essential part of using images in Plone, or in any online context. +As you will see, size matters. + +Many people source photographs taken with a digital camera, but they can also be scanned images, graphical illustrations made with software, and other specialized images. +Let's take a look at the case of a butterfly photo taken with a digital camera. + +Digital photographs taken with modern cameras are usually too big to post directly on a website, so they need to be resized. +A typical web site design may have a width of around 1000 pixels. When a photograph comes off your camera, it may be several thousand pixels wide and tall, and several megabytes in file size. +You need to use software on your computer to resize the image to something less than 1000 x 1000 pixels, often much smaller than that. + +The software you use to view or print your digital photos will often have this resizing functionality, or you may have graphics software such as Adobe Photoshop or Gimp on your computer. +Resizing an image, sometimes called resampling, is a standard function you should be able to find in your software, often under the *Image* menu. Some also have a special "save for web" command. + +How do you know what width, in pixels, to resize your image? +It depends. +For a little "head shot" photograph to go in a biography, maybe 200 pixels wide is just right. +For a group photograph, 200 pixels would be too small to allow identification of the people in the photograph, so it may need to be closer to 400 pixels wide. +For a scanned map image, perhaps the image width would need to be 1000 pixels for the map detail to be usable. + +After saving your resized image, give it a name that indicates the new size (e.g., butteryfly-resized-300px.jpg). +The file format is most commonly .jpg (or .jpeg). Other common formats for images include .png and .gif. +Take note of where you save images on your computer so that you can find them when you upload them to your Plone web site. + +```{figure} image_resizing.png +:align: center +:alt: image\_resizing.png +``` + +**To summarize**: + +1. Take your photograph with your camera, or find an existing image you want to use +2. Transfer it to your computer +3. Use image software on your computer to resize your photograph +4. Upload it to your Plone website diff --git a/docs/guides/classic-ui/working-with-content/adding-content/restricting-types-in-a-folder.md b/docs/guides/classic-ui/working-with-content/adding-content/restricting-types-in-a-folder.md new file mode 100644 index 000000000..48b587ad2 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/adding-content/restricting-types-in-a-folder.md @@ -0,0 +1,57 @@ +# Restricting Types in a Folder + +The Add new... menu has a choice for restricting the content types that can be added to the folder. + +Restricting types available for adding to a folder is the simplest way to control content creation on a Plone web site. +You may want to restrict content types if your site is going to be worked on by several people. +In this way you can enforce good practices such as putting images in the images folder, or having your "News" items all in the same folder. + +```{note} +Setting restrictions in the very top level, also known as the *root* of the website, is restricted to site administrators. +That is because this will influence the navigation, and may lead to unwanted side effects. +``` + +First, select the last choice in the *Add new...* menu called *Restrictions...*: + +```{figure} show-restrictions.png +:align: center +:alt: show restrictions.png +``` + +There are three choices shown for restricting types in the folder: + +- Use parent folder settings +- Use portal default +- Select manually + +The default choice, to use the setting of the parent folder. +That means when you create a folder and restrict the types that can be added, any subfolders created in the folder will automatically carry these restrictions. + +The second choice is a way to reset to the default, unrestricted setting. + +The last choice allows selection from a list of available types: + +```{figure} menu-restrictions.png +:align: center +:alt: menu for setting restrictions.png +``` + +Types listed under the *Allowed types* heading are those available on the web site. +The default, as shown, is to allow all types. +Allowed types may be toggled on and off for the folder. + +Use of *Secondary types* allows a kind of more detailed control. +For example, if it is preferred to store images in one folder, instead of scattering them in different folders on the web site -- a scheme that some people prefer -- an "Images" folder could be created with the allowed type set to the Image content type *only*. + +Likewise an "Company Events" folder could be created to hold only the Event content type. + +If left this way, content creators would be forced (or a single web site owner) to follow this strict scheme. + +Perhaps some flexibility is desired for images, though. By checking the Image content type under the *Secondary types* heading for the "Company Events" folder, images could be added if really needed, by using the *More...* submenu, which would appear when this mechanism is in place. + +The *Secondary types* will be allowed, but be a little more hidden when adding content. +That way, you still have flexibility without confusing part-time editors with too many options. + +Some people prefer a heterogeneous mix of content across the web site, with no restrictions. +Others prefer a more regimented approach, restricting types in one organizational scheme or another. +Plone has the flexibility to accommodate a range of designs. diff --git a/docs/guides/classic-ui/working-with-content/adding-content/setting-basic-properties.md b/docs/guides/classic-ui/working-with-content/adding-content/setting-basic-properties.md new file mode 100644 index 000000000..836df3297 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/adding-content/setting-basic-properties.md @@ -0,0 +1,140 @@ +# Setting Basic Properties + +The tab panels available on each content item has fields for basic information. +The more data you can provide, the better Plone can help in making the content available to the relevant visitors. + +Any content item, when clicked by a user with edit rights for the item, will show a set of tabs at the top for setting basic properties: + +```{figure} basicpropertiestabs.png +:align: center +:alt: basicpropertiestabs.png +``` + +These basic properties tabs are: + +- *Default* - shows the main data entry panel for the content item +- *Settings* - shows a small panel for setting whether or not the item will appear in navigation menus and if comments are allowed on the item +- *Categorization* - shows a panel for creating and setting tags (keywords) for the item +- *Dates* - shows the publishing date and expiration date for the item +- *Ownership* - shows a panel for setting creators, contributors, and any copyright information for the item + +The input fields under these tabs cover basic descriptive information called **metadata**. +Metadata is sometimes called "data about data." +Plone can use this metadata in a multitude of ways. + +Here is the *Categorization* panel, shown for a page content item (would be the same for other content types): + +```{figure} editpagecategorization.png +:align: center +:alt: Edit page categorization +``` + +The main input field for the panel is for specifying *Tags*, sometimes also known as *Categories* + +Create them, just by typing in words or phrases. +Plone will automatically search for existing tags while you type, so you can select already existing tags. +If you want to create a new tag, just hit "enter" after your word (or phrase). + +The *Related Items* field lets you set links between content items, which will show as links at the bottom, when a content item is viewed. +This is useful when you don't want to use explicit tags to connect content. + +The *Location* field is a geographic location, suitable for use with mapping systems, but appropriate to enter, for general record keeping. Note that this field may not always be present, this is a setting that your site administrator has to enable. + +The *Language* choice normally would default to the site setting, but on multilingual web sites, different languages could be used in a mix of content. + +The *Dates* panel has fields for the publishing date and the expiration date, effectively start and stop dates for the content if you wish to set them: + +```{figure} datessettings.png +:align: center +:alt: Dates Settings +``` + +The publication and expiration dates work like this: + +- When an item is past its expiration date, it's marked "expired" in + red in its document byline when viewed. +- An item whose publication date is before the current date doesn't get + extra text in its byline. +- In both cases, the item is "unpublished", which is not to be confused + with a workflow state. +- It merely means the item doesn't show up in listings and searches. +- These listings include folder listings. +- However, the owner of the item will keep seeing it, which is handy + because you like to know what you have lying around in your site. +- The permission that controls this is Access inactive portal content. +- Expired items in a folder are marked as such when viewing the + folder_contents. +- There's no quick way of seeing if items in a folder listing are not + yet published. +- When you set an unpublished item as the default view for a folder, + that item will be shown. +- Unpublishing an item doesn't have any effect for admins. They will + always see unpublished items in their listings and searches. +- Giving another regular users rights ("can add", can edit", "can + review") on the item doesn't make it any less unpublished for those + users. +- A practical way for a non-admin user to access an unpublished item is + directly through its URL. + +The *Ownership* panel has three free-form fields for listing creators, +contributors, and information about copyright or ownership rights to the +content: + +```{figure} ownershippanel.png +:align: center +:alt: Ownership Panel +``` + +The *Settings* panel has fields that may vary a bit from content type to +content type, but generally there are input fields controlling whether +or not the item appears in navigation, or if there are comments allowed, +and other similar controls: + +```{figure} settingspanel.png +:align: center +:alt: Settings panel +``` + +You can allow users to edit the "Short name" of content items. + +```{note} +The "Short Name" is part of the URL of a content item. +That means that no special characters or spaces are allowed in it. +For experienced web editors, it can be handy to manipulate the Short Name directly in order to generate more memorable or shorter URL's. +``` + +## Recommendations + +There is no requirement to enter the information specified through these panels, but it is a good idea to do so. +For the *Ownership* panel, providing the data is important for situations where there are several +people involved in content creation, especially if there are multiple creators and contributors working in groups. +You don't always need fields such as publishing and expiration dates, language, and copyrights, but these data should be specified when appropriate. +A content management system can only be as good as the data completeness allows. + +Specifying tags requires attention, but if you are able to get in the habit, and are committed to creating a meaningful set of tags, there is a big return on the investment. +The return happens through the use of searching and other facilities in Plone that work off the categorization. +The same holds for setting related items. You'll be able to put your finger on what you need, and you may be able to discover and use relationships within the content. + +## Exposing Metadata Properties as meta tags in the HTML source + +From Plone 4 on, in *Site Setup*, there is a check box that will expose the {term}`Dublin Core` metadata properties. +Checking this box will expose the title, description, etc. metadata as meta tags within the +HTML ``. +For example: + +``` + + + + + + + +a +``` + +The generator will check and obey the so-called *allowAnonymousViewAbout* setting in the {term}`Control Panel` and affects the properties\*Creator\*, *Contributors* and *Publisher*. + +You can read more about [Dublin Core](http://dublincore.org/) and +[HTML +Metatags](http://www.w3.org/TR/html401/struct/global.html#h-7.4.4.2). diff --git a/docs/guides/classic-ui/working-with-content/adding-content/settingspanel.png b/docs/guides/classic-ui/working-with-content/adding-content/settingspanel.png new file mode 100644 index 000000000..b3bdb4fba Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/settingspanel.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/show-restrictions.png b/docs/guides/classic-ui/working-with-content/adding-content/show-restrictions.png new file mode 100644 index 000000000..91907d4c8 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/adding-content/show-restrictions.png differ diff --git a/docs/guides/classic-ui/working-with-content/adding-content/whats-in-a-web-name.md b/docs/guides/classic-ui/working-with-content/adding-content/whats-in-a-web-name.md new file mode 100644 index 000000000..a965eea83 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/adding-content/whats-in-a-web-name.md @@ -0,0 +1,87 @@ +# What's in a Web Name? + +Individual content items on a Plone web site have discrete web addresses. +Plone creates these automatically, based on the Title that you supply. + +## What's in a Web Name? + +The **Title** of content items, including folders, images, pages, etc., can be anything you want -- you can use any keyboard characters, including spaces. +**Titles** become part of web address for each item you create in Plone. +Web addresses, also known as URLs, are what you type in a web browser to go to a specific location in a web site (Or, you would click your way there), such as: + +www.mysite.com/about/personnel/sally/bio + +OR + +www.mysite.com/images/butterflies/skippers/long-tailed-skippers + +Web addresses *do* have restrictions on allowed keyboard characters, and spaces are not allowed. +Plone does a good job of keeping web addresses correct by using near-equivalents of the **Title** that you provide, by converting them to lowercase, and by substituting dashes for spaces and other punctuation. + +To illustrate, let's take each of these two web addresses and split them out into their component parts: + +``` +www.mysite.com/about/personnel/sally/bio +^ +website name + ^ + a folder named About + ^ + a folder named Personnel + ^ + a folder named Sally + ^ + a folder named Bio +``` + +In this example, Plone changed each folder title to lowercase, e.g., from Personnel to personnel. +You don't have to worry about this. +Plone handles the web addressing; you just type in titles however you want. + +And, for the second example: + +``` +www.mysite.com/images/butterflies/skippers/long-tailed-skippers +^ +website name + ^ + a folder named Images + ^ + a folder named Butterflies + ^ + a folder named Skippers + ^ + a folder named Long-Tailed Skippers +``` + +This example is similar to the first, illustrating how there is a lowercase conversion from the title of each folder to the corresponding part of the web address. +Note the case of the folder named Long-tailed Skippers. Plone kept the dash, as that is allowed in both title and part of the web address, but it changed the blank between the words Tailed and Skippers to a dash, in the web address, along with the lowercase conversion. + +The web address of a given item is referred to as the **short name** in Plone. +When you use the **Rename** function, you'll see the short name along with the title. + +## What’s in a Title? + +The title of a content item not only affects the **short name** that is used in the URL of the item. +It is also displayed, with a twist, in the [title bar](http://en.wikipedia.org/wiki/Window_decoration#Title_bar) of the browser window, or in the browser tab. +The twist consists in the fact that what is displayed consists of the *item title* and the *site title*, separated by an [Em dash](http://en.wikipedia.org/wiki/Dash#Em_dash). +The site title is set in the *site control panel* (`http://yoursite.com/@@site-controlpanel`), but for the purposes of this section it is not necessary to have the permissions to access it. + +For example, the title for the item at shows in the browser tab or title bar as: + +*About CIA — Central Intelligence Agency*. + +The part to the left of the Em dash, **About CIA** is the *item title*, while the part to the right, **Central Intelligence Agency**, is the *site title*. +The site title is appended to the item title, with an Em dash, automatically. Technically, this is what the `` HTML element is set to. + +Why is this important? In and of itself, this behavior of a Plone site might often be overlooked. +However, it becomes important when looking at the results provided by a search engine, such as Google. +When Google lists a page from a Plone site, the title used is the same one just described (*item title — site title*). + +Often, you might want the homepage of your site to be listed in Google search results with just the site title. +But you can not leave the homepage item title empty, so how to achieve this? +Thankfully, there is an easy solution: make the homepage title **exactly identical** to the site title. + +In the CIA example above, if the homepage title were set to *Central Intelligence Agency*, then Google would list it simply as: + +*Central Intelligence Agency* diff --git a/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/advanced-control.md b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/advanced-control.md new file mode 100644 index 000000000..fb770017f --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/advanced-control.md @@ -0,0 +1,56 @@ +# Advanced Control + +The publication control system, under the advanced menu, has sophisticated features for setting availability by date and by context. + +The *state* Toolbar menu has an *advanced*... choice: + +```{figure} workflow-advanced-menu.png +:align: center +:alt: advanced state menu +``` + +which brings up the *advanced* state panel: + +```{figure} workflow-advanced.png +:align: center +:alt: advanced workflow options. +``` + +Below an explanation section at the beginning of the panel, there is a check box showing the content that will be affected by this change of +publication state. Here it shows we are working on the "Documentation" folder. + +```{note} +A brief aside: you may have noticed that, apart from the checkbox to the left, there is also a checkbox above, next to the headers of the *Affected content* section. +The reason is that this same *advanced* state panel can be used to make the changes described below to a whole list of unrelated content items simultaneously, in bulk, from the *contents* tab of a folder. +More on this later. +``` + +The next field, *Include contained items*, is a check box for controlling whether the state change affects this item only (the +"Documentation" folder) or the items it contains and all of any subfolders and other contained items. + +**This is an important check box**. + +It lets you change the availability of an entire section of a website. +For example, the "Documentation" folder could contain four subfolders, with images, files, and other content that has been kept *private* during the initial work to build up this content. +All of it could be immediately made public -- it could be *published* -- by checking this box and checking *Publish* at the bottom before saving. + +Likewise, the *Submit for publication* choice would be used on a web site where editors control ultimate publication. + +And you can do the reverse, of course: make an entire section *private*. +For example, if an automobile rental agency decided to remove a car model from its fleet, an entire section of their website devoted to this car model, with several subfolders full of pages, images, and files, could be set to *private*. + +The next two date fields are for *Publishing date* and *Expiration date*. +Their meanings are straightforward. +If there is a window of time, for which a content item or a set of content items is valid for publication, it may be set with these fields. + +A *comment* lets you attach an explanation to all content affected by the state change. + +This is especially useful when several people are working on a website, and a person less familiar with an area of the web site looks at content and wonders why it isn't published. +They wonder, "This information looks good. Why isn't it published already?" +Then they read a comment that says something like, "Don't publish until Richard checks on copyright issues regarding the items described here." Using comments is a good idea for sensitive information, even if you are the only person working on the web site, because you might forget why you made a decision about publication state. + +Finally, at the bottom there is a choice of several available states for this action. +It will vary, depending on the present state of the item. +For example, if the item is currently in a published state, there won't be a choice for *publish*, if the item is presently in a *private* +state, there won't be a choice for *make private*, etc. If an item is published already, there will be choices in this bottom part of the +panel for *reject* and *retract*, for "unpublishing" at item, setting it back to *public draft* or then to *private* state. diff --git a/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/basic-publication-states.md b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/basic-publication-states.md new file mode 100644 index 000000000..b66f49ed6 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/basic-publication-states.md @@ -0,0 +1,52 @@ +# Basic Publication States + +The publication control system for Plone is very flexible, starting with basic settings for making an item private or public. + +In the toolbar, for any content type --folders, images, pages, etc., and any specialized content types -- there is an item for publication state. This *state* menu has settings for controlling publication state: + +```{figure} workflow-basic.png +:align: center +:alt: basic workflow menu +``` + +The toolbar will show the current publication state for the content item, such as *State: Published*, as shown above. +Private is the initial state when you create a content item -- a page, a news item -- and in the private state, as the name indicates, the content item will generally not be available to visitors to the website. + +The *Publish* menu choice will make the content item available on the web site to anonymous visitors. +The *Submit for publication* menu choice is used on web sites where there are content editors who must approve items for publication, as discussed below. + +Also, and this will be very important, certain content types, such as news items and events, will not appear on the website as you expect, until they are explicitly *published*. + +```{note} +Store this in your memory: **Publication state is important!** +``` + +Publication state can be changed only by users whose accounts have the necessary permissions. +The menu choices in the state menu will reflect existing permissions settings. +For example, in a big newspaper web site, a reporter could add pages for news articles, but the state menu will +not show a *Publish* menu choice, only a *Submit for publication* menu choice. +This is because a reporter must submit articles up the line to the editorial staff for approval before publication. +If your account has the permissions, however, the *Publish* menu choice will appear and you can simply publish in one step. + +For an editor, a content item that has been submitted may be *published* or *rejected*, either outright, because it is an inappropriate +submission for the situation, or for the more typical reason that the content item needs revision. + +After a content item has been *published*, it may be *retracted*, to change the state back to *public draft* state, or *sent back* to +private, if desired. +The menu choices in the state menu will change accordingly: + +```{figure} workflow-reject.png +:align: center +:alt: basic workflow menu +``` + +Instead of completely deleting items in your site that have become obsolete or undesired for some reason, you can also think about retracting ("unpublishing"), or setting to *private*, any content . + +Setting to *private* will take the item from public view and from showing up in search results, but will keep it around in case the format or the actual material (text, images, etc.) is needed later, or you later change your mind and want to re-publish the content. + +```{note} +Content that was published once on a public website may have been indexed by search engines. Unpublishing will make it invisible to direct visitors to *your* site, but search engines often keep a copy of it in their indexes. Then again, the same is valid for *deleting* content. +``` + +The decision to delete or to set to *private* may depend on whether or not the content exists elsewhere, on another computer or in your company central data storage. +Having large amounts of *private* content on a site might confuse editors, and it will take up some disk space on your webserver. diff --git a/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/collaboration-through-sharing.md b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/collaboration-through-sharing.md new file mode 100644 index 000000000..f9f2fadee --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/collaboration-through-sharing.md @@ -0,0 +1,41 @@ +# Collaboration through Sharing + +The Sharing item on the Toolbar empowers you to collaborate with other users through the use of several built-in roles. + +Here, Jane Doe has created a Folder called "Documentation", and has clicked on the "Sharing" option. + +```{figure} sharing-menu.png +:align: center +:alt: basic workflow menu +``` + +The default workflow for this Plone site has not been modified, so the folder is still "Private". Only she can see the contents. + +Now she wants to let her colleagues add content to the Documentation folder. + +Taking a closer look at the available permissions, they are: + +- **Can add** - When this permission is granted to a particular user (or group of users), that user can then add new content items. + And since that user was also the creator of that content item, they will be able to edit it as they like. +- **Can edit**- When this permission is granted on a folder, the user can not only edit the Folder (its title and description) but can also edit any of the items in the folder. + Note, however, the user is not allowed to delete any of the content. + When this permission is granted on a Page, for example, the user can only edit that Page and none of the other items in the folder. +- **Can view** - When this permission is used on a folder or other item, the user can view the content but not make any changes. +- **Can review** - When this permission is granted, the user can publish items. + +```{note} +Note: these permissions will override the default workflow permissions! +For example, if you grant a user "Can view" permission on a Page that is in the Private state, that user will be able to see that Page. +``` + +## Users and groups + +Now, while it is handy to give one person the right permissions, it quickly becomes messy in a larger site. + +Plone has a well-thought out system of {doc}`User and Group management</adapt-and-extend/config/users-groups>` that can help. For instance, if you put the people that work on the Sports section of your news site into the group "Sport editors", you can give them all the permissions they need at once. + +And even more important, if Sally gets transferred from the Sports section to the Science section, you only have to remove her from one group, and add to another group, and all permissions on the whole site will work for her. + +One final note: if the "Documentation" folder was not in the published state, and you had also not given your colleague the 'view' permission on the folder, but you had given that permission on a specific Page in this folder, he or she would have to know the exact URL to the Page to see it. + +Permissions are very specific in Plone! In practice, it is usually clearer to give permission on a folder-by-folder base and not per document, as this becomes hard to maintain. Then again, if you need the permissions and the security to be this fine-grained, you can! diff --git a/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/folder-workflow-state.md b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/folder-workflow-state.md new file mode 100644 index 000000000..74751ba9d --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/folder-workflow-state.md @@ -0,0 +1,47 @@ +# How a folder's workflow state affects its content + +```{admonition} Description +On this page we are referring to workflow states and their effects on content as they are configured in a default Plone installation. Your specific site may have custom workflows, and the following discussion may or may not apply. +``` + +When it comes to the *Private* state, **Folders** are somewhat special. +Changing a folder to (or leaving it in) *private* state has the following effects: + +- The folder *as well as all its contents* are taken out of the navigation and site map for anonymous users, and also for logged-in users who don't have permission to see private content. + This means that all these users will not be able to find either the folder or any of its contents through any of the navigation menus. + Of course, this includes external search engine robots. +- The folder itself can not be viewed by anonymous users, or by logged-in users who do not have permission to see private content. + This is true even if an anonymous user, for example, had the direct URL to the folder, which would be the case if a link to the folder was part of the content body of a page in a different section of the same site or even a different site. + Clicking such a link would result in being redirected to the login form. +- However, any **published** content of a **private** folder (or even of any of its sub-folders) **will** appear in the site search, even for anonymous users. +- Also, anonymous users who know the URL of a *published* content item inside a *private* folder will be able to view this content. + Consequently, if a link to any such published content of a private folder is embedded in any part of the same site or external site, that content will be viewable by anyone. + +Thus, putting a folder in the private state is not a guarantee of security for any of its contents. +Unless, of course, all the content has been made private, as well. +This can be done in bulk and in a single step, as described in {doc}`Advanced Control <advanced-control>`. + +This is especially true of a folder's default item view (see {doc}`Setting an Individual Content Item as the View for a Folder </working-with-content/managing-content/folder-view>`). +If the contained item that is set as the folder's default view is published, then the folder will in a sense be public as well, even if it's own state has been set to private. +However, the folder will still be hidden from navigation for anonymous users. + +When it comes to the folder default item view, care must be taken to have clarity on whether the desired workflow state is set on the folder, the default view item, or both. + +## A caveat: Images and Files + +When discussing **published** content of a **private** folder above, we glossed over an important assumption: namely, that all content items actually have a **published** state. +This assumption is actually incorrect. +The *Image* content type and the *File* content type do not have the *State* menu (in a default Plone installation). +Thus, they can not be made public or private or any other state. +Instead, Images and Files *inherit* their state from the container in which they find themselves. +Therefore an image in a private folder will be private; an image in a public folder will be public. + +It is possible to bypass this inheritance of a folder's workflow state by contained images and files. + +One of the workflows shipped with Plone by default is called "Single State Workflow". +To change the workflow for all Image content items, go to Content Settings on the Site Setup page. +Select *Image* (or *File*) in the top dropdown menu, and then "Single State Workflow" from the *New workflow* dropdown menu. +Once you click *Apply changes*, all Image content items will acquire the new workflow, and in particular, they will all be in published state, and will not inherit the containing folder's workflow state. + +Some site administrators prefer all **Images** to be published, but do have special workflow states for **Files**, as some files may only be accessible for logged-in users with a certain role. +That is entirely possible using the above method, and setting an appropriate workflow on the type **File** diff --git a/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/index.md b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/index.md new file mode 100644 index 000000000..a890cfff4 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/index.md @@ -0,0 +1,14 @@ +# Collaboration and Workflow + +Learn how to share and control access to your content by using the +Sharing tab and the State menu. + +```{toctree} +:maxdepth: 2 + +basic-publication-states +advanced-control +workflow-policies +collaboration-through-sharing +folder-workflow-state +``` diff --git a/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/sharing-menu.png b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/sharing-menu.png new file mode 100644 index 000000000..67c01736f Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/sharing-menu.png differ diff --git a/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/workflow-advanced-menu.png b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/workflow-advanced-menu.png new file mode 100644 index 000000000..80b6bcb19 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/workflow-advanced-menu.png differ diff --git a/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/workflow-advanced.png b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/workflow-advanced.png new file mode 100644 index 000000000..6fd0c9d30 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/workflow-advanced.png differ diff --git a/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/workflow-basic.png b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/workflow-basic.png new file mode 100644 index 000000000..eb02ab99e Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/workflow-basic.png differ diff --git a/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/workflow-policies.md b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/workflow-policies.md new file mode 100644 index 000000000..e729643d3 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/workflow-policies.md @@ -0,0 +1,55 @@ +# Workflow Policies + +Workflow policies allow a site administrator to create a formalized system for controlling publication and content management as a step-by-step flow involving different users in set roles. + +Workflow is a relatively advanced subject. + +It involves creation of a more regimented control of content creation, review, and publication. +If you have a user account on a typical small Plone site, you will probably not encounter custom workflow policies, because there isn't a need for this more sophisticated control. + +But, the potential is there for using this functionality, as it is built in to Plone, and larger organisations often use it to model their internal structure and business logic. + +For an introduction to the workflow concept, consider an example involving a web site for a newspaper business, for which these different groups of people are at work: + +Reporters + +: Can create stories, but can only submit them for review. + +Editors + +: Can review stories, but can't publish completely. They send positively reviewed and edited stories up the line for further approval. + +Copy Editors + +: Do final fact checking, fixes, and review, and may publish stories. + +A *workflow policy*, sometimes abbreviated to *workflow*, describes the constraints on state-changing actions for different groups of people. +Once the workflow policy has been created, it needs to be applied to an area of the website for the rules to take effect. + +In the example of the newspaper web site, a workflow policy would be set up and then applied to the folders where reporters do the work of adding news articles. + +Then, reporters would create stories and send them up the line for +review and approval: + +```{figure} workflowsteps.png +:align: center +:alt: true +``` + +Reporters would add news articles and would *submit* them (the *publish* menu choice is not available to them). +Likewise, editors may *reject* the article for revision or they may, in turn, *submit* the article up the line to a copy editor for final proofreading and publication. +In this newspaper business example, this policy could be called something like "Editorial Review Policy." + +Configuring a workflow policy is a matter of defining the scope of the workflow. + +This is a web site administrator task. + +There are two main ways to set workflow policies: by content type or by area of the site. Our newspaper may set their "Editorial Review Policy" on the content type "Article", whereas they may have another workflow for Images since they go through a different process of review and approval. + +But it is also possible to have different workflows for different sections of the website. The "Letters to the Editor" section may have a different workflow. + +The web site administrator would use control panels of Plone to specify where on the web site the "Editorial Review Policy" applies, site-wide or to a subsection. + +Plone comes with several useful workflow policies -- the default one is a simple web publishing policy. +Your web site administrator might employ a more specific policy, such as a policy for a community-based web site or a company Intranet (internal web system). +If so, you may need to learn some procedural steps to publishing, but these are just elaborations of principles in the default, basic workflow policy. diff --git a/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/workflow-reject.png b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/workflow-reject.png new file mode 100644 index 000000000..da442d66a Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/workflow-reject.png differ diff --git a/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/workflowsteps.png b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/workflowsteps.png new file mode 100644 index 000000000..bc0406c92 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/collaboration-and-workflow/workflowsteps.png differ diff --git a/docs/guides/classic-ui/working-with-content/content-quality/content-quality-helpers.md b/docs/guides/classic-ui/working-with-content/content-quality/content-quality-helpers.md new file mode 100644 index 000000000..8472f5e81 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/content-quality/content-quality-helpers.md @@ -0,0 +1,44 @@ +# Content Quality helper tools + +```{admonition} Description +A selection of add-ons that can help create and maintain appealing, searchable, and high-quality content. +``` + +Apart from the {doc}`inbuilt tools <index>`, there are several add-ons available. + +Note that these are all separate add-ons you will have to {doc}`install</manage/installing/installing_addons>`, and we strongly suggest testing them out first on a separate test-instance of your site, to see if they fit your purpose and do not interfere with other parts of your site. +Also, some of these tools rely on web-services, which may or may not be allowed or advisable in high-security scenarios. + +## Avoiding content errors + +- [collective.jekyll](https://pypi.python.org/pypi/collective.jekyll) is a package that will help you identify common pitfalls, like too long or short titles or descriptions, or a URL starting with "copy_of". You can even set it up so it alerts editors when they don't stick to the preferred image format, or if a page has not enough links to other pages. +- [eea.progressbar](https://pypi.python.org/pypi/eea.progressbar) can provide a visual clue as to where a document is in the workflow progress, making it easier for editors and reviewers to track what to do next to publish a document. + +## Check your links + +- [collective.linkcheck](https://pypi.python.org/pypi/collective.linkcheck) provides link validity checking and reporting. +- although you may also want to keep this out of Plone itself, and run an external linkchecker regularly. [This Linkchecker](http://wummel.github.io/linkchecker/) is open source, available for multiple platforms and can be scripted. + +## Better images + +- [Products.ImageEditor](https://pypi.python.org/pypi/Products.ImageEditor) allows you to rotate, flip, blur, compress, change contrast & brightness, sharpen, add drop shadows, crop, resize an image, and apply sepia. +- [collective.aviary](https://pypi.python.org/pypi/collective.aviary) integrates the external "Aviary" image editor into Plone. +- [plone.app.imagecropping](https://pypi.python.org/pypi/plone.app.imagecropping) surprisingly enough, crops images. + +## Tags, relations and more + +- [eea.tags](https://pypi.python.org/pypi/eea.tags) provides a Facebook-like autocomplete widget for tagging content. +- [eea.alchemy](https://pypi.python.org/pypi/eea.alchemy) allows you to bulk auto-discover geographical coverage, temporal coverage, keywords and more. +- [collective.taghelper](https://pypi.python.org/pypi/collective.taghelper) can connect to a range of webservices to assist tagging +- [collective.simserver](https://github.com/collective/collective.simserver.core) can help with creating 'related items' links +- [collective.taxonomy](https://github.com/collective/collective.taxonomy) can set up hierarchical taxonomies in multiple languages +- [collective.classifiers](https://github.com/collective/collective.classifiers) provides a 'middle ground' between a complex taxonomy and simple tagging, allowing for two new fields to classify content +- [collective.facets](https://github.com/collective/collective.facets) is an alternative approach allowing editors to add 'facets' to content. + +## Analytics and SEO + +- [collective.googleanalytics](https://pypi.python.org/pypi/collective.googleanalytics) enables easy tracking of the standard Google statistics as well as external links, e-mail address clicks and file downloads. It also defines Analytics reports that are used to query Google and display the results using Google Visualizations. +- [quintagroup.seoptimizer](https://pypi.python.org/pypi/quintagroup.seoptimizer/) allows setting various meta tags and other information search engines like and need. +- if you have migrated from another system, and need to set up aliases to content that still lives in search engines, [Products.RedirectionTool](https://pypi.python.org/pypi/Products.RedirectionTool) gives you an interface to Plone's built-in redirection and aliasing. + +And after all that work, you can use [quintagroup.analytics](https://pypi.python.org/pypi/quintagroup.analytics) to see your webmaster stats increase. Now lean back with your favorite hot beverage, you've earned it! diff --git a/docs/guides/classic-ui/working-with-content/content-quality/index.md b/docs/guides/classic-ui/working-with-content/content-quality/index.md new file mode 100644 index 000000000..11a40261f --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/content-quality/index.md @@ -0,0 +1,36 @@ +# Create and maintain good quality content + +```{admonition} Description +Plone comes with several tools to maintain the quality of the content you create. +This ensures both good results in search engines, as better usability for the visitors. +``` + +## What is "content quality"? + +Under this heading we list several tools that help you to ensure content can be properly indexed, is enriched with meta-data such as tags, dates and even geo-location, and to make sure links are not broken. + +This will also help you with accessibility certification for your content, and Search Engine Optimization (SEO) + +## Batteries included + +Plone comes standard with a whole host of features that help you: + +- The URL's for content are derived from the Title, making sure you have human-readable URL's +- [Dublin Core](http://dublincore.org/) metadata is used throughout +- The navigation is automatic, and within folders you can also enable "previous/next" style links +- Automatic filters in the editor ensure that the page will be saved as valid HTML +- Behind the scenes, Plone registers internal links with so-called "UUIDs". In short, a unique key is generated for every content item, making sure all internal links will work if you move pieces of content or even whole folders around. +- When you delete a piece of content, you will receive a warning if there are other places in your site that still link to this content. You'll get the option to correct those other pages. +- If you move content around and people come to your site using the old URL, they will be automatically redirected to the new location. *(Tip: you can even use this to create short 'alias' URL's...)* +- Images are automatically scaled. Even if your editors upload high-resolution images, you will get smaller sizes that ensure quick loading of your page. Of course the original image size is also available, if you want. + +And there are some hidden gems as well: you can enable (in the Control Panel, as site administrator) the [After The Deadline](http://www.afterthedeadline.com/) intelligent spelling and grammar checker. Now while this is only available at the moment for English, French, Spanish and Portuguese, if your site uses one of those languages this is a very valuable add-on. +For testing and light use, you can use the connection to the online service; if you have many users or create much content, you are advised to set up your own instance of the After The Deadline server. It is free and open source software. + +In the next section, we will point to several add-ons that can help even more to create and maintain high-quality content. + +```{toctree} +:maxdepth: 2 + +content-quality-helpers +``` diff --git a/docs/guides/classic-ui/working-with-content/index.md b/docs/guides/classic-ui/working-with-content/index.md new file mode 100644 index 000000000..206e5cd93 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/index.md @@ -0,0 +1,55 @@ +# Working with Content + +```{toctree} +:maxdepth: 2 + +introduction/index +``` + +```{toctree} +:maxdepth: 2 + +logging-in +``` + +```{toctree} +:maxdepth: 2 + +adding-content/index +``` + +```{toctree} +:maxdepth: 2 + +managing-content/index +``` + +```{toctree} +:maxdepth: 2 + +using-tinymce-as-visual-editor/index +``` + +```{toctree} +:maxdepth: 2 + +collaboration-and-workflow/index +``` + +```{toctree} +:maxdepth: 2 + +using-collections/index +``` + +```{toctree} +:maxdepth: 2 + +portlet-management/index +``` + +```{toctree} +:maxdepth: 2 + +content-quality/index +``` diff --git a/docs/guides/classic-ui/working-with-content/introduction/anonymous-surfing.png b/docs/guides/classic-ui/working-with-content/introduction/anonymous-surfing.png new file mode 100644 index 000000000..7690a58f7 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/anonymous-surfing.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/butterflies_folder.png b/docs/guides/classic-ui/working-with-content/introduction/butterflies_folder.png new file mode 100644 index 000000000..ea0b7e63e Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/butterflies_folder.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/butterflies_folder_text.png b/docs/guides/classic-ui/working-with-content/introduction/butterflies_folder_text.png new file mode 100644 index 000000000..a149ecc24 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/butterflies_folder_text.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/change-password.png b/docs/guides/classic-ui/working-with-content/introduction/change-password.png new file mode 100644 index 000000000..2e6b87889 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/change-password.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/client_request.png b/docs/guides/classic-ui/working-with-content/introduction/client_request.png new file mode 100644 index 000000000..0579cf0a0 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/client_request.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/client_to_server_simple.png b/docs/guides/classic-ui/working-with-content/introduction/client_to_server_simple.png new file mode 100644 index 000000000..a42c29bac Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/client_to_server_simple.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/conceptual-overview.md b/docs/guides/classic-ui/working-with-content/introduction/conceptual-overview.md new file mode 100644 index 000000000..8083ec7c3 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/introduction/conceptual-overview.md @@ -0,0 +1,140 @@ +# Conceptual Overview + +An explanation of Plone as a content management system + +## What is Plone? + +Plone is a content management system (CMS) which you can use to build a +web site. With Plone, ordinary people can contribute content to a web +site without the help of a computer geek. Plone runs over the Web, too. + +You don't need to install any special software on your computer. +The word *content* is meant to be general, because you can publish so +many types of information, including: + +```{figure} content_types_into_plone.png +:align: center +:alt: true +``` + +A Plone web site contains various kinds of content, including text, +photos, and images. These can exist in many forms: documents, news +items, events, videos, audio files, any types of file and data that can +be uploaded or created on a web site. Content can also be uploaded from +your local computer. You create *folders* on a Plone web site to hold +content, and those automatically also create the navigation structure: + +```{figure} content_is_added_to_folders.png +:align: center +:alt: true +``` + +## You Love Butterflies + +For example, to add content about butterflies, you might add a folder +named "Butterflies," then add some text to a web page in the folder: + +```{figure} butterflies_folder_text.png +:align: center +:alt: true +``` + +And then you might add some butterfly photos to the folder: + +```{figure} butterflies_folder.png +:align: center +:alt: true +``` + +You can add many types of content to a folder, including sub-folders. +After adding a few reports and videos to the Butterflies folder, the +content would be organized like this, with two sub-folders within the +Butterflies folder: + +```{figure} folders_within_folders.png +:align: center +:alt: true +``` + +## What Goes on Behind the Scenes + +You may wonder how it all works. A typical Plone web site exists as an +installation of Plone software on a web server. The web server may be +anywhere, often at a website server company within a "rack" of computers +dedicated to the task: + +```{figure} server_rack.png +:align: center +:alt: true +``` + +The diagram shows the many cables that connect individual server +computers to the Internet, across fast network connections. Your Plone +site is software and database storage software installed on one of +the individual server computers. As you type or click on your computer, +data is sent up and down the networking cables and communication +channels of the Internet to interact with your Plone software +installation on the server. + +Let's simplify the diagram showing how you interact with Plone: + +```{figure} client_to_server_simple.png +:align: center +:alt: true +``` + +You use your web browser -- Firefox, Safari, Internet Explorer, etc. -- +to view and edit your Plone web site, and the changes are stored by the +Plone software into its database storage system. + +For example, imagine your butterfly Plone web site is located at +mysite.com. You type www.mysite.com into your web browser. After you +press Enter, the following sequence of events happens as your browser +talks to the web server at mysite.com: + +```{figure} client_request.png +:align: center +:alt: true +``` + +The Plone software responds: + +```{figure} server_response.png +:align: center +:alt: true +``` + +Plone reads its database to look for information stored in mysite.com. +It then sends back the web page to your computer, in a code called HTML. +HTML is a computer language that describes how a web page looks. It +includes text, graphics, fonts, the color of the background, and just +about everything else. There are many online resources that can teach +you HTML details, but one of Plone's advantages is that you don't +need to know about HTML. That's one reason for Plone and other +similar web software; to let you focus on your content, e.g., butterfly +text and graphics, instead of learning a new computer language. + +But back to our overview. Your web browser "renders" (translates) this +HTML, and you see the resulting web page: + +```{figure} my_site_served.png +:align: center +:alt: true +``` + +As you view your butterfly web page, you can choose to change it or add +to it. You can also upload photos, documents, etc. at any time: + +```{figure} plone_donut.png +:align: center +:alt: true +``` + +After you make your edits and click "save changes," the new version of +the web page will be immediately available to anyone surfing to your +site: + +```{figure} plone_donut_full.png +:align: center +:alt: true +``` diff --git a/docs/guides/classic-ui/working-with-content/introduction/content_is_added_to_folders.png b/docs/guides/classic-ui/working-with-content/introduction/content_is_added_to_folders.png new file mode 100644 index 000000000..690bc3c71 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/content_is_added_to_folders.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/content_types_into_plone.png b/docs/guides/classic-ui/working-with-content/introduction/content_types_into_plone.png new file mode 100644 index 000000000..bc324989e Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/content_types_into_plone.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/contents-with-thumbs-suppressed.png b/docs/guides/classic-ui/working-with-content/introduction/contents-with-thumbs-suppressed.png new file mode 100644 index 000000000..102e26fa1 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/contents-with-thumbs-suppressed.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/contents-with128x128.png b/docs/guides/classic-ui/working-with-content/introduction/contents-with128x128.png new file mode 100644 index 000000000..55f56b9f7 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/contents-with128x128.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/folders_within_folders.png b/docs/guides/classic-ui/working-with-content/introduction/folders_within_folders.png new file mode 100644 index 000000000..714ac4c4b Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/folders_within_folders.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/icons.png b/docs/guides/classic-ui/working-with-content/introduction/icons.png new file mode 100644 index 000000000..2e479c256 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/icons.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/icons2.png b/docs/guides/classic-ui/working-with-content/introduction/icons2.png new file mode 100644 index 000000000..afbc99c76 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/icons2.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/index.md b/docs/guides/classic-ui/working-with-content/introduction/index.md new file mode 100644 index 000000000..a3d6e4cf1 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/introduction/index.md @@ -0,0 +1,12 @@ +# Introduction + +A Conceptual Overview of Plone + +```{toctree} +:maxdepth: 2 + +conceptual-overview +visual-design-of-plone +user-accounts-and-roles +setting-your-preferences +``` diff --git a/docs/guides/classic-ui/working-with-content/introduction/loggedin-surfing.png b/docs/guides/classic-ui/working-with-content/introduction/loggedin-surfing.png new file mode 100644 index 000000000..405245deb Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/loggedin-surfing.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/my_site_served.png b/docs/guides/classic-ui/working-with-content/introduction/my_site_served.png new file mode 100644 index 000000000..91a3da00f Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/my_site_served.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/personal-information.png b/docs/guides/classic-ui/working-with-content/introduction/personal-information.png new file mode 100644 index 000000000..ce6c01ce5 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/personal-information.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/personal-preferences.png b/docs/guides/classic-ui/working-with-content/introduction/personal-preferences.png new file mode 100644 index 000000000..dbc218fb7 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/personal-preferences.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/plone-default-design-areas.png b/docs/guides/classic-ui/working-with-content/introduction/plone-default-design-areas.png new file mode 100644 index 000000000..6ace2243c Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/plone-default-design-areas.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/plone_donut.png b/docs/guides/classic-ui/working-with-content/introduction/plone_donut.png new file mode 100644 index 000000000..44623f05a Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/plone_donut.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/plone_donut_full.png b/docs/guides/classic-ui/working-with-content/introduction/plone_donut_full.png new file mode 100644 index 000000000..11d039713 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/plone_donut_full.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/plonedefaultareaslabeled.png b/docs/guides/classic-ui/working-with-content/introduction/plonedefaultareaslabeled.png new file mode 100644 index 000000000..2d92ef912 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/plonedefaultareaslabeled.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/server_rack.png b/docs/guides/classic-ui/working-with-content/introduction/server_rack.png new file mode 100644 index 000000000..c16033b15 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/server_rack.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/server_response.png b/docs/guides/classic-ui/working-with-content/introduction/server_response.png new file mode 100644 index 000000000..4f0f0c8dc Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/server_response.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/setting-your-preferences.md b/docs/guides/classic-ui/working-with-content/introduction/setting-your-preferences.md new file mode 100644 index 000000000..1949d37fe --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/introduction/setting-your-preferences.md @@ -0,0 +1,54 @@ +# Setting Your Preferences + +After logging in to a Plone web site, you can change your personal preferences for information about your identity and choice of web site settings. + +After logging in, your full name will show on the {term}`toolbar`. + +Click on your name to open the sub-menu, then click on the *Preferences* link to go to your personal area: + +```{figure} show-preferences.png +:align: center +:alt: Show Preferences +``` + +```{figure} personal-preferences.png +:align: center +:alt: Personal Preferences +``` + +Date entry fields include: + +- *Wysiwyg editor* - Plone comes standard with {term}`TinyMCE`, an easy to use graphical editor to edit texts, link to other content items and so forth. Your site administrator might have installed alternatives, though. +- *Language* - On multilingual sites, you can select the language that you create content in most often. Plone excels at offering multilingual support. +- *Time zone* - If you work in a different timezone than the server default, you can select it here. + +## Personal information + +Now let's switch over to the "Personal Information" tab: + +```{figure} personal-information.png +:align: center +:alt: Personal Information +``` + +- *Full Name*- If your name is common, include your middle initial or middle name. +- *E-mail address* - REQUIRED - You may receive emails from the website system, or from a message board, if installed, etc. When an item is required, a little red dot will show alongside the item. +- *Home page* web address - If you have your own web site or an area at a photo-sharing web site, for instance, enter the web address here, if you wish, so people can find out more about you. +- *Biography* text box - Enter a short description of yourself here, about a paragraph or so in length. +- *Location* - This is the name of your city, town, state, province, or whatever you wish to provide. +- *Portrait* photograph upload - The portrait photograph will appear as a small image or thumbnail-size image, so it is best to use a head shot or upper-torso shot for this. + +You can change your preferences whenever you wish. + +## Changing your password + +The last tab allows you to change your password. + +```{note} +Plone is used by a variety of organisations. Some of these have centralized policies on where you can change your password, because this might also involve your access to other computer resources. In those cases, this screen might have been disabled. +``` + +```{figure} change-password.png +:align: center +:alt: Change Password +``` diff --git a/docs/guides/classic-ui/working-with-content/introduction/show-preferences.png b/docs/guides/classic-ui/working-with-content/introduction/show-preferences.png new file mode 100644 index 000000000..136c56942 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/show-preferences.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/thumbs-example-1.png b/docs/guides/classic-ui/working-with-content/introduction/thumbs-example-1.png new file mode 100644 index 000000000..85f150e8a Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/thumbs-example-1.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/user-accounts-and-roles.md b/docs/guides/classic-ui/working-with-content/introduction/user-accounts-and-roles.md new file mode 100644 index 000000000..e4b3283cc --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/introduction/user-accounts-and-roles.md @@ -0,0 +1,96 @@ +# Plone User Accounts and Roles + +Plone web sites come in many flavors, ranging from personal websites +with one user to community, organization, or business websites that could have hundreds of users. +Each person who adds content to a Plone web site has their own user account. +A user account includes a user name and a password. +Some Plone sites allow people to sign up by visiting the site, clicking a **Join** link, and filling out basic user information. +Other sites have user accounts that are created by web site administrators, in which case people normally receive emails with the user account details. + +However created, a Plone user account allows a person to log in by typing their user name and password. +Passwords are case-sensitive, which means that you have to pay attention to the uppercase and lowercase letters. +For example, if your password is xcFGt6v, you would have to type that exactly for it to work. +Passwords that have a variety of characters in them are preferred over passwords like "raccoon" or "boardwalk," as they are more difficult to guess and therefore more secure. + +## Anonymous vs Authenticated Web Surfing + +The distinction between *anonymous web surfing* and *authenticated (logged-in) web activity* is an important one: + +### Anonymous Web Surfing + +This is the normal experience for a person surfing the web. +You type the web address of a web site into your browser and you look at web pages, watch videos, view images, but you don't have to log in. +This is why this mode is called anonymous: anyone can do it just by surfing normally. + +```{note} +**Pro tip**: you can use two different browsers (like Firefox and Chrome), and *not* log in with one of them. + +That way you can compare how visitors will see your site, and you can spot content that is not yet published. +``` + +Note the presence of the *log in* link in the screen image below. +If there is a *log in* link showing, you haven't logged in -- and you are surfing the web site anonymously, as seen in the following screen capture of a new Plone web site: + +```{figure} anonymous-surfing.png +:align: center +:alt: anonymous surfing +``` + +### Authenticated (Logged-in) Web Activity + +You know the *authenticated* mode of web experience if you have ever used a bank or credit card website, or any other website that involved a user account. +A bank web site will let you view your account information, fill out information forms, transfer funds, and do other actions, but only after you have logged in. + +A Plone web site is not much different, except that you can do more sophisticated things. + +Compare the screen image below, captured after a user called "Jane Doe" has logged in. + +A toolbar has appeared on the left, which has a number of icons and actions that she can perform on the site content. +At the bottom of the toolbar, her name is mentioned. +A submenu opens when she clicks on this, allowing her to log out and perform various other options. + +```{figure} loggedin-surfing.png +:align: center +:alt: Logged in surfing +``` + +## User Roles + +Equally important is the distinction between different user roles on a Plone web site. +To illustrate the simplest case, let's consider two user roles, one called *member* and the other called *manager*. +Consider the different rights or "power" of these two roles: + +### Member + +- has a user account, so can log in +- can add content, but only in specific areas, and can't change anything outside of this area; often users are given a "home area," to treat as personal space where they can add content. +- can not publish content so that it is visible to the anonymous web surfer, even content which they added; a person with manager role must approve content for publishing + +```{note} +In many organizations, members are allowed to publish content on parts or all of the site. +This is a policy that you can set up for each site, or even part of the site +``` + +### Manager + +- has a user account, so can log in +- can add content anywhere and has the power to change anything +- can publish any content + +When you get your new account on a Plone web site, you should be given information indicating where you have the right to add content, after you have logged in. + +After logging in, if you go to a folder where you have rights, you'll see the toolbar contain the appropriate options for *contents*, *view*, *edit* and *sharing* plus even more, depending on the role you have. + +You'll be able to explore to find the differences between these options, but here are descriptions to help you start: + +- *Contents* - shows a list of items in a folder. Also allows to re-arrange +- *Edit* - shows a page where you can edit the contents using a familiar editor +- *View* - shows the view an anonymous web surfer would see +- *Add new* - shows a sub-menu where you can edit new content items (images, + pages, folders, etc.) +- *State* - shows menu choices for setting publication state (private, public draft, public, etc.) +- *Display* - shows menu choices for setting the display type (list view, summary view, etc.) +- *Sharing* - shows a panel for setting rights of other users to see or edit content + +The toolbar will offer the main ways you interact with Plone. +You will become very familiar with them as you learn more about managing a Plone-powered website. diff --git a/docs/guides/classic-ui/working-with-content/introduction/victoria.png b/docs/guides/classic-ui/working-with-content/introduction/victoria.png new file mode 100644 index 000000000..5f4939571 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/introduction/victoria.png differ diff --git a/docs/guides/classic-ui/working-with-content/introduction/visual-design-of-plone.md b/docs/guides/classic-ui/working-with-content/introduction/visual-design-of-plone.md new file mode 100644 index 000000000..b3afb0d75 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/introduction/visual-design-of-plone.md @@ -0,0 +1,106 @@ +# Visual Design Of Plone Web Sites + +Plone allows web site administrators and designers the ability to create unique site designs. +Here's an overview of the Plone layout, and some design examples. + +What does a Plone web site look like? +For years there has been a consistent design for the default Plone appearance. +The default design looks generally like this: + +```{figure} plone-default-design-areas.png +:align: center +:alt: Plone default design areas +``` + +The Plone web site you use could have a design radically different from this, but you should be able to find common elements, such as the log in link and a navigation panel or menu. +In the default design, the navigation menu is in the left area, and usually appears as an indented list of folders in the site. +There also may be a set of tabs in the *Log In, Location Information* strip near the top. + +We can distinguish between the *design* of a web site and the *functionality* of a web site. +Quite often, these aspects of a website are also under the control of different people with different skillsets. +A designer will think about the layout, the appearance and the user interface, while a content editor will think about the structure of the information. + +All of these aspects can be strictly separated in Plone, and can be adjusted independent from each other. + +We'll use the default Plone layout design as an example of typical divisions of the screen: + +```{figure} plonedefaultareaslabeled.png +:align: center +:alt: true +``` + +You may need to adapt these terms as needed for your Plone web site design. +You may encounter varied terms for describing screen real estate, such as right and left "slots," for the left and right column areas, "portlet," or "viewlet," for discrete areas or boxes, and several other terms. + +For example, we can look at a web site from the [list of Plone success stories](https://plone.com/success-stories) to compare: + +```{figure} victoria.png +:align: center +:alt: Victoria state emergency website +``` + +This is the Emergency Service web site for the Australian state of Victoria, giving citizens the latest update on potential natural disasters. +The header section has the main navigation tabs, and a login for members. +The left area lists the latest news. +The main area has one large image and four columns of smaller images, serving as links to important areas of the website. +At the bottom area (often known as "footer") it has links to social media, legal information and contact information. + +Nowadays, since the rise of mobile devices like tablets and smartphones, websites quite often look different depending on the screen size. +On a smartphone, the navigation is often contracted into a single icon that expands when the user touches it. +Also, the "left" and "right" areas may be shown after the "main" area when using a smartphone. + +This technique is known as *responsive design*, and can be implemented using Plone. +The default theme for Plone 5 uses this method already. + +What does a Plone web site look like? + +Traditionally, the out-of-the-box look is like that shown at the top of this page, with header, menu, columns, and a footer. + +But using the flexible "Diazo" theme engine of Plone, each aspect can be made to look any way the designer chooses, and can also be shown different depending on the device of the visitor. + +% _content-type-icons-intro + +## Content Type Icons + +**Icons** are used to highlight actions, options etc. in menu bars, property sheets and the like: + +```{image} icons.png +:align: center +:alt: Icons used in Plone user interface +``` + +Furthermore **icons** can be used to help to visually identify **content types** in any kind of listing or tables. +For the content type *File* mime type icons are used to visualize the format of the given file. + +This feature is adjustable to a very high degree. There are default settings which can be configured in the {doc}`Site Configuration panel </adapt-and-extend/config/site>`. +This default settings can be overidden for each content item (edit: settings) or portlet respectively. + +```{image} icons2.png +:align: center +:alt: Content type icons +``` + +## Preview Images (aka Thumbnails, Thumbs) + +**Preview Images (or thumbnails, thumbs)** for image items or any other content items which have a lead image +(or teaser image) can be shown in any listing or table. +Additional to the same configuraion options for icons above you can define default sizes for the preview images for, tables, lists or portlets and also overwrite these settings individually. + +```{image} thumbs-example-1.png +:align: center +:alt: 'Example: preview images and icons with different settings' +``` + +Depending on the default settings for table views the content view of a folder will show preview images or not: + +```{image} contents-with-thumbs-suppressed.png +:align: center +:alt: 'Example: content view with thumbs not shown' +``` + +```{image} contents-with128x128.png +:align: center +:alt: 'Example: content view with thumbs shown' +``` + +The second option (here with image size set to 128x128) is very handy whenever you need to rearrange a big number of images whith mkore or less meaningless title. diff --git a/docs/guides/classic-ui/working-with-content/logging-in.md b/docs/guides/classic-ui/working-with-content/logging-in.md new file mode 100644 index 000000000..1478a3592 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/logging-in.md @@ -0,0 +1,29 @@ +# Logging In + +What to expect when you log in to a Plone site + +When you visit a Plone web site anonymously, or are given the web address for site maintenance, you'll see a *log in* button in the top-right corner like this: + +```{figure} login-link.png +:align: center +:alt: login link +``` + +```{note} +Your site administrator may have *hidden* the login link, in which case you can go directly to a URL she or he has provided. +``` + +After clicking the *log in* link, you'll see an input panel where you can type in your user name and password: + +```{figure} login-popup.png +:align: center +:alt: login link +``` + +After logging in to a Plone web site you will see some indication of your name, as the last item on the {term}`toolbar`. +You can click on your name to perform some actions related to your user, covered in the following sections. + +You (or the site administrator) can allow users to use their email address as login name. +This feature can be switched on in the Security settings control panel. +The effect is that on the registration form no field is shown for the user name. +On the login form the user is now asked to fill in an email address. diff --git a/docs/guides/classic-ui/working-with-content/login-link.png b/docs/guides/classic-ui/working-with-content/login-link.png new file mode 100644 index 000000000..7690a58f7 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/login-link.png differ diff --git a/docs/guides/classic-ui/working-with-content/login-popup.png b/docs/guides/classic-ui/working-with-content/login-popup.png new file mode 100644 index 000000000..c7a79294c Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/login-popup.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/automatic-locking-and-unlocking.md b/docs/guides/classic-ui/working-with-content/managing-content/automatic-locking-and-unlocking.md new file mode 100644 index 000000000..fe256dff8 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/automatic-locking-and-unlocking.md @@ -0,0 +1,14 @@ +# Automatic Locking and Unlocking + +Plone gives you a locking message that will tell you that a document was locked, by whom, and how long ago - so you won't accidentally stomp on somebody else's changes. + +When somebody clicks on the Edit tab, that item immediately becomes locked. +This feature prevents two people from editing the same document at the same time, or accidentally saving edits over another user's edits. + +If a user leaves the edit page without clicking Save or Cancel, the content locking will remain effective for the next ten minutes after +which time, the locked content item becomes automatically unlocked. + +This timeout feature is important for some browsers that do not execute the "on-unload" javascript action properly, such as Safari. +Should you desire to disable locking, go to the Plone control panel (Site Setup -> Site) and uncheck *Enable locking for through-the-web edits*. + +Finally, users with the role "Site-Admin" can override the lock and unlock it. diff --git a/docs/guides/classic-ui/working-with-content/managing-content/content-history.png b/docs/guides/classic-ui/working-with-content/managing-content/content-history.png new file mode 100644 index 000000000..f0fd37a6b Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/content-history.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/contentrules-add.png b/docs/guides/classic-ui/working-with-content/managing-content/contentrules-add.png new file mode 100644 index 000000000..016f7fe40 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/contentrules-add.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/contentrules-assign.png b/docs/guides/classic-ui/working-with-content/managing-content/contentrules-assign.png new file mode 100644 index 000000000..1e8a52d5b Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/contentrules-assign.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/contentrules-conditions.png b/docs/guides/classic-ui/working-with-content/managing-content/contentrules-conditions.png new file mode 100644 index 000000000..c03f5ed99 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/contentrules-conditions.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/contentrules-start.png b/docs/guides/classic-ui/working-with-content/managing-content/contentrules-start.png new file mode 100644 index 000000000..96d34152c Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/contentrules-start.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/contentrules.md b/docs/guides/classic-ui/working-with-content/managing-content/contentrules.md new file mode 100644 index 000000000..6f1d4e89f --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/contentrules.md @@ -0,0 +1,221 @@ +# Using Content Rules + +This tutorial discusses what content rules are and how to configure and use them. + +## Helicopter view + +Content Rules are a powerful mechanism to automate dealing with content. + +There are several steps, that follow one another: + +**Define the rule** + +1. create and name a new rule, specifying what triggers it to be executed +2. then narrow it down, by using conditions, to execute only on the content items you want +3. and select the action or actions that should be taken + +Afterwards, you end up with a ready-to-go, named Content Rule. But by default it will not execute yet; there is one more step to take: + +**Apply it** to a portion of your site. Or to the whole site, if you so choose to. + +Why is the setting up of a Content Rule separated from the application? Because you may want to have different content rules applied to different parts of your site. + +## Triggers, conditions, actions + +A general overview what makes up a content rule, some sample use cases, and who can set up and use content rules. + +**What is a content rule?** + +A content rule will automatically perform an action when certain events (known as "triggers") take place. + +You can set up a content rule to send an email (the action) whenever certain (or any) content is added to a specific folder (the trigger). + +**Other use cases for content rules** + +- Move content from one folder to another when that content item is published +- Send email when a content item is deleted +- Delete content after a certain date + +**Who can set up and use content rules?** + +Site Manager permissions are required to in order to set up and apply content rules. + +**What are the triggers, conditions and actions that come with Plone 5.0?** + +The following general **triggers** are available by default: + +- Comment added +- Comment removed +- Comment reply added +- Comment reply removed +- Object added to this container +- Object copied +- Object modified +- Object removed from this container +- User created +- User logged in +- User logged out +- User removed +- Workflow state changed + +These triggers can be made more specific by using **conditions** + +The following general **conditions** are available by default: + +- Content type: the type has to be one or more specific ones, like a Page or News Item +- File extension: do only for type .PDF, for instance +- Workflow state: only act on unpublished items, for instance +- Workflow transition: only act when an item is being published +- User's Group: only act when one of the "Sports Team" members logs in +- User's Role: only act when a Site Administrator logs in +- TALES expression: an advanced, programmable condition. + +The following **actions** are available by default: + +- Logger - make an entry in the event log +- Notify user with an information, warning, or error message +- Copy to folder +- Move to folder +- Delete object +- Transition workflow state +- Send email + +```{note} +Content Rules are extendable. + +There are add-ons available that will create new actions, conditions or triggers, and you can also write your own. +``` + +## Creating and Defining Content Rules + +How to define content rules using the triggers and actions included in Plone + +### Creating a Rule + +Content rules are created globally through the Plone Control Panel ("Site Setup" link) and then selected from the Rules tab for the desired folder (or at the Plone site root if you want the rule applied site-wide). + +In this example, you're going to create a content rule that will send an email any time a Page type is modified. + +> - Click on "Content Rules" from the Site Setup page +> - The first option, "Disable Globally", allows you to disable ALL content rules. This is the emergency brake, for when you have created rules that are not doing what you want. +> - In the second section of the main page for Content Rules is where any existing content rules will be listed. There are also some checkboxes to filter them, which can be useful if there are many rules defined. + +```{figure} contentrules-start.png +:align: center +:alt: Content Rules overview +``` + +If no content rules exist, the only option is an "Add content rule" button. Click that. + +An "Add Rule" form comes up. Enter a descriptive title -- for this example, use: "Send Email when any Page is Modified". Enter a description if desired. + +For the "Triggering event" select "Object modified". Leave "Enabled" checked, and "Stop executing rules" and "Cascading rule" unchecked. + +```{figure} contentrules-add.png +:align: center +:alt: Content Rules overview +``` + +Click the "Save" button. At this point, you have essentially created a "container" for the content rule. + +Next you'll further define the trigger and actions for this rule. + +```{figure} contentrules-conditions.png +:align: center +:alt: Content Rules conditons and actions +``` + +## Defining conditions and actions + +After creating a content rule, you need to actually define the specific conditions of the trigger and actions that will occur based on those conditions. + +**For the condition:** + +> - By default, "Content type" is selected and since you want a trigger only for Pages, click on the "Add" button. +> - From the "Add Content Type Condition" page, select "Page" and click on "Save" + +**For the action:** + +> - Select "Send email" from the drop down menu and click on the "Add" button. +> - From the "Add Mail Action" page, fill out the form: +> - For the "Subject" enter: "Automated Notification: Page Modified" +> - "Email source" is the From: address and is optional +> - "Email recipients" is the To: address; enter a valid email address +> - For the "Message" enter what you want for the body of the email + +- Click the "Save" button + +Congratulations, you have created a working content rule! + +In the next section, you'll learn how easy it is to apply this content rule to any part (or all) of your Plone site. + +## Assigning a Content Rule + +Now that you've set up a content rule, how does it actually get used? + +At this point, you have successfully created a content rule. However, this content rule isn't actually in use until it has been assigned and enabled on one or more folders. + +- Navigate to the folder where you want the content rule to be in effect. + This can be any folder on the Plone site or it can be for the entire Plone site ("Home"). + In this example we're going to the "News" folder. +- Click on the "Rules" tab. From there you will see a drop down menu of possible content rules: + +```{figure} contentrules-assign.png +:align: center +:alt: assign content rules +``` + +- Select the desired content rule ("Send Email..." in this example) and click on the "Add" button. +- By default, the rule has now been applied to the current folder only as indicated by the symbol in the "Enabled here" column indicates. + +There will be several buttons near the bottom. + +Tick the check box for the rule you want ("Send Email...") and then click on either "Apply to subfolders" button. + +Now this content rule will also apply to any subfolder that exist now or are created in the future. + +If you wish to have this rule apply to all the subfolders but not to the current folder, then tick the check box next to the rule and click on the "Disable" button. + +```{note} +The "Enabled here" column is empty for this rule now. + +You will need to explicitly use the "Enable" button to re-active this rule for the current folder; +using the "Apply to current folder only" button will **NOT** re-enable the content rule. + +The `Apply to subfolders` and `Apply to current folder only` can be thought of as toggles. + +You can test this rule now by creating a new Page or modifying an existing Page. + +Once you click on `Save` for that Page, an email will be sent. +``` + +## Managing Multiple Rules + +For each rule, you can define if additional rules should be applied after it, or if it is the end of the pipeline. + +Furthermore, you can specify if you want rules to be *cascading* or not. + +An example: the first ContentRule is triggered for a content item, which is then moved to a folder. But, in this folder, another ContentRule is active, which will operate on any new content item that gets moved into that folder. *Cascade* means that yes, the second rule should be applied. + +```{note} +It is entirely possible to create never-ending loops this way: Rule1 moves newly published files in Folder1 to Folder2. + +But Rule2, which is active in Folder2, unpublishes any newly moved files, and then copies them into Folder1. And so it goes round and round... + +Be careful when using cascading rulesets! +``` + +### "Navigating" with assigned content rules + +The "Edit Content Rule" page uses a 'related items' like display ("Assignments") for listing all the locations where the rule is assigned. +From there, you can go directly to that folder's Rules tab by clicking on the Title of that folder. + +Note that there is no indication in the Assignments section if the Rule is applied to subfolders or not. + +If you're on a folder that has the rule assigned to it directly (e.g. it's NOT a subfolder of a folder that has the rule assigned), +you can get directly to the "Edit Content Rule" page from the Rules tab by clicking on the Title of that rule (which is always a link). + +Alternately, if you're on a folder that has the rule assigned from a folder higher up in the hierarchy, +clicking on the rule Title link will take you to the folder's Rules tab where the rule has been explicitly assigned. + +If from the Rules tab, a rule is listed at active, then the assignment of that rule is being managed from a parent folder. diff --git a/docs/guides/classic-ui/working-with-content/managing-content/cutting-copying-and-pasting-items.md b/docs/guides/classic-ui/working-with-content/managing-content/cutting-copying-and-pasting-items.md new file mode 100644 index 000000000..04b889995 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/cutting-copying-and-pasting-items.md @@ -0,0 +1,33 @@ +# Cutting, Copying and Pasting Items + +Cut, copy, and paste operations involve moving one or more items from one folder to another. + +## Cut/Paste + +Moving items from one area to another on a website is a common task. + +It may be that you, or someone else, has created the item in the wrong place. +Or, as time goes by, you decide that reordering content will make your site easier to use, for instance in an intranet when projects and their associated files get transferred to another department in the organisation. + +Whatever the reason, Plone makes it easy to transfer individual content items, or even whole folders containing hundreds of items, to another location. All internal links will still work. Plone will even redirect external links (where other websites have linked to this content item directly) in most cases. This mechanism can break, however, if you create a new item with the same title and same location as the one you moved. + +The easiest way to move content is by using "Contents" on the Toolbar. + +```{figure} foldercontents-cutpaste.png +:align: center +:alt: cutting and pasting content +``` + +You see an overview of all content in the folder, and in this screenshot that is the content in the top-level or *root* of the site. + +You can select individual items, and then use the "Cut" button to cut them. A message "Successfully cut items" will be shown, but the content will still be visible! + +Now you can navigate to the folder where you want the content to be, and press the "Paste" button. Only then will the actual moving take place. + +The *paste* button remains active, because you would be allowed to continue pasting the content you cut into other places if you wanted. +This could happen in several situations, including when you need to copy one page, for example, as a kind of template or basis document, into several folders. + +## Copy/Paste + +A *copy*/*paste* operation is identical to the *cut*/*paste* operation, except that there is no removal of content from the original folder. It works as you would expect it to work: the original content remains. +If you copy and then paste into the same folder, the (now doubled) new copy of the content will get an automated *short name* of something like "copy_of_originalitem", which you will most likely want to correct by using the "Rename" button. diff --git a/docs/guides/classic-ui/working-with-content/managing-content/deleting-items.md b/docs/guides/classic-ui/working-with-content/managing-content/deleting-items.md new file mode 100644 index 000000000..e474ea4db --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/deleting-items.md @@ -0,0 +1,21 @@ +# Deleting Items + +Items may be deleted from a folder with ease. + +Sometimes it is necessary to delete a content item. Again, the easiest way to do this is by using "Contents" on the Toolbar. + +```{figure} foldercontents-delete.png +:align: center +:alt: deleting content +``` + +Simply select the content item(s) you want to delete, and press the "Delete" button. + +Entire folders may be deleted, so care must be taken with the delete operation! + +Plone will warn you if there are other content items in your site that link to the one you are deleting, and will offer to open those in a separate window so you can edit them. + +```{note} +Plone's database will keep a record of deleted items, and in many cases your site administrator will be able to undo an accidental delete. +However, this will only work if there haven't been many site edits after the delete operation, so if you accidentally delete content, it is important to act soon. Careful site administrators will also have regular backups of the entire site, but getting your content back from there will involve more work. An alternative to deleting content is to 'un-publish' it, so it isn't available to outside visitors anymore. +``` diff --git a/docs/guides/classic-ui/working-with-content/managing-content/display-menu.png b/docs/guides/classic-ui/working-with-content/managing-content/display-menu.png new file mode 100644 index 000000000..243004657 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/display-menu.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/edit-page.png b/docs/guides/classic-ui/working-with-content/managing-content/edit-page.png new file mode 100644 index 000000000..34a6d0b9e Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/edit-page.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/editing-content.md b/docs/guides/classic-ui/working-with-content/managing-content/editing-content.md new file mode 100644 index 000000000..57242e8c9 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/editing-content.md @@ -0,0 +1,29 @@ +# Editing Content + +Editing Plone content works the same as adding content -- usually the data entry and configuration panels for the content are the same for editing as for adding. + +Of course, when we edit an item of content, the item already exists. +Click "Edit" on the toolbar when you are viewing it, and you will see the data entry panel for the item, along with the existing values of the item's data. + +For an example of something really simple, where editing looks the same as adding, we can review how to edit the default frontpage on a new Plone site. + +The *Edit* panel for a Page shows the title, description and text areas. + +```{note} +If you do wish to give a description, which is a generally a good idea, the description can be text only -- there is no opportunity for setting styling of text, such as bold, italics, or other formatting. This keeps the descriptions of Plone content items as simple as possible, and is also required by the {term}`Dublin Core` standard. +``` + +```{figure} edit-page.png +:align: center +:alt: Editing a page +``` + +That's it. Change what you want, for instance changing the description or the content, and save. +The content item will be updated in Plone's storage system. +You can repeatedly edit content items, just as you can repeatedly edit files on your local computer. + +```{note} +Note that there is an extra field, called **Change Note**. +Here you can write a short message on why you were editing this, like "updated with our new company motto". +That note will normally not be shown on a public website, but is available for your co-workers to see when they look at the history of a content item. +``` diff --git a/docs/guides/classic-ui/working-with-content/managing-content/folder-contents.md b/docs/guides/classic-ui/working-with-content/managing-content/folder-contents.md new file mode 100644 index 000000000..07289c8bb --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/folder-contents.md @@ -0,0 +1,113 @@ +--- +substitutions: + columns: |- + ```{image} foldercontents-columns.png + ``` + copy: |- + ```{image} foldercontents-copy.png + ``` + cut: |- + ```{image} foldercontents-cut.png + ``` + delete: |- + ```{image} foldercontents-delete.png + ``` + paste: |- + ```{image} foldercontents-paste.png + ``` + properties: |- + ```{image} foldercontents-properties.png + ``` + rearrange: |- + ```{image} foldercontents-rearrange.png + ``` + rename: |- + ```{image} foldercontents-rename.png + ``` + searchbox: |- + ```{image} foldercontents-searchbox.png + ``` + selected: |- + ```{image} foldercontents-selected.png + ``` + state: |- + ```{image} foldercontents-state.png + ``` + tags: |- + ```{image} foldercontents-tags.png + ``` + upload: |- + ```{image} foldercontents-upload.png + ``` +--- + +# Folder Contents + +The Contents item on the Toolbar shows a list of items in a folder. +It is the place for simple item-by-item actions and for bulk actions such as copy, +cut, paste, move, reorder, etc. + +The Contents tab for folders is like "File Manager" or "My Computer" system utilities in Windows and Linux desktops and the "Finder" in Mac OS X, with similar functionality. + +```{figure} foldercontents.png +:align: center +:alt: folder contents +``` + +The general method is to select one or more items, by checking the checkbox in front of their name, and then performing the desired operation. + +*Shift-clicking* to select a range of items works. +This could be very handy for a folder with more than a dozen items or so, and would be +indispensable for folders with hundreds of items. + +Let's go over the possibilities one by one: + +{{ columns }} + +The first icon lets you select the columns to show. This can help you find the right content. + +{{ selected }} + +The second item in the horizontal bar shows how many items you have selected. + +{{ rearrange }} +Press **"Rearrange"** to sort all items in the folder, for instance alphabetically on their title, or chronologically by `creation date`, `published date` or `date last modified`. + +```{warning} +Be careful when using this option, especially in the root of the site. As folders get re-arranged, it will change the order of the navigation tabs in your site. +``` + +{{ upload }} + +**"Upload"** allows you to upload one or more files (like images or PDF's) from your computer. + +{{ cut }} - {{ copy }} - {{ paste }} + +**"Cut"**, **"Copy"** and **"Paste"** do what you {doc}`expect them to do <cutting-copying-and-pasting-items>`. + +{{ delete }} + +The **"Delete"** button has a red color, since this is a potentially {doc}`dangerous operation <deleting-items>`. + +{{ rename }} + +> **Rename** will open up a form where you can change the Title and the *short name* for an item. The **Title** can be anything you like, but the **short name** is part of the URL. That means you have to abide by certain rules: + +- it cannot contain any spaces or special characters like * or \\. When you create an item, Plone generates a safe *short name* from the Title, but when you change this later you should take care this remains a valid URL. +- it has to be unique in a folder. You can have two items with the same Title (although it would be confusing), but you cannot have two items with the same *short name* within the same folder. It's perfectly fine to have the same *short name* being used in different folders. + +{{ tags }} + +> **Tags** allows you to set tags on several items in bulk. This can be a real time-saver. + +{{ state }} + +**State** will allow you to change the workflow state of one or more items, such as *publishing* them. See the {doc}`chapter on collaboration and workflow </working-with-content/collaboration-and-workflow/index>` for in-depth information. + +{{ properties }} + +With the **Properties** button you can set things like the *Publication Date*, *Expiration Date*, copyright and other metadata on your content items. + +{{ searchbox }} + +And finally, use the Query searchbox to locate content items, if you know (part of) the title or any other identifier. This is a very quick way to get to content items in folders with hundreds or thousands of items. diff --git a/docs/guides/classic-ui/working-with-content/managing-content/folder-view.md b/docs/guides/classic-ui/working-with-content/managing-content/folder-view.md new file mode 100644 index 000000000..192256afa --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/folder-view.md @@ -0,0 +1,81 @@ +# Folder View + +Folders have the "Display" item on the Toolbar, which controls the different ways of showing folder contents. + +```{figure} display-menu.png +:align: center +:alt: Display menu +``` + +For most content items, if you want to change how it looks, you edit the content directly. +But folders are a different animal. +As containers of other items, folders can display their contents in a variety of ways. + +Plone by default comes with these displays: + +Standard view + +: A basic list of contained items, showing their title, description, modification date and icon. + (The icon and the modification date may or may not be shown to anonymous visitors, depending on your site settings) + +Summary view + +: A slightly nicer view, showing the Title and Description and a 'Read more' link for each content item. If the contained items have a 'Lead Image' declared, like the standard News Item, it will show a thumbnail of that image as well. + +Tabular view + +: Compact view, as a table, of the contained items. + +All content + +: This displays the full content of each contained item. This can quickly get very long, and is best used only on folders with a small number of items in them, and where each item is in itself not too long. An example could be a list of Frequently Asked Questions, or FAQ. + +Album view + +: This view is meant for folders with images in them, it shows a thumbnail for every content item. + +Event Listing + +: Designed to give a nice overview of a series of Events. + +And often the most useful, yet also more difficult to understand: + +**"Select a content item as default view"** + +```{note} +The standard folder views are often used as the starting point for more elaborate views, that will reflect the purpose of the website. +At the very least, these views are often customized with CSS or {term}`Diazo` rules, to show specific information about the content types shown. Many add-ons will provide extra folder views, to properly display any special content items that these add-ons provide. Some widely used add-ons provide a so-called 'faceted search' display, which is designed to quickly find your way around large numbers of content. + +Therefore, you will likely see more possibilities in this menu if you are working on a real-life site. +``` + +## Setting an Individual Content Item as the View for a Folder + +The basic list view functionality described above for folders fits the normal way we think of folders -- as containers of items -- but Plone adds a nice facility to set the view of a folder to be that of any single item contained within the folder. + +You can set the display view for a folder to show a single page, which can be useful for showing an 'introductory page', which you or others have created to explain the purpose of this section of the site, and which contains links to sub-sections and other documents. + +Or, you can set it to a *"collection"*, which on its own is already a powerful content filter. One common use-case, and one that is used in a default Plone site, is to have a Folder called "News". In it, there are individual News items, but also a Collection which will sort all of these news items so the most recent one is shown first. + +You would then set the "most recent" collection as the default view of the "News" folder. Using the same 'Display' menu, you can then set the display view for the "most recent" to be the "Summary view" + +## A word of warning + +Setting the default view of a folder to be one of the items contained in that folder, is one of the most powerful features of Plone. + +But the very fact that you can select for instance a 'Collection', which in term displays a whole number of items, as that default item, can also be confusing. + +This will play a role when you edit a Folder, which has a content item set as its default view. Or when you want to manage the portlets for a Folder which has a content item set as its default view. Or when you are trying to give {doc}`sharing permissions </working-with-content/collaboration-and-workflow/collaboration-through-sharing>` on a folder, but by accident are only setting them on the default item in that folder. + +Plone will display a message in these cases, along the lines of "You are editing the default view of a container. If you wanted to edit the container itself, go *here*." + +**Learn to not ignore, but read those messages!** + +Remember: when setting properties, ask yourself the question: *do I want to do this on the Folder, or just on this one content item that is contained in the Folder?* + +Lastly, the display view setting should be used with care, because it can do two things: + +- It changes the behavior of folders, from acting as simple containers to acting as direct links to content, if you select an individual content item as default view. +- Changing the view can radically alter the way the information is presented to users. If you select "Album view" on a folder with no images, it may appear the content is gone, since there are no images to show, although of course the information is still there. Or your perfectly written introductory page is suddenly replaced by a boring tabular display. + +While the "Display" menu is one of the most powerful features of Plone, it is wise to note for yourself which was the previous view - before you change it - so you can quickly change it back when needed. diff --git a/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-columns.png b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-columns.png new file mode 100644 index 000000000..368c78613 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-columns.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-copy.png b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-copy.png new file mode 100644 index 000000000..5bdfcb95e Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-copy.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-cut.png b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-cut.png new file mode 100644 index 000000000..6dcbef24e Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-cut.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-cutpaste.png b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-cutpaste.png new file mode 100644 index 000000000..042b7d7b8 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-cutpaste.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-delete.png b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-delete.png new file mode 100644 index 000000000..bc60126c0 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-delete.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-paste.png b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-paste.png new file mode 100644 index 000000000..cb894a1f0 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-paste.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-properties.png b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-properties.png new file mode 100644 index 000000000..0e9ffd841 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-properties.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-rearrange.png b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-rearrange.png new file mode 100644 index 000000000..f8ec75498 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-rearrange.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-rename.png b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-rename.png new file mode 100644 index 000000000..2fab2e371 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-rename.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-reorder.png b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-reorder.png new file mode 100644 index 000000000..db8ed0318 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-reorder.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-searchbox.png b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-searchbox.png new file mode 100644 index 000000000..e7f514b14 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-searchbox.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-selected.png b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-selected.png new file mode 100644 index 000000000..a41629471 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-selected.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-state.png b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-state.png new file mode 100644 index 000000000..f2649010d Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-state.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-tags.png b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-tags.png new file mode 100644 index 000000000..2ac53a321 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-tags.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-upload.png b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-upload.png new file mode 100644 index 000000000..0ea2719d9 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents-upload.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/foldercontents.png b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents.png new file mode 100644 index 000000000..db8ed0318 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/foldercontents.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/index.md b/docs/guides/classic-ui/working-with-content/managing-content/index.md new file mode 100644 index 000000000..a547ad0f8 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/index.md @@ -0,0 +1,21 @@ +# Managing Content + +The contents tab is the place where content items can be copied, cut, +pasted, moved, renamed, etc. + +```{toctree} +:maxdepth: 2 + +editing-content +cutting-copying-and-pasting-items +folder-view +folder-contents +reordering-items +previous-next-links +deleting-items +automatic-locking-and-unlocking +versioning +working-copy +contentrules +ploneformgen/index +``` diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/add-new-item-form-folder.png b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/add-new-item-form-folder.png new file mode 100644 index 000000000..4a0a3867e Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/add-new-item-form-folder.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/basic-form.png b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/basic-form.png new file mode 100644 index 000000000..1b1e226c5 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/basic-form.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/captcha.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/captcha.md new file mode 100644 index 000000000..8b75409eb --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/captcha.md @@ -0,0 +1,34 @@ +# Adding CAPTCHA Support + +```{admonition} Description +PloneFormGen has built-in support for Re-Captcha. This how-to tells you how to enable it. +``` + +## PloneFormGen and CAPTCHA Fields + +When PFG is installed in a Plone instance via add/remove products, it will look for evidence that either collective.captcha or collective.recaptcha are available. If that's found, the CAPTCHA Field will be added to the available field list. + +If you are using collective.recaptcha, you need to take the additional step of setting your public/private keypair. You get these by setting up an account at recaptcha.net. The account is free. You may specify your keypair in the PFG configlet in your site settings. + +```{note} +If you add a captcha facility *after* installing PFG, you will need to reinstall PFG (via add/remove products) to enable captcha support. +``` + +## Installing collective.recaptcha + +Add the following code to your buildout.cfg to install collective.recaptcha and Products.PloneformGen together: + +```ini +[buildout] +... +eggs = + Plone + ... + collective.recaptcha + Products.PloneFormGen + ... +``` + +- Re-run bin/buildout and relaunch your zope/plone instance. +- Open the PortalQuickinstaller or plone control panel and install (or reinstall if already installed) PloneFornGen. +- Open the PloneFormGen configlet in the Plone control Panel and fill in the fields with your Public and Private Keys of your ReCaptcha Account. Obtain keys from [reCaptcha.net](https://www.google.com/recaptcha/intro/invisible.html). diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/creating-the-form-title-description.png b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/creating-the-form-title-description.png new file mode 100644 index 000000000..5a4d69be2 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/creating-the-form-title-description.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/creating_content.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/creating_content.md new file mode 100644 index 000000000..081c20b86 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/creating_content.md @@ -0,0 +1,80 @@ +# Creating Content From PFG + +```{topic} Description +> This how-to covers simple creation of portal content from PloneFormGen. We'll create web pages from sample form submissions. + +A question that's come up frequently on Gitter and the Plone forum is "How do I create an event, news item, page, or some other content item from PloneFormGen? It's common that there's some security need or extra content needed that prevents just using Plone's "add item." +``` + +This is actually very easy if you know a little Python and are willing to learn something about the content items you want to create. + +Please note that I'm not going to show you how to create new content types here. Just how to use PFG to create content objects from existing types. If you want to create new content types, learn to use Dexterity. + +Your first step should be to determine the attributes you want to set in the new content item and how they'll map from your form fields. + +In this case, we're going to use the sample contact form created when you first create a form folder to create a page (Document). + +Our mapping of form fields to content attributes will look like this: + +| Form Field | Document Attribute | +| ----------------------------- | ------------------ | +| Your E-Mail Address (replyto) | Description | +| Subject (topic) | Title | +| Comments (comments) | Body text | + +Note that for each form field, we've determined its ID in the form. We'll use those to look up the field in the form submission. + +Next, we need to learn the methods that are used to set our attributes on a Document object. How do you learn these? It's always nice to read the source, but when I'm working fast, I usually just use DocFinderTab and look for "set\*" methods matching the attributes. + +Now, determine where you want to put the new content. That's your target folder. It's convenient to locate that folder in a parent folder of the form object, as you may then use the magic of acquisition to find it without learning how to traverse the object database. + +Now, in the form folder, we add a "Custom Script Adapter" - which is just a very convenient form of Python script. Then, just customize the script to look something like the following: + +```python +# Find our target folder from the context. The ID of +# our target folder is "submissions" +target = context.submissions + +# The request object has a dictionary attribute named +# form that contains the submitted form content, keyed +# by field name +form = request.form + +# We need to engineer a unique ID for the object we're +# going to create. If your form submit contained a field +# that was guaranteed unique, you could use that instead. +from DateTime import DateTime +uid = str(DateTime().millis()) + +# We use the "invokeFactory" method of the target folder +# to create a content object of type "Document" with our +# unique ID for an id and the form submission's topic +# field for a title. +target.invokeFactory("Document", id=uid, title=form['topic']) + +# Find our new object in the target folder +obj = target[uid] + +# Set its format, content and description +obj.setFormat('text/plain') +obj.setText(form['comments']) +obj.setDescription(form['replyto']) + +# Force it to be reindexed with the new content +obj.reindexObject() +``` + +That's it. This will really work. + +## Security + +At the moment, the person that submits your form will need to be logged in as a user that has the right to add pages to the target folder, then change their attributes. You may need to allow other users (even anonymous ones) to submit the form. That's where the Proxy role setting of the custom script adapter comes in. You may change this setting to Manager, and the script will run as if the user has the manager role - even if they're anonymous. + +I hope it's obvious that you want to be very, very careful writing a script that will run with the Manager role. Review it, and review it again to make sure it will do only what you want. Never trust unchecked form input to determine target or content ids. + +If I'm doing this trick with a form that will be exposed to the public, I often will use a Python script rather than the custom script adapter, as it allows me to determine the proxy role for the script more precisely than choosing between None and Manager. I may even create a new role with minimal privileges, and those only in the target folder. +Credit! + +```{note} +A big thank's to Mikko Ohtamaa for contributing the Custom Script Adapter to PloneFormGen. +``` diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/custom_addons.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/custom_addons.md new file mode 100644 index 000000000..a7234a212 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/custom_addons.md @@ -0,0 +1,20 @@ +# Adding Custom Fields, Action Adapters or Thanks Pages + +```{admonition} Description +You may add custom fields, action adapters and thanks pages +to PloneFormGen. By far the easiest way to do this is to derive +a subclass from one of the field types in fieldsBase or an +action adapter from actionAdapter.FormActionAdapter. +``` + +When PFG is installed, or reinstalled, it will automatically add +to its available fields, adapters and thanks pages list any installed +Archetypes content type that implements one of: + +- Products.PloneFormGen.interfaces.actionAdapter.IPloneFormGenActionAdapter +- Products.PloneFormGen.interfaces.field.IPloneFormGenField +- Products.PloneFormGen.interfaces.thanksPage.IPloneFormGenThanksPage + +Also, the Archetypes class *must* specify a meta_type in the class definition +that matches the meta_type defined in its GS type declaration. Otherwise, it +won't be found. diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/custom_mailer.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/custom_mailer.md new file mode 100644 index 000000000..bcf9b68f2 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/custom_mailer.md @@ -0,0 +1,71 @@ +# Custom mailer script + +```{admonition} Description +Customizing email output from PloneFormGen +``` + +## Introduction + +Below is an email script example to customize how PloneFormGen generates the email output. + +## Installation instructions + +Go to form, on the contents tab remove the existing Mailer item. + +Choose create new... Custom script adapter. Pick any name. + +For the script, set Proxy role: Manager. + +Fix the email addresses in the script below. + +Paste the code to the script body field. + +Save. + +Test. + +## Example script + +``` +from Products.CMFCore.utils import getToolByName + +mailhost = getToolByName(ploneformgen, 'MailHost') + +subject = "Email subject" + +# Use this logger to output debug info from this script if needed +import logging +logger = logging.getLogger("mailer-logger") + + +# Create a message body by appending all the fields after each another +# This includes non-functional fields like labels too +message="" +for field in ploneformgen.fgFields(): + label = field.widget.label.encode("utf-8") + value = str(fields[field.getName()]) + + # For non-functional fields draw a custom separator line + if not field.widget.blurrable: + value = "-------------------------------" + + # Format lists on the same row + try: + if (value[0] == "["): + value = value.replace("'", "")[1:-1] + except IndexError: + # Skip formatting on error + pass + + #remove last ':' from label + if (label[-1] == ":"): + label = label[0:-1] + + message += label + ": " + value + "\n\n" + + +source = "noreply@example.com" +receipt = "info@example.com" + +mailhost.send(message, receipt, source, subject=subject, charset="utf-8", ) +``` diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/custom_thanks.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/custom_thanks.md new file mode 100644 index 000000000..9a950727f --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/custom_thanks.md @@ -0,0 +1,23 @@ +# Customizing an individual thanks page + +```{admonition} Description +It's not hard to customize the thanks page for an individual form. +This trick is particularly useful for purposes like adding 'pay now' buttons. +``` + +If you can tolerate a little work in the Management Interface, you'll find it very easy to customize the Thanks Page for an individual form. + +The steps: + +1. Create your form; +2. Bring up the Management Interface; navigate to portal_skins/PloneFormGen; +3. Open the fp_thankspage_view template; push the Customize button; this puts an editable copy of the thanks page template in your custom skin folder. +4. Step back to the Custom folder listing (still in the Management Interface); cut the fp_thankspage_view template; +5. Navigate to your form folder; paste it there. +6. Edit the template to insert your Pay/Donate Now form and button code, or whatever other custom code you might need just for this form. + +> ```{note} +> Note: If there is already an fp_thankspage_view template in your custom skin folder +> (perhaps because you've already customized the template for the site), +> you'll be cutting and pasting a new copy. +> ``` diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/custom_validators.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/custom_validators.md new file mode 100644 index 000000000..986d66468 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/custom_validators.md @@ -0,0 +1,125 @@ +# Creating custom validators + +```{admonition} Description +PloneFormGen allows you to create a custom field-input validator by specifying a TALES expression that will be used to validate input when it's submitted. +This how-to explains what that means, and offers a few examples. +``` + +`Template Attribute Language Expression Syntax` (TALES) is a simple notation that allows determination of a value via path (as in path/to/object), string or Python expressions. +It is used in `Zope's Template Attribute Language` (TAL), and is ubiquitous in Plone templates. +This how-to does not teach you TALES; for that, try the [Zope Page Templates Reference](https://docs.zope.org/zope2/zope2book/AppendixC.html). + +```{warning} +Please note that it's easy to make a mistake when working with TALES fields that will cause an error when you try to display your form. +Take note of the error message, and return to the field edit form to fix it. Don't be scared of this kind of error. +``` + +The rules for writing a validator are: + +- You should validate against the the variable value, which will contain the field input. Note that -- for simple fields -- value will be a string. But, for a lines field, the contents of value will be a list. +- Return False or zero if you wish to accept the input. +- Return a string containing a user-feedback message if you don't wish to accept the input. +- Don't change the value variable. It won't do you any good. + +## Example + +Let's say that you are operating a restaurant that serves only dishes containing spam. +You may wish to check to make sure that the input to a string or text field contains "spam". +You may do that with by setting a custom validator that reads: + +``` +python: 'spam' not in value and 'Input must include spam.' +``` + +The odd logic comes from the need to return `False` for valid input. +Look at a couple of examples of validation in action with literal strings. +Remember, we want to force spam on the user: + +```pycon +>>> 'spam' not in "eggs, eggs, bacon" and 'Input must include spam.' +'Input must include spam.' + +>>> 'spam' not in "eggs, eggs, bacon and spam" and 'Input must include spam.' +False +``` + +## The name space + +Here are the objects available when your expression is evaluated. + +### TALES context + +value + +: The field input. + +here + +: The current object. A bit dangerous since this varies depending on context. + +folder + +: This will be your form folder. + +portal + +: The portal object. + +request + +: The REQUEST object. Note that request/form contains form input. + +member + +: The authenticated user's member data -- if any. + +nothing + +: Equivalent to Python None. + +folder_url + +: URL of the form folder. + +portal_url + +: URL of the site. + +modules + +: Module importer. + +```{note} +Some of these identifiers are supplied by PloneFormGen and are not available in other contexts. +``` + +## Using a Python script + +You'll be quickly frustrated if you try to do anything smart in a single TALES expression. +If you need to do something more complicated, add a Python Script to your form folder and call it via TALES. +For example, if you added a script with the id includesSpam, you could call it with the expression: + +``` +python: folder.includesSpam(value) +``` + +Make sure your script returns False if you wish to accept the input, or an error string otherwise. + +Here's what a validator script to check for spam might look like: + +``` +if 'spam' in value.lower(): + return False +else: + return "'%s' doesn't seem to have spam. Try again." % value +``` + +Make sure your script parameter list includes value. (Alternatively, you may check the request.form dictionary, +which will include form input.) + +```{note} +Python scripts are not the same as the Custom Script Adapter. +The latter is meant to make it easy to add a custom adapter that's processed in the same way as the mail or save-data adapter. +Python scripts Python code fragments that act like functions. +They are added via the Management Interface. +``` diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/embedding.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/embedding.md new file mode 100644 index 000000000..0acac2c32 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/embedding.md @@ -0,0 +1,52 @@ +# Embedding PloneFormGen forms + +```{admonition} Description +PloneFormGen forms may be rendered from other templates, viewlets, and portlets. +``` + +*Caveat*: This feature should be considered beta quality. +I've written code that takes advantage of it, and you shouldn't be afraid of it, but take care to test +thoroughly. +There may be certain types of contexts for rendering the form with implications that I haven't taken into consideration. + +To insert the form into an arbitrary template, use the 'embedded' browser view: + +``` +<tal:block tal:replace="structure path/to/form/@@embedded"/> +``` + +If you are including the form on a page that features another form, you'll probably +need to set a prefix on the 'embedded' view to disambiguate submissions: + +``` +<tal:block tal:define="form nocall:path/to/form/@@embedded; + dummy python:form.setPrefix('mypfg')" + tal:replace="structure form"/> +``` + +Or if you are using a view class, you could define a method like: + +``` +from Products.CMFCore.utils import getToolByName +def render_form(self): + portal = getToolByName(self.context, 'portal_url').getPortalObject() + form_view = portal.restrictedTraverse('path/to/form/@@embedded') + form_view.prefix = 'mypfg' + return form_view() +``` + +(Note that restrictedTraverse expects a path relative to the object you are +calling it on, with no initial slash.) And then in the associated template: + +``` +<tal:block tal:replace="structure view/render_form"/> +``` + +By default the embedded form uses the current URL as the form's 'action' parameter. +When the form is rendered upon submission, it will perform validation, run the normal +action adapters, and redirect to the success page as normal. If you want to submit to +the form's real location or somewhere else, you can override the action by setting the +'action' attribute on the 'embedded' view. + +*Known limitation*: Embedded forms have no way of injecting JavaScript or CSS into +the page head like their standalone counterparts. diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/failsafe_email.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/failsafe_email.md new file mode 100644 index 000000000..4ae500159 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/failsafe_email.md @@ -0,0 +1,53 @@ +# Fail-safe email sending + +By default if SMTP server rejects the message sent by PloneFormGen +the page will crash with an exception. Possible reasons for SMTP failure are + +- SMTP server is down +- SMTP server is overloaded +- SMTP server spam protection is giving false positives for your email sending attempts + +If you have a situation where gathering the data is critical, +the following process is appropriate: + +- Use save data adapter to save results +- Use a custom email sender script adapter to send email and even if this + step fails then the data is saved and no exception is given to the user + +Example PloneFormGen script adapter (using proxy role Manager): + +``` +# -*- coding: utf-8 -*- +from Products.CMFCore.utils import getToolByName + +# This script will send email to several recipients +# each written down to its own email field +# whose id starts with "email-" +emails = [] + +for key in fields: + if key.startswith('email-'): + if fields[key] != '': + emails.append(fields[key]) + + +mailhost = getToolByName(ploneformgen, 'MailHost') + +subject = "Huuhaa" + +# Custom message with a name filled in +message = u"""Hello, + +Thanks for participating %s ! +Cheers, +http://www.opensourcehacker.com +""" % (fields['etunimi']) + +source = "info@opensourcehacker.com" + +for email in emails: + try: + mailhost.send(message, email, source, subject=subject, charset="utf-8", ) + except Exception: + pass +``` diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/faq.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/faq.md new file mode 100644 index 000000000..ab9a9b9da --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/faq.md @@ -0,0 +1,167 @@ +# Frequently Asked Questions + +## Q. How can I make a date/time field default to current time? + +In the field's "overrides" fieldset, specify as Default Expression: + +``` +python:DateTime() +``` + +Note that you may do some simple date arithmetic. To set the default a week after server time, use: + +``` +python:DateTime() + 7 +``` + +## Q. I've made an error in a TALES expression, and now I can't view or edit my form! + +An error in a TALES override may prevent you from viewing the form, but it shouldn't stop you from editing it. + +To edit, navigate to the form (you'll see your error). + +- If the error is in a form override, add "/atct_edit" to the end of the URL to reach the editor. That will allow you to reach the form editor; now go to the overrides fieldset and fix the problem. +- If the error is in a field override, add "/folder_contents" to the end of the URL to reach the folder contents. Click on the troubled field; you'll again get an error. Now, add "/atct_edit" to the end of the URL to reach the editor. + +## Q. How do I make a field default to the member's name/address/id? + +In the field's override fieldset, set the Default Expression to: + +``` +here/memberEmail +``` + +memberEmail is a method of the form folder which will return a member's e-mail address, if one is available, and an empty string otherwise. + +You may also use "here/memberFullName" to get the member's name, and "here/memberId" to get the login id. + +```{note} +memberEmail, memberFullName and memberId are a convenience facility of PloneFormGen. They are not part of the Plone API. +``` + +## Q. Where is the encryption option? + +I understood PFG could GPG encrypt mail, but can't find the option to do it. + +Navigate to your mail adapter and edit it. Look in the fieldset list (the list of bracketed sub-forms at the top of the form). +Do you see an encryption field set title? If so, you've found the option. If not, it means that PFG was unable to find the gpg binary when it started. Read the README_GPG.txt file in the PFG product folder for details on how to solve this problem. + +Don't forget that after you install GnuPG, you'll need to restart Zope or refresh your PFG product. +Where is the save-data adapter? + +## Q. I've added a form folder, and the action adapter list includes "None" and "Mailer". Where is the save-data adapter? + +You need to add it to the folder via the add-item drop-down. + +A mailer adapter is in the "sample" form created when you add a form folder because it's probably the most common use. Other adapters need to be added. + +## Q. Why are these action adapters content types? Why aren't they built into the form folder? + +There are several reasons. One is that doing it this way makes it easy to copy configured action adapters from one form to another. + +## Q. When I attempt to submit a form, I get an AssertionError "You must specify a recipient e-mail address in the mail adapter." + +The error is occurring because PloneFormGen doesn't have a recipient address to which to mail the form input. + +To fix this, choose the contents tab of your PFG form folder. Navigate to the mailer and use its edit tab. Choose the "addressing" fieldset and specify a recipient address. + +By the way, if the recipient address isn't specified, PFG tries to use the e-mail address of the form folder's owner. You'll see this error if you've failed to set an e-mail address in personal preferences. + +## PloneFormGen missing from Add list? + +I installed the release of PloneFormGen in my Products directory in Plone 2.5.x, and neither the Management Interface (/Control_Panel/Products) nor Plone (Quick Installer) seemed to recognize it after restarting my Zope. + +Zope has probably encountered an error in the course of loading the product. + +Try checking your event.log for related error messages. You may wish to try starting Zope in foreground mode (bin/zopectl fg for a standalone zope) for more diagnostics. + +## How do I add a hidden field with the username? + +Create a string field and mark it hidden. + +On the overrides tab, set "here/memberId" for the Default Expression. + +```{note} +To follow this recipe, you'll need to have permission to edit TALES fields. +``` + +## Q. Dynamically populate selection fields? + +Can I dynamically populate selection and/or multi-selection fields in PloneFormGen? + +Yes, use the \[overrides\] panel of the field's edit view to set an Options Vocabulary. + +It should be a TALES expression that evaluates as a list of value/label lists (tuples are also OK). + +For example, let's say that we wanted a selection field populated with option values '1', '2', '3', '4' and matching visible labels 'one', 'two', three', 'four'. The TALES code for this would be: + +``` +python: (('1','one'), ('2','two'), ('3','three'), ('4','four')) +``` + +It's unlikely, though, that you'll be able to do what you need in a single line of TALES. A more typical use would be to create a python script that returns a sequence of value/label sequences. If you put that script in your form folder, you can fill in: + +``` +here/myscriptid +``` + +in your Options Vocabulary field. + +## Q. Could a selection field in a FormFolder be used to redirect? + +I have created a custom FormFolder, using PloneFormGen. Within the FormFolder, I have created a page and added a selection field with value/label pairs equivalent to: path (url) | company department --> i.e. <http://my.site/reports>/accounting|Accounting I am wondering if it is possible to create an action override that would 'redirect_to' the 'selected' value in the selection field, something like: 'redirect_to:string: ' If so, how might I access the value from the selection field? + +For the redirection, just put something like: + +``` +redirect_to: request/form/my-selection-field +``` + +in the Custom Success Action field on the form folder's \[override\] panel. + +If you need to do something more complicated, you can use the "Custom +Script Adapter" in the 1.1 alpha and end your code with: + +``` +request.response.redirect(request.form['my-selection-field']) +``` + +## Use a "From" address other than the site address? + +One stock-field is called replyto and contains a valid email address. I want this address to be in the From: line - not just in Reply-To:. I could fill in a TALES expression to overwrite the default sender-address. But what's the correct TALES expression for that? + +By default, PloneFormGen's mailer sends mail with the "From" address set to the site's global "From" address (specified in site setup / Portal Settings). That's the standard return address for portal-generated mail, but you may wish to use another. + +In the mailer's overrides sub-form, set the Sender Expression to: + +``` +request/form/replyto +``` + +to use the address filled in for the "replyto" form field. + +You could also specify a literal: + +``` +string:test@mysite.org +``` + +Be cautious about using user-submitted addresses for the "From" address. It's important that the "From" address be a real one, owned by a responsible person. + +## Q. Can I integrate my favorite field/widget? + +I'd like to integrate a new field/widget into PloneFormGen so that it will be useful as a form field in a PFG form. + +PFG is designed to allow this, but it's going to take some programming by you or the field developer. See the PFG "examples" directory for a heavily commented, really working, example of integrating a third-party field into PloneFormGen without touching the PFG or field code. + +## Q. Captcha field is not accessible? + +Or, not always readable for some people with low vision, or when using mobile phones this type of control is strongly blocking + +To effectively replace a Captcha, just add a mandatory text field (must match the size of two chars. max.) That can be called e.g. 'Filter' as help text with the following question: "to avoid spam can you answer this question: 7+2-1 = ? + +Next, modify the object and choose the menu 'overrides' and fill in the "custom validator" by this expression: + +``` +python: value != '8' and 'the answer is false' +``` diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/getting_started.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/getting_started.md new file mode 100644 index 000000000..6133c3652 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/getting_started.md @@ -0,0 +1,349 @@ +# Getting Started with PloneFormGen + +```{admonition} Description +Learn the basics of creating web forms with PloneFormGen +``` + +## Introduction + +{doc}`Please read general PloneFormGen information first </working-with-content/managing-content/ploneformgen//index>` + +## Getting Started + +```{note} +The best place to start for non-technical Plone users. +``` + +To get started building a custom form using PloneFormGen, you must first create a **Form Folder**. A form folder is a lot like a normal Plone folder - you use it to organize and hold other types of content. The Form Folder also has some settings of its own that will control the behavior and appearance of the form. + +Click *Add Item* and choose Form Folder from the drop-down menu. + +```{image} add-new-item-form-folder.png +:alt: 'screenshot: Adding form folder via drop-down' +``` + +### Create the form + +Provide a *Title* and *Description* for the form. You can also change the wording of the *Submit* or *Reset* button if you wish. + +Ignore the rest of this edit screen for the time being and just click *Save* at the bottom. + +```{image} creating-the-form-title-description.png +:alt: 'screenshot: Creating the form' +``` + +## Form Folder Settings + +```{admonition} Description +Learn how to configure your form. +``` + +You now have a basic form to work with. By default, a form starts with *E-Mail Address*, *Subject* and *Comments*. These are fields you get automatically, every time you create a new form. + +```{image} basic-form.png +:alt: 'screenshot: Basic form' +``` + +### Adding text to the form + +Before you learn how to add new fields, or change existing ones, let's look at how you can add some simple text above and below the form. + +You may want to include instructions to your site visitor about how to fill out your form, or what the purpose of the form is supposed to be. You can add that descriptive text as follows: + +- Edit the Form Folder by clicking on Edit in the taskbar +- Now you'll see two Body Text areas called Form Prologue and FormEpilogue (which means before and after). Use the text editor to format your content, include links, and even pictures. Click Save when you're all done. + +```{image} prologue-epilogue.png +:alt: 'screenshot: prologue and epilogue' +``` + +### Overrides + +When in the *Edit* mode on the Form Folder, notice the *Overrides* tab on the right-hand side of the page properties tabs. Form submission behaviors can be customized in this tab. + +Read the on-screen help to give you an idea what sort of customizations are possible here. Depending on what you need to do, you may need to learn how to write some basic TALES or Python code. Don't be afraid though! + +```{image} overrides-tab.png +:alt: 'screenshot: overrides tab' +``` + +## Overview of Field Types + +```{admonition} Description +Learn about the commonly used field types in PloneFormGen. +``` + +By now you've seen how to create a new form. The next step is to learn how to add new fields to the form. + +There are a lot of different types of fields that one can employ. You've probably seen many of those types of fields around on the Internet like a text box, a list you can choose from, a checkbox, radio buttons, and so on. + +Some of the field types that are included with PloneFormGen will not be discussed here as they are used more for advanced applications than for basic web forms. The field types discussed here should be all you need to create useful forms in Plone. + +### Common field types + +Navigate to your Form Folder and push the Add Item button. You should see a long drop-down menu appear. There's a lot of choices, but we've chosen the four most common to focus on for this tutorial. + +String Field + +: This is probably the most commonly used field. It's a simple, one-line text box for gathering info like name, address, e-mail, phone number and so on. + +Text Field + +: A large text box for gathering things like comments or other long-form text responses. + +Selection Field + +: This field type is to gather one choice from a list of selections. The list can be checkboxes, radio buttons, or a text list. + +Multi-Select Field + +: Use this field type if you want to let your site visitor select multiple items from a list. + +You'll notice that there is a special icon for each field type. It's a good idea to get familiar with how each one looks so you'll be able to recognize the different field types at a glance. + +In the next section, you'll see how to add and configure a string field; the most common type of form field. + +## Adding a String Field + +Steps to adding a single text line field called a String. + +Navigate to your Form Folder and click Add Item. Select String Field from the drop-down menu. + +The string field creates a simple one-line text box. Some common uses for this field type are: + +> - First Name +> - Last Name +> - Email +> - Street Address +> - Lots more! + +### Basic field info + +Many field types have the same information on their edit screen. Here's an explanation of each of these: + +Field label + +: The title of the field. + +Field help + +: Some text you can provide to the form submitters to help them figure out what you're asking for. + +Required + +: Is this a required field? + +Hidden + +: Is this a hidden field? This is useful for passing data back to yourself. + +Default + +: You can supply a defult value that the form submitters can change if they wish. + +Other types of information can be defined for other field types, and we will cover those as they come up. Since we're talking about the string field, let's take a moment to talk about validation. + +### Validators + +Validation is a feature common to many web forms. A validator checks that the input being provided conforms to a particular format. For example the "email address" validator simply checks that the input contains an @ sign (i.e. <mailto:contact@groundwire.org>). There are a set of standard validators available for string fields such as: Valid US phone number and Valid zip code. + +In practice validators can be helpful, but in some cases they may be too restrictive. If your site visitors are from outside the US, they mey become frustrated with trying to get past US-centric form validators! + +## PloneFormGen editing environment + +Note that PloneFormGen has both an *Edit* tab and a *QuickEdit* tab on the taskbar. The *Edit* mode mainly allows you to edit major settings for the entire form. The *QuickEdit* mode allows you to interactively edit the form. It's much a much easier way to add, edit, delete and reorder fields. + +In *QuickEdit* mode, you may add fields by dragging them from the toolkit at the right side of the page and dropping them into the target position in the form. + +If you want to see the form the way that your site visitors would, you can click on View in the taskbar. Likewise you can get to the editing environment from the normal view, by clicking the *QuickEdit* tab in the taskbar. + +Note that you cannot complete or submit the form when working in the editing environment. You will need to return to the normal form view first. + +```{image} quickedit-demo.png +:alt: 'screenshot: Quick edit demo' +``` + +## Changing the Order of the Fields + +```{admonition} Description +How to rearrange fields in your form. +``` + +By now you're probably wondering how to change the order that fields appear on your form. By default, when you create a new field, it will appear at the bottom of your form. Often, this isn't the result you wanted to see. + +Navigate to your Form Folder and click on the *QuickEdit* tab on the taskbar to enter the form editing environment. + +Notice that the column on the far left called Order. You can move the position of each field by clicking and dragging each field around if you hover your mouse pointer in the Order column. Continue to rearrange fields until you have the layout you want. + +To see the results, you need to click on the View tab to see your form the way your site visitors will. + +## Text Field + +```{admonition} Description +How to add a text box for collecting comments or other text. +``` + +A *Text field* is like a string field except that it's a large box instead of a single line. You can change the size of the field by adjusting the Rows and Max Length parameters. + +Rows controls the vertical height of the text box. Max Length controls the number of characters the site visitor can input at a time. If you want to limit a Comments text box to short comments, you might choose 500 characters as the limit. + +The *Default* field can be used if you want to suggest some content to the site visitor or wish to show an example of the sort of information you want from them. + +You can also *Reject Text with Links* to discourage people from adding links to your text area field. One reason why you might choose to do this would be if you're asking someone to enter some information and you don't want them to simply link to a blog entry or other online content. + +## Selection and Multi Select + +```{admonition} Description +How to create menus and checkboxes for selecting items from a list within your form. +``` + +In addition to text boxes and the string field, *selection* and *multi-select* are commonly used field types. They allow site visitors to choose a selection from a list, drop-down menu, radio buttons or checkboxes. + +### Selection field + +As before, you must be in your Form Folder to add additional fields. Choose *Selection Field* from the list in the Add New drop-down menu or the QuickEdit toolkit. + +In addition to the regulars like *Field Label* and *Field Help*, there are *Options* and *Presentation Widget* to consider. + +### Options + +Options is for establishing what the options in the field are going to be. Each option should be separated with a line break. + +### Presentation widget + +The *Presentation Widget* is the kind of graphic used for gathering the input: you can choose either Radio Button or Selection List (a drop-down menu). The option Flexible simply means that you leave it up to PloneFormGen to decide which widget is most appropriate. Basically, if you have more than three choices it will use the selection list. Less than three will appear as radio buttons. + +### Value|label + +Entering Options can be done in one of two ways. Either "one line per option" or the "Value|Label format". One line per option is described above, but what about *Value|Label*? + +Let's say you want to present some choices, but the actual value recorded by the form is different than what the form submitter sees on the screen. For example, let's say that you want to ask a site visitor what county they live in, but in your program work you classify counties into regions like "Northwest" and "Southeast". Instead of asking the visitor to identify which region they live in (which some might get wrong or misunderstand) you could present them a list of counties. + +In the above example you would format Options like this: + +``` +Northwest|Jefferson +Northwest|Island +Northwest|Mason +Southeast|Columbia +Southeast|Asotin +Etc . . . +``` + +In this example, if a visitor selects "Jefferson" as their county, the form would record the entry as "Northwest". + +### Multi-select + +Multi-select is very similar to a Selection Field except that you have an additional widget (the checkbox) and your site visitors can choose many options from one list. + +If you plan to use the Selection List widget for a multi-select field, it is helpful to include a note about the Control key in Field Help. In order to actually choose more than one option in the list, you must hold down the control key (CTRL) on your keyboard and then click to select/de-select options. Because of this, it is most often the best choice to use the Checkbox widget instead of Selection List for a multi-select field. + +## The Thank You Page + +```{admonition} Description +How to customize the page a site visitor sees after having submitted the form. +``` + +After a site visitor has filled out your form and clicks submit, they will see a page thanking them for their input. Look in your Form Folder and you should already see a Thank You page in the contents. + +It doesn't matter where the Thank You page appears in your Form Folder contents. It will always work the same, no matter its folder position. + +By default, the thank you page only lists a summary of what the site visitor put into the form. Here's an example of what that looks like, to the right. + +Note: You will only see this result if you fill out the form and submit it. Otherwise, if you try to navigate or link to the thank you page directly, you get a message that says something like "no input was received". + +### Add content to the thank you page + +The above example is decent, but there will be times that you may want to say something more, or even provide a few links for your site visitor to follow. Edit the Thank You page in your list of Form Folder contents. You should now see the familiar Title and Description fields, but you'll also see: + +- Thanks Prologue +- Thanks Epilogue +- No Submit Message + +If you've chosen to display any field results the Prologue content will appear before those results and the Epilogue content will appear after. If you aren't going to display field results, just use the Prologue. + +Should you wish to change the No Submit Message (remember, if you just hit submit on your form without filling out any fields, you'll see this message) you can do so here. You have the full power of Plone's text editor so feel free to include links and formatted text here. + +### Fields + +thanks-fields.gif + +When editing the Thank You page, notice the Fields tabnext to Default. Here's where you can control which field results to display or which ones to take out. Simply uncheck Show All Fields if you don't want to display any results on the Thank You Page. + +## The Mailer Adapter + +```{admonition} Description +Learn to configure the adapter which sends an email after the form is submitted. +``` + +### Overview + +Adapters control what happens to the form data that your site visitors submit with the form. The Mailer Adapter will send form data to an email address or addresses of your choosing. The Save Data Adapter will save the results in your Form Folder so that you can export them any time you wish. You can even use adapters concurrently to get the functionality of both. + +## Configuring the mailer adapter + +The *Mailer Adapter* is probably the more complex of the two adapters covered in this tutorial. As such, we won't go through and explain all the options present in the Mailer Adapter. However, we will cover the most important options available. + +Go ahead and edit the Mailer Adapter in the form editing environment. The first screen you see look like this: + +From here you can do three things: + +- Change the Title of your Mailer Adapter (really no reason to, unless you have more than one) +- Choose a recipient name +- Choose a recipient email address + +### Addressing + +Now notice the tabs \[default\] \[addressing\] and so on. Click on \[addressing\]. + +The *Addressing* screen allows you to make selections about other recipients and dynamically populate the *From* and *Reply-to* fields directly from form data. + +### Message + +The Message tab allows you to configure the: + +- Subject Line +- Email body content +- Form field data that appears in the email message + +### Template, encryption, & overrides + +These options are beyond the scope of this tutorial as they require a discussion of HTML, TALES and Python programming languages as well as an understanding of mail server configuration. + +## The Save Data Adapter + +```{admonition} Description +Collect and save answers from each from submission with the Save Data Adapter. +``` + +Unlike the Mailer Adapter, the *Save Data Adapter* isn't automatically created when you build a new Form Folder. As such, you must add it yourself by clicking Add New (when you're in your Form Folder) and selecting the *Save Data Adapter* from the drop-down menu. Or, drag and drop it from the toolbox in QuickEdit mode. + +The first thing you'll see is a screen like the one to the right. + +### Configure the adapter + +Enter in a Title that sounds good to you (*My Saved Form Data*, for example). Your site visitors won't see this title at all, so anything will do. + +Next, you can select some *Extra Data* to store if you wish. Most of these choices are for fairly esoteric things, but Posting Date/Time could be helpful if you want to know when someone filled out your form. + +*Download Format* depends on what your preferences are, but *Comma-Separated Values* is probably the most common. It really depends on if you are going to plug the info into a database, and what type of file is most appropriate for that. If the info is for human eyes only, then it doesn't really matter what you pick here. Europeans: you may choose to use a colon rather than a comma for CSV on the PloneFormGen config panel in site setup. + +Now click on *Save* to finish. You do not need to put anything into the Saved Form Input box. If your Save Data Adapter had any data in it, it would appear in that box. + +That's all there is to it. Sit back and wait for the data to come pouring in! + +### Retrieving your data + +Once your form has been filled out a few times by site visitors, you can start retrieving the form data. You need to navigate to your Form Folder and click on the Contentstab to get a view of all contents. + +Now click on your *Save Data Adapter*. You should then see a screen like this one at the right. + +You can download the form data as many times as you want. The data will always be there as long as you don't delete the *Save Data Adapter*. If you click *Clear Saved Input* all data will be erased as well. + +### Safety Net + +A common way of saving important data is to use two *save data* adapters in your form. Use one to occasionally harvest new data and clear it. Use the other to save all your history. + +```{note} +This document was originally written by Sam Knox for Groundwire. Thanks to both Sam and Groundwire for passing it on to the Plone Foundation. +``` diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/gpg.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/gpg.md new file mode 100644 index 000000000..1b781881c --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/gpg.md @@ -0,0 +1,44 @@ +# Using GnuPG encryption + +```{admonition} Description +The Gnu Privacy Guard may be used to encrypt emails sent by PloneFormGen. +``` + +```{warning} +Encryption is serious business, and this how-to does not teach you about it or about the Gnu Privacy Guard. You should develop expertise with both of these before attempting to enable PFG encryption. +``` + +Using GPG encryption with PloneFormGen requires: + +1\) That gpg be installed on your system and available on the search path +or in a common location (e.g., /usr/bin); + +2\) That gpg, when executed as a subprocess of Zope/Plone, be able to +find a public keyring; + +3\) That gpg, when executed as a subprocess of Zope/Plone, have the +rights to read the public keyring; + +4\) That you, as administrator, understand how gpg works, and be able to +maintain the public keyring. + +PloneFormGen tries to find the gpg binary when it's installed, when the +product code is refreshed, and when you restart Zope. If it finds it +you will see an "encryption" field set in the mailer adapter form. If +you don't see the "encryption" fieldset, it means PloneFormGen didn't +find a gpg binary. Fix this by adding the path to the gpg binary to the +PATH environment variable when you start Zope. + +gpg will typically look for a public keyring in the current user's home +directory, .gnupg subdirectory. If it's not finding it, consider the +possibility that the user id you're using to maintain your keys isn't the +same one that you're using to run Zope. You may need to use the +GNUPGHOME environment variable to point to your .gnupg directory. Make +sure your Zope process can open the directory and read the file! + +```{note} +Windows + +gpg can work in a Windows environment, but you'll need to have a +command-line gpg. <http://www.cygwin.com/> is a good, free source. +``` diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/index.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/index.md new file mode 100644 index 000000000..c283441c4 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/index.md @@ -0,0 +1,63 @@ +# Creating forms without programming: PloneFormGen + +```{admonition} Description +PloneFormGen allows you to build and maintain convenience forms through Plone edit interface. +``` + +## Introduction + +*PloneFormGen* is a Plone add-on Product that provides a generic Plone form generator using fields, widgets and validators from Archetypes. +Use it to build, one-of-a-kind, web forms that save or mail form input. + +To build a web form, create a form folder, then add form fields as contents. +Individual fields can display and validate themselves for testing purposes. +The form folder creates a form from all the contained field content objects. + +Final disposition of form input is handled via plug-in action products. + +Action adapters included with this release include a mailer, a save-data adapter that saves input in tab-separated format for later download, +and a custom-script adapter that makes it possible to script simple actions without recourse to the Management Interface. + +To make it easy to get started, newly created form folders are pre-populated to act as a simple e-mail response form. + +- [PloneFormGen product page](https://plone.org/products/ploneformgen) + +### Getting started with PloneFormGen + +```{toctree} +:maxdepth: 2 + +getting_started +``` + +### PloneFormGen topics + +```{toctree} +:maxdepth: 1 + +installation +override_defaults +custom_validators +select_mail +restyle +javascript +custom_thanks +request +multipage +captcha +faq +``` + +### Advanced topics + +```{toctree} +:maxdepth: 1 + +sql_crud +gpg +embedding +custom_addons +creating_content +custom_mailer +failsafe_email +``` diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/installation.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/installation.md new file mode 100644 index 000000000..a32f00321 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/installation.md @@ -0,0 +1,18 @@ +# Installing PloneFormGen + +```{admonition} Description +PloneFormGen is a Plone add-on product, and is not included with Plone. Fortunately, it's easy to install. +``` + +PFG installs just like most other Plone add ons. Edit the buildout.cfg file at the top of your Plone instance and look for the `eggs =` section that specified Python Packages that you with to include. Add PloneFormGen: + +```ini +eggs = + Plone + ... + Products.PloneFormGen +``` + +Run bin/buildout and restart your Plone instance. Dependencies will be loaded automatically. + +After restarting Plone, visit your site-setup page and use the "add on" configuration page to activate PloneFormGen. diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/javascript.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/javascript.md new file mode 100644 index 000000000..827d7c60c --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/javascript.md @@ -0,0 +1,70 @@ +# Adding a JavaScript event handler to a form + +```{admonition} Description +Need to make your PFG forms more dynamic? It's easy to add JavaScript. +``` + +There are two basic steps to injecting JavaScript into a PFG form: + +1. Use the Management Interface to create a text file (object type: file; mimetype: text/plain) either inside the form folder or in a skin folder; +2. Use the form folder's edit / overrides pane, header injection field to tell PFG to inject it into the form. + +## Injection + +Let's look at the second step first. Let's say that your JavaScript file is named form_js. Then just specify: + +``` +here/form_js +``` + +in the header injections override field. + +## JavaScript + +There are a couple of considerations here: + +1. Since this is a header injection, you'll need to supply the `SCRIPT` tags; +2. You'll nearly certainly want to use jQuery to attach the event handler, since jQuery is part of Plone. + +```html +<script> +jQuery(function($) { + $('#my-questions :input') + .click(function() { + alert('checkbox clicked'); + }); +}); +</script> +``` + +This code fragment shows off both, and attaches an alert to every input in the `mqy-questions` field. + +Note the use of the common jQuery idiom: + +```javascript +jQuery(function($) { + ... +}); +``` + +This accomplishes a couple of things: + +1. it sets the code up to run once the page is loaded; +2. it aliases "jQuery" to "\$" so that we may use common jQuery shorthand. + +## An alternative injection + +If you want to use a separate JavaScript file that is actual JS (no `script` tags) and will be shared among forms, +use the header injection override like this: + +``` +string:<script src="form_scripts.js" /> +``` + +assuming your script is named `form_scripts.js`. You may make it a little more sophisticated if you need an absolute URL: + +``` +string:<script src="${here/form_scripts.js/absolute_url}" /> +``` + +using TALES string interpolation. diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/multipage.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/multipage.md new file mode 100644 index 000000000..dbf56dd24 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/multipage.md @@ -0,0 +1,35 @@ +# Creating a Multi-Page Form + +```{admonition} Description +You can create a multi-page form as a chain of form folders. +``` + +Creating a multi-page form is probably much simpler than you might suppose. You may do it by just creating a sequence of form folders that each link to the next. +The basic procedure is: + +- Create your sequence of form folders, typically all in the same normal Plone folder; +- On all but the last form folder, turn off all action adapters and set the Custom Success Action override to "traverse_to:string:id-of-next-form-folder"; +- On all but the last form folder, set the Submit Button Label to something like "Next" and turn off the cancel button. +- On all but the first form folder, set the Exclude From Navigation flag in the properties tab; +- In each form folder, create a set of hidden form fields matching all the fields in all the previous forms; +- In the last form, turn on your real action adapter(s). + +As your user moves from form page to page, input will be automatically saved in the hidden fields of subsequent pages. + +```{note} +A Note on Hidden Fields: The hidden flag is not available for all form field types, but you don't need it. String, Text and Lines fields are adequate to carry all the basic data. Use a hidden Lines field to hold multiple selection field input, string or text for the rest. +``` + +An added bonus + +If you want to create a sequence of forms, where the answers on form_A could lead to a form_B or form_C, you can use a traverse_to override. + +- Create a selection field in form_A, which could be called 'formnext'; +- As values in the selection field, put the paths to the next forms in the sequence; +- Then, in the form overrides -> custom success action use + +traverse_to:request/form/formnext + +```{note} +use traverse_to as opposed to a redirect_to as this will preserve the form object in the request. +``` diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/override_defaults.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/override_defaults.md new file mode 100644 index 000000000..c03213ad2 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/override_defaults.md @@ -0,0 +1,126 @@ +# Overriding field defaults dynamically + +```{admonition} Description +PloneFormGen allows you to supply dynamic field defaults by specifying a TALES expression in the Default Expression field of the overrides fieldset (sub-form). This how-to explains what that means, and offers a few examples. +``` + +Creating a dynamic field default means to have a form field's initial value change with context. We might, for example, wish to use a member's e-mail address, which would vary with the user. Or, we might be looking up some data via a catalog or RDBMS query, and wish to supply that to the user for correction. + +`Template Attribute Language Expression Syntax` (TALES) is a simple notation that allows determination of a value via path (as in path/to/object), string or Python expressions. It is used in `Zope's Template Attribute Language` (TAL), and is ubiquitous in Plone templates. This how-to does not teach you TALES; for that, try the [Zope Page Templates Reference](https://docs.zope.org/zope2/zope2book/AppendixC.html). + +```{warning} +Please note that it's easy to make a mistake when working with TALES fields that will cause an error when you try to display your form. Stay calm! Take note of the error message, and return to the field edit form to fix it. Don't be scared of this kind of error. +``` + +## Example + +Let's say you wish to put the member's id in a string field default. You may do that with the TALES expression: + +``` +member/id +``` + +This is a path expression. "id" is found in the "member" object and returned. + +There's a gotcha here. What if the form is viewed by an anonymous visitor? They'll receive an error message. We can avoid that with the expression: + +``` +member/id | nothing +``` + +The vertical bar (|) marks alternate expression that is used if the left-hand expression is empty or can't be evaluated. Here we're saying to show nothing if member/id can't be evaluated. +Using Python + +You may also use Python expressions: + +``` +python: 5 + 3 +``` + +would supply a value of 8. This is trivial, but what about: + +``` +python: DateTime() + 7 +``` + +This would supply the current date/time plus seven days. + +## The name space + +Here are the objects available when your expression is evaluated. + +### TALES context + +here + +: The current object. A bit dangerous since this varies depending on context. + +folder + +: This will be your form folder. + +portal + +: The portal object. + +request + +: The REQUEST object. Note that request/form contains form input. + +member + +: The authenticated user's member data -- if any. + +nothing + +: Equivalent to Python None. + +folder_url + +: URL of the form folder. + +portal_url + +: URL of the site. + +modules + +: Module importer. + +```{note} +Some of these identifiers are supplied by PloneFormGen and are not available in other contexts. +``` + +When you compose your TALES expression, keep in mind that it will need to return different types of data for different types of fields. For simple field defaults, return a string value; for the lines field, return a list or tuple. + +## Calling a Python script + +You'll be frustrated fast if you try to do anything smart in a single TALES expression. If you need to do something more complicated, add a Python Script to your form folder and call it via TALES. For example, if you added a script with the id getEmail, you could call it with the expression: + +``` +folder/getEmail +``` + +Make sure your script returns the value you wish to use as a field default, in the appropriate format. + +Setting Many Defaults With One Script + +If you need to dynamically set several fields, you may do it with one script. Call the script by specifying it in the Form Setup Script field of the form folder's overrides fieldset. + +Set the form fields by putting them in the request/form dictionary. Make sure you don't overwrite anything that's already in the dictionary, as that is probably previously submitted input. + +For example, we could create a Python Script (using the Management Interface) in the form folder: + +```python +request = container.REQUEST + +request.form.setdefault('topic', 'value from python script') +``` + +If the script id was setTopicDefault, we'd call it by putting: + +``` +here/setTopicDefault +``` + +in the `Form Setup Script` field of the form folder's overrides fieldset. diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/overrides-tab.png b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/overrides-tab.png new file mode 100644 index 000000000..c595790fa Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/overrides-tab.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/prologue-epilogue.png b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/prologue-epilogue.png new file mode 100644 index 000000000..05451383b Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/prologue-epilogue.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/quickedit-demo.png b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/quickedit-demo.png new file mode 100644 index 000000000..33de76bc2 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/quickedit-demo.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/request.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/request.md new file mode 100644 index 000000000..7b8e19952 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/request.md @@ -0,0 +1,36 @@ +# What's in a Request + +```{admonition} Description +If you're trying to use PloneFormGen overrides, you're going to need to use the request object. Here's a quick trick for exploring it. +``` + +As a page is assembled by Zope and Plone following a browser request, information about that request is bundled into a non-persistent, pseudo-global request object. This object is available in the scripts, templates and TALES expressions you may use in creating PloneFormGen overrides. It will contain the form input submitted by the user. + +To effectively write more complex overrides, you're going to need to know how to get information out of the request object. + +```{note} +The Request class itself is well-documented in the Zope help system (API section) and in the source at Products.OFSP-2.13.2-py2.X/Products/OFSP/help/Request.py. +``` + +Here's a quick recipe that will help you examine the form input contained in the request. + +- Jump into the Management Interface and navigate to your PFG Form Folder. + Inside it, create a Page Template named showrequest. Now, just before \</body>, add: + + ``` + <div tal:replace="structure request" /> + ``` + + Note: when the request object is called, it renders a readable, HTML version of the data. We use "structure" to prevent escaping the HTML. + +- Give your template a title and save it away. + +- Return to Plone and your form folder. Edit it, and on the form's \[overrides\] pane, set a Custom Success Action of: + + ``` + traverse_to:string:showrequest + ``` + +Note that this will override any thanks page you've specified. Just clear it when you're done developing. + +Now, just fill out your form, and submit it. You should see the contents of the request object. Take a particular look at the form section. That's a dictionary available as request.form when you're composing an override. diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/restyle.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/restyle.md new file mode 100644 index 000000000..f59350c57 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/restyle.md @@ -0,0 +1,156 @@ +# Restyle a form + +```{admonition} Description +How to inject CSS into a form page to turn a label green ... or pretty much anything else. +``` + +The general answer to "how do I restyle a form" questions is: use CSS. + +The underlying Archetypes form generator surrounds every form element with a \<div> with a distinct ID. For example, a sample form with a textarea contents field has the generated XHTML: + +```xml +<div class="field ArchetypesTextAreaWidget" + id="archetypes-fieldname-comments"> + <span></span> + <label for="comments">Comments</label> + <span class="fieldRequired" title="Required"> + (Required) + </span> + <div class="formHelp" id="comments_help"></div> + <textarea rows="5" name="comments" cols="40" id="comments"></textarea> + <input type="hidden" name="comments_text_format" value="text/plain" /> +</div> +``` + +That's more than enough ID and Class selectors to do pretty much anything in the way of visual formatting. + +How do we get the CSS into the form's page? You could add it to the site's css, but there's a much easier way. +Using the Management Interface, create an object of type File inside your form folder. +Set its Content Type to "text/plain" and give it the ID "newstyle". + +Let's turn the label for the comments field green. Just fill in the big text field on your file with: + +```css +<style> +#archetypes-fieldname-comments label { + color: green; +} +</style> +``` + +Now, save it, return to the Plone UI and edit your form folder. Specify "here/newstyle" for the Header Injection field of the `overrides` pane. Now, enjoy your green label. + +## Putting checkboxes in a row + +Now, for a more useful example. It's a common requirement to want to put a set of checkbox fields on a single line. + +The easiest way to set this up is to create the list of checkboxes as a multi-selection field with "checkboxes" designated for display. That's going to generate markup that will look something like this: + +```xml +<div id="my-questions"> + <div class="formQuestion label"> + My Questions + <span id="my-questions_help" class="formHelp"></span> + </div> + <div id="archetypes-value-my-questions_1" class="ArchetypesMultiSelectionValue"> + <input type="checkbox" name="my-questions:list" value="a" id="my-questions_1" class="blurrable"> + <label for="my-questions_1">Choice A</label> + </div> + <div id="archetypes-value-my-questions_2" class="ArchetypesMultiSelectionValue"> + <input type="checkbox" name="my-questions:list" value="b" id="my-questions_2" class="blurrable"> + <label for="my-questions_2">Choice B</label> + </div> + <div id="archetypes-value-my-questions_3" class="ArchetypesMultiSelectionValue"> + <input type="checkbox" name="my-questions:list" value="c" id="my-questions_3" class="blurrable"> + <label for="my-questions_3">Choice C</label> + </div> +</div> +``` + +Note that each checkbox/label pair is in a `DIV` with the class "ArchetypesMultiSelectionValue". The basic CSS couldn't be simpler: + +```css +<style> +#my-questions div.ArchetypesMultiSelectionValue { + float: left; +} +</style> +``` + +Of course, you'll need to do some more styling. First of all, you'll need to set a `clear: left` on the following control. And, you'll need to do some padding. + +## Putting string fields in a row + +Making string fields display horizontally is a little different than the solution for checkboxes. There is no div wrapping the string fields like there is with check boxes. To get around this, add a fieldset and put the fields in the fieldset. This also lets you isolate the horizontal fields from other vertical fields. Here, two fields are required, one is not. The markup will look similar to this: + +```xml +<fieldset class="PFGFieldsetWidget" id="pfg-fieldsetname-name"> + <div class="formHelp" id="name_help"></div> + <div class="field ArchetypesStringWidget " id="archetypes-fieldname-first-name"> <span></span> + <label class="formQuestion" for="first-name"> First Name <span class="required" title="Required" style="color: #f00;"> ■ </span> </label> + <div class="formHelp" id="first-name_help"></div> + <div class="fieldErrorBox"></div> + <input type="text" name="first-name" class="blurrable firstToFocus" id="first-name" size="20" maxlength="30" /> + </div> + <div class="field ArchetypesStringWidget " id="archetypes-fieldname-middle-initial"> <span></span> + <label class="formQuestion" for="middle-initial"> Middle Initial </label> + <div class="formHelp" id="middle-initial_help"></div> + <div class="fieldErrorBox"></div> + <input type="text" name="middle-initial" class="blurrable firstToFocus" id="middle-initial" size="1" maxlength="1" /> + </div> + <div class="field ArchetypesStringWidget " id="archetypes-fieldname-last-name"> <span></span> + <label class="formQuestion" for="last-name"> Last Name <span class="required" title="Required" style="color: #f00;"> ■ </span> </label> + <div class="formHelp" id="last-name_help"></div> + <div class="fieldErrorBox"></div> + <input type="text" name="last-name" class="blurrable firstToFocus" id="last-name" size="30" maxlength="255" /> + </div> + </fieldset> +``` + +Here is the CSS: + +```css +<style> +/* Displays the 3 string fields horizontally. Turn off the clear from Public.css. This is necessary to display horizontally. */ +#pfg-fieldsetname-name div.ArchetypesStringWidget { + float: left; + clear:none; +} + +/* needed for space between fields */ +#archetypes-fieldname-middle-initial +{ + padding: 0 1em; +} + +#content fieldset#pfg-fieldsetname-name +{ +/*Hide the border on the fieldset */ + border-style: none; +/*Need this to left align the fields inside the fieldset with the fields outside the fieldset*/ + padding-left: 0; +} +</style> +``` + +## An alternative way to inject CSS + +Let's say you've got a lot of CSS. You may want to use an external style sheet file rather than inject the whole bundle into the header with every form display. + +Let's say the CSS resource is named `form_styles.css`. Then, just put the following in your overrides / header injection field: + +``` +string:<style>@import url(form_styles.css)</style> +``` + +We can get a little fancier to generate absolute URLs for the style file: + +``` +string:<style>@import url(${here/form_styles.css/absolute_url})</style> +``` + +using the string interpolation feature of TALES. + +```{note} +Need to do something more sophisticated? You can use a Python script to generate dynamic CSS or JavaScript. +``` diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/select_mail.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/select_mail.md new file mode 100644 index 000000000..32083dc69 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/select_mail.md @@ -0,0 +1,30 @@ +# Using a selection field to pick mail destination + +```{admonition} Description +You may allow form users to use a selection field to choose a destination address for their form input. + +> I'm trying to use a PloneFormGen form as a support center for my project and I would like to have the mail sent to different email addresses based on a choice from a selection field. +> +> How can I do it? +``` + +## The form + +First, create a selection field in your form + +In the Options field, specify your set of possible destination addresses in a "value|label" format where the e-mail address is the value and its readable name the label. For example: + +``` +softwarehelp@example.org|Software Support Desk +hardwarehelp@example.org|Hardware Support Desk +``` + +Then, pick the address (the actual e-mail address value, not the label) you wish selected by default. Put it in the Default field. Make sure the Required checkbox is selected. + +Save the form field. + +## Configuring the mailer + +Now, edit the mail adapter for your form. (Navigate to the form folder, click on contents, find your mail adapter and follow the link; select the edit tab.) + +Choose the `[addressing]` sub-form and find the Extract Recipient From field. You should see a None choice and a list of all of the selection fields in your form. Select the field you just created and save your changes. diff --git a/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/sql_crud.md b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/sql_crud.md new file mode 100644 index 000000000..c58da614d --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/ploneformgen/sql_crud.md @@ -0,0 +1,288 @@ +# Simple SQL CRUD with PloneFormGen + +```{admonition} Description +A step-by-step lesson in using PloneFormGen to read, insert and update rows in a single SQL table. +``` + +## Introduction + +One of the goals of PloneFormGen is that it should be useful for simple update operations on an external database. + +This tutorial covers the use of PloneFormGen to update and insert rows in a single-table SQL database. + +The simple application we'll develop here would need quite a bit of polishing before you'd wish to expose it to the public, +but it will demonstrate the basic techniques. + +Skills required to understand this tutorial include: + +- The ability to add an SQL database connection and Z SQL Methods via the Management Interface and to understand what they do. If you've never read the Relational Database Connectivity chapter of the Zope Book, take some time now to do it; it's fundamental. +- Simple Python scripting via the Management Interface. Read the python-based scripts portions of the Advanced Zope Scripting chapter of the Zope Book if you're new to this vital Zope/Plone development skill. + +Our basic steps will be to: + +- Add a database and table to our SQL database and create a matching form in PloneFormGen; +- Add a Z SQL Method to insert rows into the database and show how it can be used in PFG; +- Add a Z SQL Method to read a row, write a Python script wrapper and use it to fill out the fields of our form; +- Add a Z SQL Method to update a row, write a Python wrapper for it and the insert method and use it as a form action; +- Consider the security implications of the fact that the SQL access methods we just created are not part of the Plone workflow. + +By the way, we'll be skipping the "D" in CRUD. Deletion is up to you. :) + +```{note} +This tutorial uses *Z SQL Methods* because they're easy to teach quickly. +If you're doing any significant database work with any Python application, +[SQLAlchemy](http://www.sqlalchemy.org) is a much more scalable way to use a relational database from Plone. +``` + +## Database table & form + +In this step, we create a simple database table and a matching form. + +The database + +Hope you're not feeling too ambitious at the moment, because this is going to be a demonstration table. It's going to have three columns: + +uid + +: A unique ID that's the primary key for the table. We'll make it auto-increment so that our SQL server (MySQL in this case) will do the work of keeping it unique. + +string1 + +: A simple string. + +string2 + +: Another simple string. + +(I told you this was simple!) + +Create a test database and then the table. In MySQL, the CREATE code to set up the table is: + +```sql +CREATE TABLE simple_db ( + uid bigint(20) unsigned NOT NULL auto_increment, + string1 varchar(255) NOT NULL default '', + string2 varchar(255) NOT NULL default '', + PRIMARY KEY (uid) +) TYPE=MyISAM; +``` + +Now, set up an SQL user with privileges adequate to select, insert and update the table. +Use that user identity to set up an SQL database connection object via the Management Interface. +(If you're using MySQL, this would be a Z MySQL Database Connection.) The connection must be in a place where it will be visible to the form you'll be creating. + +The form + +Create a PloneFormGen form with three fields: + +uid + +: An string field with id uid, marked hidden, with a default value of "-1". Later in the tutorial, we'll use the "-1" as a marker value to indicate a new record. + +string1 + +: A string field with id string1. + +string2 + +: A string field with id string2. + +Note that the form field ids must exactly match our column ids. +You can script your way around this requirement, but it's a lot easier this way. + +While you're at it, turn off or delete the mailer action adapter. It's harmless, but it would be a distraction. + +That's it. We now have a form that matches our database table. + +## Inserting rows + +In this step, we create a method to insert a row, and show how to make of it. + +Now, inside the Management Interface, in your form folder, create a Z SQL Method with the id *testCreateRow*. + +Set the parameters: + +Connection ID + +: This should be the database connection you set up to allow access to your test database. + +Arguments + +: On separate lines, specify "string1" and "string2". (Leave off the quotes.) + +Then, in the big text area, specify the code: + +```python +insert into simple_db values ( + 0, + <dtml-sqlvar string1 type=string>, + <dtml-sqlvar string2 type=string> +) +``` + +Note: always use \<dtml-sqlvar ...> to insert your variables. It protects you against SQL-injection attacks by SQL quoting the values. + +Now for a little magic: Z SQL Methods can pick up their arguments from REQUEST.form, which is exactly where Zope is putting your form variables when you submit a form. +That means that you can just go to the \[overrides\] pane of your Form Folder and set `here/testCreateRow` as your After Validation Script. + +Your form will now store its input into your SQL table! Add a few rows to check it out. +Reading a Row, Filling in the Fields + +If we want to update records, we're going to have to get rows from our SQL table and use the columns to populate our form fields. + +The SQL + +Now, use the Management Interface to create, inside your form folder, a Z SQL Method named testReadRow. Set up the following parameters: + +Connection ID + +: Choose your test database adapter. + +Arguments + +: Just "uid" + +Then, add the SQL Code: + +```sql +select * from simple_db where + <dtml-sqltest uid type="int"> +``` + +The \<dtml-sqltest ...> operator is a safe way to use user input for an SQL "where" test. The default test is "=". + +The Script + +Let's wrap this method in a simple Python script that will selectively use it. Create a Python Script with the id formSetup and the Python: + +```python +request = container.REQUEST +form = request.form + +if form.has_key('uid') and not form.has_key('form.submitted') : + res = context.testReadRow().dictionaries() + if len(res) == 1: + row = res[0] + for key in row.keys(): + form[key] = row[key] +``` + +Let's deconstruct this code. + +The if test: + +```python +if form.has_key('uid') and not form.has_key('form.submitted') +``` + +will make sure that this code does nothing if the form has already been submitted (we don't want to overwrite values the user just input). It also won't do anything if we don't have a "uid" variable in the form dictionary. (form.submitted is a hidden input that's part of every PFG form.) + +If we have a uid variable and we won't be overwriting user input, then we call our SQL read method: + +```python +res = context.testReadRow().dictionaries() +``` + +This will return the results of our SQL query in the form of a list of dictionaries. +The dictionary entries will be in the form columnid:value. + +Note that the uid value is being passed via the request variable, and doesn't need to be specified. + +The rest of the code checks to make sure that we got one result, and throws all of its key:value pairs into the form dictionary -- just where our form will expect them. + +## The form + +Now, go to the \[override\] pane of your form folder, and specify `here/formSetup` for your Form Setup Script. + +### Calling The Form + +Hopefully, you've got a few rows in your table. + +Now, try calling your form with the URL: + +``` +http://localhost/testfolder/myform?uid=1 +``` + +Everything up to the question mark (the query string marker) should be the URL of your form folder. +The "?uid=1" specifies that we want to use the data from the row where the uid is "1". + +How would you actually get your users to such a URL? Typically, you'd have some sort of drill-down search that offered them a list of links constructed in this fashion. + +Creating a drill-down template is left as an exercise for the reader. + +## Updating or inserting as necessary + +In this step, we'll create an update SQL method and show how to selectively update or insert data. + +Using the Management Interface, create a Z SQL Method inside your form folder with the id testUpdateRow. +For its parameters, set: + +Connection ID + +: Choose your test database connection. + +Arguments + +: Add "uid", "string1" and "string2" on separate lines, without quotes. + +Then, specify the SQL code: + +```sql +UPDATE simple_db +SET + <dtml-sqltest string1 type="string">, + <dtml-sqltest string2 type="string"> +WHERE <dtml-sqltest uid type="int"> +``` + +Notice the use \<dtml-sqltest ...> for the SQL set id=value lines. +This is a hack that uses sqltest where we could have instead written lines like "string1=\<dtml-sqlvar string1 type=string>". + +Now, we've got to solve a problem. +How do we update our table under some circumstances, and insert new values under others? + +Remember how we set "-1" as the default value of our hidden "uid" form field? +If we've read a record, uid will have changed to match a real row. +If it's "-1", that means that we started with a clean form rather than values read from a table row. + +Let's use that knowledge in a simple switchboard script with the id doUpdateInsert: + +```python +request = container.REQUEST +form = request.form + +if int(form.get('uid', '-1')) >= 0: + # we have a real uid, so update + context.testUpdateRow() +else: + context.testCreateRow() +``` + +Now, go to the \[overrides\] pane of your form folder and set `here/doUpdateInsert` as the *AfterValidationScript*. + +```{Note} +Believe it or not ... you're done. +``` + +Time to go back and repeat the process with your own table. +Don't forget to add lots of sanity-checking code along the way. + +## A note on security + +It takes extra steps to secure a database connection and SQL methods. + +If this is the first time you've worked with a Zope database connection, there's an important security point you may not have considered: + +```{warning} +Zope Database Connections and Z SQL Methods are not part of the Plone workflow. +``` + +This means that you may not depend on the Plone content workflow to provide security for these connections and methods. +You must use the Zope security mechanisms directly to control access. + +This is also true of Python scripts and other Zope-level objects you might create via the Management Interface. +But Zope provides a safety net of security for most of those. +There is no such automatic safety net for external RDBMS access methods. + +The easiest way to do this is to use the Management Interface to visit the top-most folder of your form and use the Security tab to customize security. Look in particular for the Use Database Methods permission, and make sure it is not extended to any user role that should not have a right to read or update your external database. diff --git a/docs/guides/classic-ui/working-with-content/managing-content/previous-next-links.md b/docs/guides/classic-ui/working-with-content/managing-content/previous-next-links.md new file mode 100644 index 000000000..d3fce4b64 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/previous-next-links.md @@ -0,0 +1,11 @@ +(rst-prev-next-links)= + +# Next/Previous Navigation + +Automatic previous-next links for content items in a folder can be enabled under the Settings tab for a folder. + +The *Settings* tab is found by clicking the *Edit* tab for the folder. + +Once enabled, as content items are added to the folder, previous and next links will automatically appear at the bottom of each content item. + +This is a *really* useful feature! diff --git a/docs/guides/classic-ui/working-with-content/managing-content/reordering-items.md b/docs/guides/classic-ui/working-with-content/managing-content/reordering-items.md new file mode 100644 index 000000000..3efee65b4 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/reordering-items.md @@ -0,0 +1,10 @@ +# Reordering Items + +Using "Contents" on the Toolbar gives you the overview of a folder. From here, you can do manual reordering of items in a folder. + +```{figure} foldercontents-reorder.png +:align: center +:alt: reordering content + +Simply hover over the content item you want to reorder (any column is fine, just don't hover exactly over the title), and the cursor changes into a hand. Click and drag to reorder. +``` diff --git a/docs/guides/classic-ui/working-with-content/managing-content/versioning.md b/docs/guides/classic-ui/working-with-content/managing-content/versioning.md new file mode 100644 index 000000000..8e6687f63 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/versioning.md @@ -0,0 +1,57 @@ +# Versioning + +An overview on how to view the version history of an item, compare versions, preview previous versions and revert to previous versions. + +## Creating a new version + +Plone includes a versioning feature. +By default, the following content types have versioning enabled: + +- Pages +- News Items +- Events +- Links + +Note that all other content types do track workflow history (so, when an item was published, unpublished etcetera) + +Content items can be configured to have versioning enabled/disabled through the Site Setup Plone Configuration panel under "Types". + +When editing an item, you may use the **change note** field at the bottom; the change note will be stored in the item's version history. +If the change note is left blank, Plone includes a default note: "Initial Revision". + +A new version is created every time the item is saved. +Versioning keeps track of all kinds of edits: content, metadata, settings, etc. + +## Viewing the version history + +Once an item has been saved, you can see the **History** by clicking on the *clock* item in the Toolbar. + +```{figure} content-history.png +:align: center +:alt: History view of a content item +``` + +The most recent version is listed first. The History view provides the following information: + +- The type of edit (content or workflow) +- Which user made the edit +- What date and time the edit occurred + +In the above example, Jane created a Page, then published it. Then, she decided to edit the Page, change it's title and she put in "Title should be Hurray, not Sample Page." in the "Change notes" box. +Here you can see why it's good to put in change notes: you get a good overview of *why* an item was edited. + +## Comparing versions + +From the History viewlet you can compare any previous version with the current version or any other version with the version just before it. + +To compare any previous version with the one just before it, click the *Compare* link located between two adjacent versions in the History overlay. + +By clicking this button, you'll see a screen like this one where you can see the differences between the two versions: + +You may also compare any previous version to the *current* version by clicking the *Compare to current* link. + +## Viewing and reverting to previous versions + +**You can preview any previous version** of a document by clicking the *View* link to the right of any version listed. + +**To revert back to a previous version**, click on the *Revert to this revision* button to the right of any version listed. diff --git a/docs/guides/classic-ui/working-with-content/managing-content/working-copy.md b/docs/guides/classic-ui/working-with-content/managing-content/working-copy.md new file mode 100644 index 000000000..5a4a755d8 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/managing-content/working-copy.md @@ -0,0 +1,103 @@ +# Working Copy + +Working Copy lets you have two versions of your content in parallel. + +```{note} +When a Plone site is first created, there are a number of additional features that can be enabled, including "Working Copy". +If the Plone site you are using doesn't show the "Check out" option under the Actions menu, you will need to contact your site manager and request that "Working Copy Support (Iterate)" be installed. +``` + +## Overview + +You might have been in a situation like this before: you have published a document, and you need to update it extensively, but you want the old version to exist on the web site until you have published the new one. +You also want the new document to replace the current one, but you'd like to keep the history of the old one, just in case. + +Working copy makes all this possible. + +Essentially, you "check out" a version of the currently published document, which creates a "working copy" of the document. You then edit +the working copy (for as long as you like) and when you're ready for the new version to go live, you "check in" your working copy, and it's live. + +Behind the scenes, Plone will replace the original document with the new one in the exact same location and web address and archive the old +version as part of the document's version history. + +## Using "Check out" + +First, navigate to the page you want to check out. +Then from the "Actions" menu, select "Check out": + +```{figure} working-copy_checkout.png +:align: center +:alt: true +``` + +An info message will appear indicating you're now working with a working +copy: + +```{figure} working-copy_checkout-notification.png +:align: center +:alt: true +``` + +Now you're free to edit your own local copy of a published document. +During this time, the original document is "locked" -- that is, no one +else can edit that published version while you have a working copy +checked out. This will prevent other changes from being made to (and +subsequently lost from) the published version while you edit your copy. + +```{figure} working-copy_locked.png +:align: center +:alt: true +``` + +## Using "Check in" + +When you are ready to have your edited copy replace the published one, +simply choose "Check-in" from the "Actions" drop-down menu: + +```{figure} working-copy_checkin.png +:align: center +:alt: true +``` + +You will then be prompted to enter a Check-in message. +Fill it out and click on "Check in": + +```{figure} working-copy_checkin-form.png +:align: center +:alt: true +``` + +Your updated document will now replace the published copy and become the new published copy. + +You will also notice that there is no longer a copy of the document in the folder. + +Note that it is not necessary (and in fact, it is not recommended) to use the "State" drop-down menu on a working copy. +If you inadvertently do so, however, don't panic. Just go back to your working copy and use "Check in" from the "Actions" menu. + +## Canceling a "Check out" + +If for any reason it becomes necessary to cancel a check out and **you don't want to save any of your changes**, simply navigate to the working copy and select "Cancel check-out": + +```{figure} working-copy_cancel-checkout.png +:align: center +:alt: true +``` + +You will prompted to confirm the "Cancel checkout" or to "Keep checkout": + +```{figure} working-copy_cancel-checkout-form.png +:align: center +:alt: true +``` + +```{note} +If the user who has checked out a working copy is not available to check in or cancel a check out, users with the Manager role may navigate to the working copy and perform either the check in or cancel check out actions. +That's because not all contributors have the *Check in* privilege. If that option is missing from your *Actions* menu: + +1. Use the *State* menu. +2. Submit for publication. +3. Ask a reviewer to **not** change the state. +4. Ask the reviewer to perform the check in on your behalf instead. + +The check in routine will handle the state. +``` diff --git a/docs/guides/classic-ui/working-with-content/managing-content/working-copy_cancel-checkout-form.png b/docs/guides/classic-ui/working-with-content/managing-content/working-copy_cancel-checkout-form.png new file mode 100644 index 000000000..16e6080a3 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/working-copy_cancel-checkout-form.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/working-copy_cancel-checkout.png b/docs/guides/classic-ui/working-with-content/managing-content/working-copy_cancel-checkout.png new file mode 100644 index 000000000..5d317f50a Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/working-copy_cancel-checkout.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/working-copy_checkin-form.png b/docs/guides/classic-ui/working-with-content/managing-content/working-copy_checkin-form.png new file mode 100644 index 000000000..6723d9679 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/working-copy_checkin-form.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/working-copy_checkin.png b/docs/guides/classic-ui/working-with-content/managing-content/working-copy_checkin.png new file mode 100644 index 000000000..ad0abf522 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/working-copy_checkin.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/working-copy_checkout-notification.png b/docs/guides/classic-ui/working-with-content/managing-content/working-copy_checkout-notification.png new file mode 100644 index 000000000..57178ef42 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/working-copy_checkout-notification.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/working-copy_checkout.png b/docs/guides/classic-ui/working-with-content/managing-content/working-copy_checkout.png new file mode 100644 index 000000000..eae4a1db4 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/working-copy_checkout.png differ diff --git a/docs/guides/classic-ui/working-with-content/managing-content/working-copy_locked.png b/docs/guides/classic-ui/working-with-content/managing-content/working-copy_locked.png new file mode 100644 index 000000000..3ff82bbaf Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/managing-content/working-copy_locked.png differ diff --git a/docs/guides/classic-ui/working-with-content/portlet-management/hierarchy.png b/docs/guides/classic-ui/working-with-content/portlet-management/hierarchy.png new file mode 100644 index 000000000..e6809ae19 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/portlet-management/hierarchy.png differ diff --git a/docs/guides/classic-ui/working-with-content/portlet-management/index.md b/docs/guides/classic-ui/working-with-content/portlet-management/index.md new file mode 100644 index 000000000..6c62c8cb2 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/portlet-management/index.md @@ -0,0 +1,11 @@ +# Portlet Management + +An introduction to the use and management of portlets. + +```{toctree} +:maxdepth: 2 + +managing-portlets +portlet-hierarchy +portlet-types +``` diff --git a/docs/guides/classic-ui/working-with-content/portlet-management/managing-portlets.md b/docs/guides/classic-ui/working-with-content/portlet-management/managing-portlets.md new file mode 100644 index 000000000..b35261761 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/portlet-management/managing-portlets.md @@ -0,0 +1,58 @@ +# Managing Portlets + +To assign the different {doc}`types of portlet <portlet-types>` into your site, use the "Manage portlets" item on the Toolbar. + +There are three locations where portlets can be put: to the left, to the right, and in the footer. + +```{note} +The "left", "right" and "footer" locations come from the classical website design. It is entirely possible, using Diazo theming, to move these portlet locations from one place to another. In fact, many so-called *responsive* designs, that automatically scale for mobile devices, will not display these as 'left' and 'right'. + +There is still a relevance to these different locations, even on mobile devices: as a rule of thumb, the 'left' portlets will be displayed **before** the main content, and the 'right' portlets afterwards, with the 'footer' portlets last. +``` + +```{figure} portlet-menu.png +:align: center +:alt: Where to find the Portlet menu on the Toolbar +``` + +From here, you choose which region you want to work on. In the example below, we are working on the "footer portlets" + +```{note} +The footer portlet region is new for Plone 5. If you have worked on previous versions of Plone: this is where you now can find (and edit) the colophon and other items. +``` + +```{figure} portlet-footer.png +:align: center +:alt: List of footer portlets +``` + +The various options for "blocking" are explained in the {doc}`Portlet hierarchy <portlet-hierarchy>` section. + +## Adding a Portlet + +Adding a Portlet is as simple as selecting the **Add Portlet** drop down box and clicking on the type of Portlet you would like to add. +We will cover the different options available in the {doc}`next section <portlet-types>`. + +## Editing an Existing Portlet + +To edit the properties of an existing Portlet, simply click on the name of the Portlet. +If we wanted to edit the properties of the Navigation Portlet, we would Click on *Navigation*. +Each type of Portlet will have different configuration options available to it. + +## Rearranging Portlets + +To rearrange your Portlets, simply click the **up or down arrow**. +This will affect the order your Portlets are displayed on the page. + +## Removing Portlets + +To remove a Portlet, click the **"X"** associated with its name. + +## Hiding Portlets + +You can show/hide portlets using the associated show/hide link. + +## Adding multiple portlets + +With Portlets, you can add more than one of the same type on a page. +There is no limit (except common sense) to how many times you can use an individual Portlet or a limit to how many total Portlets can be on a Page. diff --git a/docs/guides/classic-ui/working-with-content/portlet-management/portlet-footer.png b/docs/guides/classic-ui/working-with-content/portlet-management/portlet-footer.png new file mode 100644 index 000000000..84b6907ca Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/portlet-management/portlet-footer.png differ diff --git a/docs/guides/classic-ui/working-with-content/portlet-management/portlet-hierarchy.md b/docs/guides/classic-ui/working-with-content/portlet-management/portlet-hierarchy.md new file mode 100644 index 000000000..3846d5855 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/portlet-management/portlet-hierarchy.md @@ -0,0 +1,52 @@ +# Portlet Hierarchy + +Portlets use a basic hierarchy approach which determines how and why they appear on each section of your site. + +By default, the portlets that you assign at the root (homepage) of the site will propogate down to all the subsections of the site. + +If you want a different set of portlets or order of portlets for a particular sub-section, you can use the **Block/unblock portlets** controls, to "block" the parent portlets. +When you block Portlets, you must explicitly add all the Portlets that +you wish to see on the child page. + +There are some specific sets of portlets: + +Group Portlets + +: Created by your Site Manager for Groups of Users. + +Content Type Portlets + +: Assigned in the Plone Control Panel to specific Content Types by your Site Manager . + +They can be blocked or unblocked separately from the (much more used) "Parent portlets" + +```{note} +Beware of the {doc}`default view for a Folder </working-with-content/managing-content/folder-view>`. + +When you set about creating Portlets that you want to propagate, be careful to that you are creating the Portlet at the Site Root or Folder and not at the Default View for that folder. +``` + +In this diagram, our Portlets are designated in blue underneath the Page +title: + +```{figure} hierarchy.png +:align: center + +Portlet Hierarchy +``` + +As you can see we have two Portlets designated on our Home page (navigation and recent items). +These same Portlets appear on our About Page because of portlet hierarchy. + +However, on the Documentation page we added a third portlet - the Collection Portlet. +Here we are still allowing Parental Portlets, but in addition we specifically added the Collection Portlet. + +On **both** the Tutorials and Videos Pages we have to block Parental Portlets because we do not want the Collection Portlet that is on the Documentation Page to show. +When we block Parental Portlets we must re-add the Portlets to **each** Child page. +In this case we re-added the Navigation Portlet to both and then added the Search Portlet to both. + +Remember that the child pages only inherit from the parent page directly above them. +In our example, if we added a page called *Staff* under About and allowed the parent portlets without adding any additional portlets, it would show the same Portlets as the Home Page as well as the About Page. +However do not think that it is inheriting from the Home page. +If we were to change the About Page and added a Search Portlet, our Staff Page would reflect the Portlets on the About Page not the Home +Page. diff --git a/docs/guides/classic-ui/working-with-content/portlet-management/portlet-menu.png b/docs/guides/classic-ui/working-with-content/portlet-management/portlet-menu.png new file mode 100644 index 000000000..ce3e28624 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/portlet-management/portlet-menu.png differ diff --git a/docs/guides/classic-ui/working-with-content/portlet-management/portlet-types.md b/docs/guides/classic-ui/working-with-content/portlet-management/portlet-types.md new file mode 100644 index 000000000..8d7e67114 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/portlet-management/portlet-types.md @@ -0,0 +1,111 @@ +# Portlet Types + +Descriptions of each Portlet Type + +There are several different types of Portlets to choose from. + +```{note} +These are the default portlets for Plone 5. + +: Your site may have more available, as many add-ons come with their own portlets. +``` + +## Navigation + +The Navigation Portlet **allows users to navigate your site** with ease by providing a structured "site map", or navigation tree. + +You have the option to display the navigation for the overall site or choose to display the current folder contents. + +As you dig deeper into the site, the tree will continue to expand. + +There are several configuration options available that effect how the Navigation Portlet will behave. + +You can set the *Title*, the *Root node* (which is from where the tree will start), and various other options to limit how deep you want to expand the tree. + +## Calendar + +The Calendar Portlet is a simple Portlet that will display a Calendar on your site. + +The main use is to highlight "Events". + +You can choose what the workflow state of the Events (or other items like it) should be, and can choose whether you want all events on your site or only the ones within a given subfolder. + +If you have published Event content objects on your site, the days upon which they occur will be highlighted in the calendar and will link to the corresponding events on your site. + +## Collection + +The Collection Portlet will allow you to **display the results of a Collection**. + +You must have a Collection previously created when you add this Portlet, then you can specifying the Collection to be used. + +This is a great way to present targeted queries like for example "newest pages with tag "Latin America". + +## Events + +The Events Portlet will **display Upcoming Events**, provided that you have Events on your site. +You can determine how many events you want to be displayed and also which events you want to display based on publishing state. + +## Log in + +The Log in Portlet is another non configurable Portlet that will simply **display a Log in Form** that will allow users with Log in information to log in to the site. + +Once a user is logged into the site, this Portlet will not appear. + +## News + +The News Portlet works exactly like the Events Portlet. + +Instead of displaying Events, it **displays recent News items**. + +Once again you can choose how many News items are displayed and filter them based on their state. + +```{note} +Both the "News" and "Events" portlets could be created by using a "Collection" portlet which finds the right content items. + +They are provided for convenience. +``` + +## RSS Feeds + +The RSS Feed Portlet allows you to link to an RSS Feed, choose how many items to display, and specify the refresh rate. + +## Recent Items + +The Recent Items Portlet displays a customizable **number of Recent Items**, listed by Title. +A Recent Item is determined by its Last Modified Date. + +## Review List + +The Review List Portlet will display a **list of objects that have been submitted for review**. + +If you are using a submit and review cycle (and have properly set global roles for your users) this is a great way for reviewers to see what content has been submitted for review. + +This Portlet only appears to those logged in as this state is not viewable to the public. + +## Search + +The Search Portlet will place a search box in your Portlet Column. +This search box will search the Titles, Descriptions, and Body text of objects on your site for the text specified. + +You have the option of enabling Live Search. + +Live Search is a feature which shows live results if the browser supports JavaScript. + +## Static Text + +The Static Text Portlet allows you to enter content just as you would on a normal Page object. +This is useful for adding for example contact information, your company motto, or any information that is relatively static. + +## Classic + +A Classic Portlet is refers to the way portlets were used in older version of Plone, prior to Plone 3. + +You must create a Page Template in the Management Interface and properly set the path and macro to enable the portlet. + +This requires technical knowledege of both TALES and the Management Interface. + +```{warning} +The 'classic' portlet is provided strictly for sites that have very old legacy code. + +You should refrain from using it in any modern Plone site. +``` diff --git a/docs/guides/classic-ui/working-with-content/using-collections/index.md b/docs/guides/classic-ui/working-with-content/using-collections/index.md new file mode 100644 index 000000000..86789487e --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/using-collections/index.md @@ -0,0 +1,27 @@ +# Using Listings & Queries (Collections) + +Collections take advantage of the intelligence of Plone. + +Think of them as automatically updated queries, with criteria that you define. As new pieces of content are added, they will show up in these Collections if they match the criteria. + +Collections have gone through various iterations, since Plone 4.2 the so-called 'newstyle' collections are enabled by default. These are easy to create and maintain. + +```{toctree} +:maxdepth: 2 + +newstyle/introduction-to-collections +newstyle/creating_collections +``` + +Before that, there were 'oldstyle' Collections. Setting them up was a bit less streamlined, but for power users they can have more flexibility, which is why you can enable them in your site if wanted. + +```{toctree} +:maxdepth: 1 + +oldstyle/introduction-to-collections +oldstyle/adding-collections +oldstyle/adjusting-the-display-settings +oldstyle/definition-of-criteria +oldstyle/setting-the-sort-order +oldstyle/using-and-understanding-dates +``` diff --git a/docs/guides/classic-ui/working-with-content/using-collections/newstyle/collection1.png b/docs/guides/classic-ui/working-with-content/using-collections/newstyle/collection1.png new file mode 100644 index 000000000..91620fac9 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/using-collections/newstyle/collection1.png differ diff --git a/docs/guides/classic-ui/working-with-content/using-collections/newstyle/collection2.png b/docs/guides/classic-ui/working-with-content/using-collections/newstyle/collection2.png new file mode 100644 index 000000000..526696c39 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/using-collections/newstyle/collection2.png differ diff --git a/docs/guides/classic-ui/working-with-content/using-collections/newstyle/collection3.png b/docs/guides/classic-ui/working-with-content/using-collections/newstyle/collection3.png new file mode 100644 index 000000000..89903b3a6 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/using-collections/newstyle/collection3.png differ diff --git a/docs/guides/classic-ui/working-with-content/using-collections/newstyle/creating_collections.md b/docs/guides/classic-ui/working-with-content/using-collections/newstyle/creating_collections.md new file mode 100644 index 000000000..8e7aa1424 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/using-collections/newstyle/creating_collections.md @@ -0,0 +1,33 @@ +# Creating a collection + +When you add a new collection, you can select from a lot of different options. + +The content type (Page, Event, Folder, etcetera), various dates, the location in the site and also keywords or tags are available as selection criteria. + +```{figure} collection1.png +:align: center +:alt: choosing criteria +``` + +While you're adding criteria, the number of content items that fit those criteria is dynamically updated. + +```{figure} collection2.png +:align: center +:alt: Content items are dynamically updated +``` + +By combining more criteria, you can create sophisticated queries, which will be automatically updated. + +The combination shown below will always show upcoming events: + +- content type is event +- the start date must be within 31 days from now + +```{figure} collection3.png +:align: center +:alt: select upcoming events +``` + +The resulting "Collection" works much like a Folder, only it is always up-to-date according to the criteria you set. + +Please experiment with Collections, they are one of the most powerful features of Plone! diff --git a/docs/guides/classic-ui/working-with-content/using-collections/newstyle/introduction-to-collections.md b/docs/guides/classic-ui/working-with-content/using-collections/newstyle/introduction-to-collections.md new file mode 100644 index 000000000..8b7a88f73 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/using-collections/newstyle/introduction-to-collections.md @@ -0,0 +1,29 @@ +# Introduction to (new-style) Collections + +A Collection in Plone works much like a report or query does in a database. +Use Collections to dynamically sort and display your content. + +A **Collection** in Plone works much like a report or query does in a database. +The idea is that you use a Collection to search your website based on a set of **Criteria** such as: content type (page, news item, image), the date it was published, or keywords contained in the title, description, or body. + +Let's say you have a large catalog of photos and maps on your website. +You can display them all at once by creating a link to the folder they're stored in. +You could even create different links for subfolders if you've organized things that way. +However, if your images and maps were spread out over the site in many folders this would quickly become cumbersome. +Also, there is no way with normal folders to display different content, from different parts of your site based on things like: + +- keywords in the title +- date of creation +- author +- type of content + +The need for showing content in a variety of dynamic ways has given rise to **Collections** (formerly known as **Smart Folders**, or **Rich Topic** in older versions of Plone). +Collections do not actually contain any content items themselves in the same way that a folder does. +Instead it is the **Criteria** that you establish which determines what content appears on each Collection page. + +Common applications for Collections are: + +- News Archives +- Event Archives +- Photos Displayed by Date Range +- Content Displayed by Keyword diff --git a/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/adding-collections.md b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/adding-collections.md new file mode 100644 index 000000000..dc0dd0361 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/adding-collections.md @@ -0,0 +1,79 @@ +# Adding Collections + +Collections (formerly called Smart Folders) are virtual containers of +lists of items found by doing a specialized search. + +Learning to think about content being stored wherever it is stored, and +about using custom collections to gather up different "views" of the +content, is an important step to using Plone most effectively. It is an +intelligent system. + +To add a collection, use the *Add new...* menu, as for adding other +content types: + +```{figure} p4_addnewmenu.png +:align: center +:alt: p4\_addnewmenu + +p4_addnewmenu +``` + +You will see the Add\*Collection\*panel: + +```{figure} copy_of_p4_addcollection.png +:align: center +:alt: p4\_addcollection2 + +p4_addcollection2 +``` + +Below the title and description fields is a set of fields for specifying +the format of search results returned by the search criterion for the +new collection. The four fields in the panel above are in pairs. The top +two fields let you limit the search results to a number of items that +will be displayed. The bottom two fields let you control the order of +the search result items. + +## Setting the search criterion + +After setting the display configuration in the edit panel shown above, +click the criteria tab to show the panel for setting search criteria: + +```{figure} copy2_of_copy_of_p4_collectionssearchcrit1.png +:align: center +:alt: p4\_collectionssearchcrit1 2 + +p4_collectionssearchcrit1 2 +``` + +The top area of the panel, *Add New Search Criteria*, lets you set a +field and a matching criterion. The bottom area, *Set Sort Order*, is a +simple selection for a field to sort on: + +```{figure} copy_of_p4_collectionssearchcrit2.png +:align: center +:alt: p4\_collectionssearchcrit2 2 + +p4_collectionssearchcrit2 2 +``` + +The criteria types for matching data in content items depend on which +field is selected. + +After saving the collection, the search criteria will be applied and the +results shown when the collection is clicked. You can create any number +of collections for such custom views. For the butterfly example +described above, in addition to a date constraint to find recent items, +the categories field could be used to match color to have a series of +collections for "Blue Butterflies," "White Butterfles," etc. + +Multiple criteria can be used for a collection. For example, a +collection called "Butterflies Photographed in the Last Month," could be +made by setting a criterion on Creation Date and on Item Type as Image. +Such date-based collections are really effective to show up-to-date +views of content that don't require any administrative hand-work -- once +such a collection has been created, it will automatically stay up to +date. + +*Note:* A collection doesn't behave like a normal folder, you can't +add content items via the add item menu, as you can for a normal folder. diff --git a/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/adjusting-the-display-settings.md b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/adjusting-the-display-settings.md new file mode 100644 index 000000000..167f4a3d1 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/adjusting-the-display-settings.md @@ -0,0 +1,53 @@ +# Adjusting the Display Settings + +Learn how display settings can change the look of your Collection page + +While the main power of Collections lies in Criteria, the display +settings can make a big difference in the way your Collection will +appear. All three of the settings we will cover in this section can be +found by clicking the **Edit tab** of a Collection. + +**Inherit Criteria** + +By selecting the **Inherit Criteria** option, the Collection will +inherit the Criteria from a parent Collection. This is only useful when +using Sub Collections. If this is checked, you can create another +Collection that is more specific than the Parent while still retaining +the basic criteria of the Parent. A simple example might be a Parent +Collection for displaying all Events in a site, and a Sub Collection +that also displays Events (by inheriting Criteria) *but only* those +Events with a particular keyword. + +**Limit Search Results** + +We can use Limit Search Results to limit the number of results that +are Collection will display *per page*. This way if we have a Collection +that is displaying News Items, we can limit the results to five or ten, +instead of having it show all News Items on a single, large list. + +**Display as a Table** + +Display as a Table is simply another way to display the results of a +Collection. Instead of having the Collection spit out the results in a +list form, we can have it **generate a table** with the results, and set +exactly what information about the results we want displayed. We +customize the table by selecting the **Table Columns** from the left and +clicking the right arrow button to move it over to the right. In the +example above we chose to include the Title of the object, its Creator, +and the Effective date. You can use any number of the columns, or all of +them if you so choose. + +When considering what to select, keep in mind that not all objects will +have the information for every column available. For example, the +**Start Date** and **End Date** only apply to Events. Therefore if you +added these columns and your table included Pages as well as Events then +the rows for the Pages would not have the Start and End Dates filled in. +The other thing to consider is that the more columns you have showing +the more crowded the table will become. The best rule of thumb is to +only display what you absolutely need to display. + +A few more notes on selecting columns: You can select more than one at a +time by holding down the control key (Ctrl) while you click. If you want +to remove a column, select it on the right and click on the left arrow +button. Also you can add and remove columns by double clicking on their +name. diff --git a/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/copy2_of_copy_of_p4_collectionssearchcrit1.png b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/copy2_of_copy_of_p4_collectionssearchcrit1.png new file mode 100644 index 000000000..2d42521b2 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/copy2_of_copy_of_p4_collectionssearchcrit1.png differ diff --git a/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/copy_of_p4_addcollection.png b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/copy_of_p4_addcollection.png new file mode 100644 index 000000000..fa8fff269 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/copy_of_p4_addcollection.png differ diff --git a/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/copy_of_p4_collectionssearchcrit2.png b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/copy_of_p4_collectionssearchcrit2.png new file mode 100644 index 000000000..e3ce86af5 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/copy_of_p4_collectionssearchcrit2.png differ diff --git a/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/definition-of-criteria.md b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/definition-of-criteria.md new file mode 100644 index 000000000..6cbc953e9 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/definition-of-criteria.md @@ -0,0 +1,122 @@ +# Definition of Criteria + +Definitions and examples of the different criteria fields available + +The power of Collections most certainly lies with the Criteria fields. +Mastering how to use the different Criteria will allow you to use +Collections in several useful ways. In this section, we will use +examples to illustrate the many ways of using Criteria. + +## Categories + +The Category criterion allows you to search the **Category field** of +objects. For this to work you must specify Categories for the content +objects ahead of time (this is done through the Categorization tab on +content objects). An example where you could use this is you want to +create a Collection that would display all objects relating to the +Category *Organization*. As you can see in the image below, we are able +to select the value *Organization* for our criterion. Then, by saving +this criterion and viewing our Collection, the results would be all +content objects we had designated with the Category *Organization*. + +Once again the values available to you are completely dependent on what +you have specified on your objects in the Categorization tab. + +## Creator + +When using the Creator criterion, we are **filtering objects based on +who created them**. This might be useful if you want to do a featured +author section, where you would only want to display content on your +site that has been created by a certain author. + +As you can see we have several options for our criterion type. They +allow us to restrict the creator to the person currently logged in, +enter the name of another user as text, or to select users from a list. + +If you want to display results from multiple users, you would need to +use the **List of Values** option. Otherwise you would normally use the +Text option unless the creator you wanted to select was yourself in +which case you would use Restrict to Current User. + +## Description + +The Description field is essentially a **search box type** criterion. +However, instead of searching the title and body of a page, it will +**only search for the text in the Description field** of a content +object. This criterion is only really useful if you fill out the +Description field consistently for all your content objects. + +## Location + +Using the Location criterion is much like specifying a location when you +search for a document on your hard drive. By specifying a Location +criterion, **the results that are displayed in your Collection will only +come from that location**, most commonly a Folder. This can be useful if +you only want to display content that is in the About Us section of your +site, for example. This is also useful for narrowing Collection results +when combined with other criteria. + +To specify a Location, simply click the **Add button**, which will pop +up a new window showing you a directory of your site. If we follow our +example and want to search the About Us section of our site, we would +click the Insert button next to the About Us folder. + +You can open folders to view content contained within them either by +clicking the Browse button or directly on the title of the folder you +want to open. You may also use the Search box to search for the Title of +an object. + +## Search Text + +The Search Text is a very useful criterion. It is similar to the search +box on your site or an Internet search engine. It takes the text you +specify and searches the Title, Description, and Body of all objects and +returns **any that have the word or phrase you specify**. This is useful +when you want to find objects that have to deal with a certain thing, +especially if the word or phrase appears across many content types. +Using training.plone.org as an example, if I want to create a Collection +that displays all objects that reference the word Collections, I would +use the Search Text criterion and specify *collections*. All Tutorials, +Videos, Glossary items, etc with *collections* in the Title, +Description, or Body would then appear in the Collection results. + +## Related To + +The Related To field is another field, like Category, that **must be +specified on a content object prior to being used for a Collection**. +The Related To field on an object lets you specify which other objects +in your site are similar or are relevant to the object you created. By +specifying this field, when you create an object you can create a web of +related content that will reference each other (think of a "see also" +kind of function). When you have done this, you can use the Related To +criterion in a Collection to display anything related to a specific +object. + +In this case we have specified that there are pages related to Our +Staff, History, and the About Us Homepage. By selecting one or multiple +values from this list, our Collection will display the pages that +related to that Value. + +If we selected History as the value we wanted, our Collection would show +us everything that is related to the History page. + +Keep in mind that the Related To Values list does not work based on +which objects are related to content but on which objects have another +object related **to it**. The Collection will display the results that +are related to that value. + +## State + +Using the State criterion is very simple. It allows us to **sort by +published or private** state. It is a very good idea to restrict +publicly viewable Collections **to filter on published**, so that no +private content appears in the Collection results. Filtering on the +Private state can be useful as well. For example, a site administrator +might want to quickly see private content, so that they could determine +what work needs to be done and what could deleted. + +## Dates + +You may have noticed that there are **several different dates +available** to use as Criteria. Since there are such a large number of +dates, they will be covered in {doc}`their own section of the manual <using-and-understanding-dates>` diff --git a/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/introduction-to-collections.md b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/introduction-to-collections.md new file mode 100644 index 000000000..6cc1e0d8a --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/introduction-to-collections.md @@ -0,0 +1,29 @@ +# Introduction to (old-style) Collections + +A Collection in Plone works much like a report or query does in a database. +Use Collections to dynamically sort and display your content. + +A **Collection** in Plone works much like a report or query does in a database. +The idea is that you use a Collection to search your website based on a set of **Criteria** such as: content type (page, news item, image), the date it was published, or keywords contained in the title, description, or body. + +Let's say you have a large catalog of photos and maps on your website. +You can display them all at once by creating a link to the folder they're stored in. +You could even create different links for subfolders if you've organized things that way. +However, if your images and maps were spread out over the site in many folders this would quickly become cumbersome. +Also, there is no way with normal folders to display different content, from different parts of your site based on things like: + +- keywords in the title +- date of creation +- author +- type of content + +The need for showing content in a variety of dynamic ways has given rise to **Collections** (formerly known as **Smart Folders**, or **Rich Topic** in older versions of Plone). +Collections do not actually contain any content items themselves in the same way that a folder does. +Instead it is the **Criteria** that you establish which determines what content appears on each Collection page. + +Common applications for Collections are: + +- News Archives +- Event Archives +- Photos Displayed by Date Range +- Content Displayed by Keyword diff --git a/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/p4_addnewmenu.png b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/p4_addnewmenu.png new file mode 100644 index 000000000..0c38c7ea1 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/p4_addnewmenu.png differ diff --git a/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/setting-the-sort-order.md b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/setting-the-sort-order.md new file mode 100644 index 000000000..c977e21ba --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/setting-the-sort-order.md @@ -0,0 +1,80 @@ +# Setting the Sort Order + +Learn how to use the Sort Order feature to customize the order in which +your results display + +The Sort Order **determines the order the results of the Collection will +be displayed in**. Sort Order allows you to sort by three main +categories: text, object properties, and dates. When you sort by text, +objects will be sorted in alphabetical order. When sorting by one of the +object properties, we effectively are grouping objects together by the +specified properties. When we sort by a date the results will be +displayed with the most recent first (although there are many 'dates' in +Plone). All Sort Orders are in Ascending Order unless the Reverse Order +check box is selected. By checking this we can display in reverse order, +or newest dates first, etc. + +## **Dates** + +There are numerous Date options which will be explained in the next +section of the manual. + +## Object Properties + +**Item Type** + +When sorting by Item Type, we end up with a Collection that has results +that are grouped by Item Type. We would want to use this if we have a +Collection that will return many different Item Types. This way we can +make the Collection very easy to browse for the site visitor. + +**State** + +Sorting by State will display results grouped by the publishing state. +Since there are only two States in the default configuration of Plone, +there will only be Published and Private items. We can use this to +separate all pages on our site and see what we have that is +public (Published) and what we are hiding from the public eye (Private). + +**Category** + +Category Sort Order is useful when we want to display the objects on our +site in a manner where they are grouped by the Category we placed them +in. Keep in mind, for sorting by Category to even be remotely useful, +you must have specified the Category on several objects. If you have not +specified any Categories, then sorting by Categories will do nothing. + +**Related To** + +The Related To Sort Order will actually apply a criterion to your +Collection. It limits to the results to only those that have Related To +information specified on their properties. + +## Text + +**Short Name** + +Sorting by the Short Name is the same as putting the result objects in +alphabetical order. By default Plone sets the Short Name of an object to +be the same as the Title. The difference between the two is that the +Short Name is all lower case and hyphenated between all words. For +example the Short Name for the page titled About Us would be *about-us*. +The Short Name is what Plone also uses in the URL for the page +(www.myplonesite.org/about-us). You can specify a different Short Name +for an object by using the Rename button on the Contents tab. + +**Creator** + +Sorting by the Creator will group all results in alphabetical order by +their author. For example, let's say we had several documents published +by Bob Baker and several of other documents published by Jane Smith. +Sorting by the creator would result in all the documents created by Bob +Baker listed first followed by those of Jane Smith. + +**Title** + +Sorting by Title will display the results in alphabetical order, by +the object titles. + +Next we will cover the Dates that we skipped over in this section as +well as the Criteria Field section. diff --git a/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/using-and-understanding-dates.md b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/using-and-understanding-dates.md new file mode 100644 index 000000000..7624d8ce7 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/using-collections/oldstyle/using-and-understanding-dates.md @@ -0,0 +1,130 @@ +# Using and Understanding Dates + +Explanation of the Dates associated with Collections and their uses + +There are several different types of dates we can choose from, many of +them sounding similar. Because of this it is very easy to get confused +about which date to use. Below, each date option is defined. + +## Dates Defined + +**Creation Date** +The Creation Date is the date the document was made. You can think of +this as its birthday, the day it was born. You cannot change the +Creation Date of an object. + +**Effective Date** +The Effective Date is the date when an object becomes published. This +date is customizable through the **Edit tab** on objects under the +**Date tab**. However, there it is referred to as the Publishing Date (a +minor discrepancy in Plone's nomenclature). + +**Creation Date** and **Effective Date** are very similar. They both are +representative of the beginning point of an object. A very important +point to keep in mind when choosing which one you want to use, is that +an object can be created long before it ever becomes public. You could +have a page that is worked on for several weeks before it is actually +published. Thus you would get different results in a Collection +depending on which date you used. +We recommend using the **Effective Date**, instead of Creation Date for +date-oriented Collections. This way your Collection shows results based +on when they became viewable to the public, which is more relevant to +the audience of your Collection. Also, you can go in and manually adjust +the Effective Date to control the sort order which is not something you +can do with the Creation Date. + +**Expiration Date** +The Expiration Date refers to the day that the item will no longer +become publicly available. This date is also customizable through the +Edit tab (shown above) like the Effective Date. By default, objects have +no Expiration Date. + +**Modification Date** +The Modification Date is the date the object was last edited. Note that +this date is first set the day the object is created and will +automatically change every time the object is edited. There is no way to +customize this date. You could use this as a Sort Order along with an +Item Type criterion set to Page, to display all recently modified pages +within the last week, for example. The What's New listing on the +homepage of LearnPlone.Org uses Modification Date as its date criterion. +That way both newly created documents *and* ones that have been updated +appear in the listing. + +**Event Specific Dates** +The two following dates **only** apply to objects that +are **Events.** These two dates are very effective for creating Recent +Events and Upcoming Events Collections that will let your audience know +what your organization is doing and will be doing in the future. + +**Start Date** +The Start Date is simply the date that an Event starts. + +**End Date** +The End Date is simply the date that the Event ends. + +**Publication Date** + +The Publication Date is the date when object was last published. It can +either be set manually by means of Effective Date field or, if the +latter hasn't been set, calculated based on date when object was last +published. + +To display Publication Date on your pages you need to switch it on with +*"Display publication date in 'about' information"* option in **Site +Settings Control Panel**. Publication Date will be visible right before +object Modification Date inside 'about' information area. Make sure +*"Allow anyone to view 'about' information"* option is also enabled +inside **Security Settings Control Panel** to make it all work. + +## Setting Dates + +A confusing thing about dates can be how its Criteria are set up. They +have a setup that is not like any of the other Criteria. First off, you +have to choose whether you want a Relative Date or a Date Range. + +The Relative Date allows you to construct a **conditional statement**. +Such as: Items modified less than 5 days in the past. A Date Range will +allow you to **specify an exact range of dates**, such as 01/02/08 to +02/02/08. The Date Range is useful when you want to create a Collection +with a static date that won't change. The Relative Date can be very +useful as it will allow you to create Collections that are automatically +updating themselves, such as a Recent News Collections or an Upcoming +Event Section. + +## Relative Date + +Looking first at the Relative Date option, you can see we have three +options to fill out. + +The first option is **Which Day**. This allows us to select the number +of days our criterion will include. One of the options is called *Now*. +Using this will set the date range to the current day. The other two +options do not matter and can be ignored when using *Now*. + +The second option is **In the Past or Future**. This enables us to +choose whether we are looking forward or backward into time. + +The last option is **More or Less**. Here we can choose from three +options. *Less than* allows us to include everything from now to a +period of time equal to or less than the **Which Day** setting, either in +the past or future. *More than* will include everything from beyond our +specified number of days equal to or more than **Which Day**. Finally +*On the Day* will only include things that are on the day we specified in +the **Which Day**. Using the example in the image above if we had +selected *On the Day* instead of *Less than* our Collection would +display only objects that were modified (we are using the Modification +Date criterion) 5 days ago. + +If this is confusing to you, try reading it as a statement substituting +in the field options you chose. "I want the results to include objects +**More or Less** than **Which Day**, **In the Past or Future**". Our +example in the image above would become "I want the results to include +objects **Less than** **5 days in the past**". + +## Date Range + +The **Date Range** is much easier to understand. Both a Start Date and +End Date are required (do not confuse these terms with the Event +Specific dates!). The Date Range allows us to enter a beginning and an +end date and the display everything within that time frame. Notice also +that it allows us to specify a specific time of day as well. diff --git a/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/basics.md b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/basics.md new file mode 100644 index 000000000..21fd81b50 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/basics.md @@ -0,0 +1,28 @@ +# Basics + +Basic options of TinyMCE. + +The default TinyMCE editor will look like this: + +```{figure} tinymce.png +:align: center +:alt: true +``` + +On top you can see the toolbar, below the text area with the actual content you are editing and at the bottom a status bar. +If you drag the lower right corner you can make the editor window bigger or smaller. + +The editor allows you to style text, add images and links, add tables and more. + +```{note} +Although it may look like a word-processor on your desktop computer, editing text for the web is slightly different. +You would create headlines by selecting the "Formats" dropdown, and then choose "Header 1" (biggest) to "Header 6" (smallest). + +You would **not** choose the font and size directly, those are set up by the theme. This will ensure a consistent look over your site, and it is also important to make content available to different devices (phones, tablets) and to ensure the best result for people with disabilities. +``` + +The toolbar icons and dropdowns generally work as you would expect. + +Some of the more interesting ones are explained in the sections {doc}`Inserting images <inserting-images>`, {doc}`Inserting links <inserting-links>` and {doc}`Inserting tables <inserting-tables>`. + +If you want to get at the pure HTML source code of your text, just use the 'Tools' menu. diff --git a/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/index.md b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/index.md new file mode 100644 index 000000000..d1bd16407 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/index.md @@ -0,0 +1,13 @@ +# Using TinyMCE as visual editor + +A user manual for content creators + +```{toctree} +:maxdepth: 2 + +introduction +basics +inserting-images +inserting-links +inserting-tables +``` diff --git a/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/inserting-images.md b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/inserting-images.md new file mode 100644 index 000000000..c0afae532 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/inserting-images.md @@ -0,0 +1,37 @@ +# Inserting Images + +The TinyMCE editor allows you to insert image files stored in Plone into your document, using the Image button on the TinyMCE toolbar: + +```{figure} tinymce-imgbutton.png +:align: center +:alt: true +``` + +Clicking this button launches the Insert Image dialog: + +```{figure} tinymce-imgdialog.png +:align: center +:alt: true +``` + +There are three ways to select images: + +Internal image + +: This means the image is already on the site somewhere. You can search on it by title or description, or navigate to it. + +Upload + +: This means using an image file you already have on your computer. The image will be uploaded to the same folder as the content item you are editing. + +External Image + +: This means specifying the URL of an image that is elsewhere on the web. + +For all three methods, you can set the Title, ALT text (this is important for non-sighted users, make this a description of the image) and the alignment. Aligning "inline" means the image will appear exactly where you put it, in the middle of a sentence if wanted. Aligning "left" or "right" will make the image go to the side of the paragraph, and text will flow around it. + +For Internal and Uploaded images, you can also select the size. These sizes come from the range of sizes that you (or your site administrator) has set in the Image Handling Settings control panel. Plone automatically generates the different sizes when you upload an image. + +```{note} +Be careful with the size "original". Modern cameras and smartphones take high-resolution pictures, much higher than is usually needed in a website. Larger pictures take longer to download, making your site slower to appear. +``` diff --git a/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/inserting-links.md b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/inserting-links.md new file mode 100644 index 000000000..51f674900 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/inserting-links.md @@ -0,0 +1,39 @@ +# Inserting Links + +Select a word or phrase and click on the *Insert/edit link* icon: + +```{figure} tinymce-linkbutton.png +:align: center +:alt: TinyMCE link button +``` + +The Link dialog will appear: + +```{figure} tinymce-linkdialog.png +:align: center +:alt: TinyMCE link dialog +``` + +Here, you can fill in the information on where you want to link to: + +## Internal Link + +You can search for, or navigate to, the content item that you want to link to. Furthermore, you can set a "target": open in the same browser window, or a new one. In general, it is considered good etiquette to always open internal links in the same window. Setting a descriptive Title for the link is helpful if the item you are linking to does not have a distinctive title of its own. + +## Upload + +The Upload tab lets you upload a PDF or Office document or other file. It will be stored in the same Folder as the content item you are editing. + +## External Link + +When linking to external sites, make sure you include the *complete* link, including the "<http://>" or "<https://>" part, otherwise it will be interpreted as a *relative* link within your own site. Again, you can set a Target and Title. +Opinions differ on whether you should open an external link in a new window or not; ask if your organisation has a policy on this. + +## Email + +This tab lets you create a `mailto:` link, which will open in the user's email program. You can optionally set a subject for the email, although your visitor will always be able to override it. setting the Email Subject is more a helpful suggestion. + +## Anchors + +Anchors are like position markers within a document, based on headings, subheadings, or another style set within the document. You can also set Anchors at arbitrary positions in a document. +Plone automatically creates Anchors for headings and subheadings, and thus you can directly link to a chapter in a long web document. diff --git a/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/inserting-tables.md b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/inserting-tables.md new file mode 100644 index 000000000..289a4a4a0 --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/inserting-tables.md @@ -0,0 +1,20 @@ +# Inserting Tables + +Tables are handy for tabular data and lists. + +To add a table, put your cursor where you want it and click the *Table* dropdown menu. + +```{figure} tinymce-table.png +:align: center +:alt: TinyMCE table +``` + +There are various options to choose a *style* for the table, insert rows and columns, and set properties on the individual cells. Plone comes with a few basic styles for tables, but you (or your site administrator) will most likely want to provide some extra CSS classes to make them look better. + +```{note} +Creating and managing tables in HTML has historically been *awkward*. People tend to mis-use them for layout purposes, which you should not do. + +Use tables **only** for tabular data. And, as rule of thumb, try to keep it to a very small number of rows and columns. + +If you want to present information that is mostly tabular, such as larger amounts of statistical data, there are various add-ons to help you do that. These will generate nicer tables, and are easier to work with both for content editors and visitors to your site. Visitors will be able to sort tables and use a quick search to locate individual cells, for instance. +``` diff --git a/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/introduction.md b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/introduction.md new file mode 100644 index 000000000..2a0f1355d --- /dev/null +++ b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/introduction.md @@ -0,0 +1,19 @@ +# Introduction + +Introduction to TinyMCE. + +TinyMCE is a platform independent web based JavaScript HTML WYSIWYG editor. +What this means is that it will let you create html content on your web site. + +TinyMCE supports most modern operating systems and browsers. +Some examples are: Mozilla, Internet Explorer, Firefox, Opera, Safari and Chrome. +TinyMCE has a large userbase and an active development community. + +TinyMCE is the default visual editor since Plone 4.0. + +```{note} +Browsers on mobile devices were, until recently, limited in their support for editors like TinyMCE. +The situation is improving all the time. If your mobile device supports installing different browsers, it can help to check if modern browsers like Chrome or Firefox give better results when working on a tablet or smartphone. + +Updating to the latest version is usually a good idea. +``` diff --git a/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/tinymce-imgbutton.png b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/tinymce-imgbutton.png new file mode 100644 index 000000000..e17eb2f8c Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/tinymce-imgbutton.png differ diff --git a/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/tinymce-imgdialog.png b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/tinymce-imgdialog.png new file mode 100644 index 000000000..41e3a7580 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/tinymce-imgdialog.png differ diff --git a/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/tinymce-linkbutton.png b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/tinymce-linkbutton.png new file mode 100644 index 000000000..0a4a2d9e3 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/tinymce-linkbutton.png differ diff --git a/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/tinymce-linkdialog.png b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/tinymce-linkdialog.png new file mode 100644 index 000000000..18c75eb27 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/tinymce-linkdialog.png differ diff --git a/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/tinymce-table.png b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/tinymce-table.png new file mode 100644 index 000000000..5c762ce95 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/tinymce-table.png differ diff --git a/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/tinymce.png b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/tinymce.png new file mode 100644 index 000000000..34745aa91 Binary files /dev/null and b/docs/guides/classic-ui/working-with-content/using-tinymce-as-visual-editor/tinymce.png differ diff --git a/docs/guides/index.md b/docs/guides/index.md new file mode 100644 index 000000000..1befd25e9 --- /dev/null +++ b/docs/guides/index.md @@ -0,0 +1,14 @@ +--- +myst: + html_meta: + "description": "User Guides for Plone 6" + "property=og:description": "User Guide for Plone 6" + "property=og:title": "User Guide for Plone 6" + "keywords": "Plone, user, guide" +--- + +```{toctree} +:maxdepth: 2 + +classic-ui/index +``` diff --git a/docs/index.md b/docs/index.md index ef7dcb6b2..7c1d6d8e5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -40,6 +40,7 @@ backend/index classic-ui/index i18n-l10n/index contributing/index +guides/index ``` ```{toctree}