Symphony.

Please discuss the documentation for Glossary in this thread.

Thought it might be helpful to take a quick first stab at a list of terms to include in the glossary. It’s sure to be incomplete or faulty, so… have at it.

Symphony-specific

• author
• content group
• data source
• data source: parameter output
• debug
• debug: parameter pool
• debug: profile
• ensemble
• event
• extension
• extension: enable/disable/uninstall
• field
• page
• page: page type
• section
• URL parameter
• utility
• workspace

XML/XSLT/XPath

• entity
• namespace
• node

Could everyone who is comfortable take one term from above and post its definition. I think we’ll get better definitions this way. I’m going to Sticky this thread for a few days.

Please use second person.

Utility

A utility generally refers to an XSLT template that can be imported by a page template using an xsl:import instruction. A utility can often used as a master template that can be used to manage common elements of a page template, such as the html, head and body elements, and for site-wide control of common layout elements, such as the header and footer of the page. A utility can also be used to build navigation and pagination elements, or to format dates, layout calendars, or perform math or string functions.

(XSLT templates need not necessarily be imported into an XSL stylesheet to be used by the page template. Multiple templates can exist in a single stylesheet.)

Event

An event is a PHP class that can be attached to a page template to perform specific functions that are out of the realm of what XSLT alone can accomplish. Extensions can sometimes include events that can be attached to a page. Built into Symphony is a way of creating events that can be used to save data to the database from front-end forms as a single entry or even multiple entries at one time, with the option of sending an email message on successfully saving an entry or entries.

PHP code cannot be inserted into XSLT, since it is not valid XML. Plus, it might compromise the security of the site if it were possible. Symphony events have been created as a way of enabling pages to take advantage of the PHP classes available in the Symphony core, or to extend these core classes with additional functionality.

Section

A section is set of data input fields that are used to create a content entry page in the Symphony admin area. Upon the creation of the first section, a section will be added as a menu item in the Publish menu of the main navigation of the Symphony admin, unless the section has been set to be hidden from the Publish menu. (If no sections have been created, the Publish menu will not display in the admin navigation.) To create a section, navigate to Blueprints : Sections and click on the “Create New” button. Provide a name for the section, select whether to display the section and add items to the section. Each item is a data entry field that will be displayed in the content entry page as configured in the section. Each item can be dragged by the field type bar to configure the position of the field on the content entry page. Configure placement of each field in the main content or sidebar of the content entry page with the “Placement” select menu.

Navigating to a section in the publish menu will provide a paginated list of entries created in a section, with columns of data displayed for each field that has been set to “Show column”. To create a new entry in a section, click on the “Create New” button. To edit or delete an entry, click on the entry link in the first column of the entries list to open a data entry page for the selected entry.

Creating sections is a way of dynamically creating the database structure for your site and the navigation system of the Symphony admin area.

As this is a glossary, I think these definitions are starting to spill into the area of tutorial. Where do you want to draw the line? Particularly for the term, “Section”, it is difficult to explain without going into a lot of detail about how it works in Symphony.

The definition for Section may even be too short, as it doesn’t describe how sections are used to build the XML structure, but, then, this bleeds into the definition of a data source.

Also, it might help to define a preferred grammatical style and voice, just for the sake of consistency. Should we avoid personal pronouns as much as possible and use a voice that implies second-person: “Provide a name…”, “Click on the Create New button”?

Should we avoid personal pronouns as much as possible and use a voice that implies second-person

Yes, I agree. I started with the former and decided documentation is better written in second person. Thank you for bringing that up!

As this is a glossary, I think these definitions are starting to spill into the area of tutorial. Where do you want to draw the line? Particularly for the term, “Section”, it is difficult to explain without going into a lot of detail about how it works in Symphony.

Correct, these definitions should not sound like tutorials. They should be concise. Nevertheless, whatever is contributed in this thread will go a long ways to finding the best definition for each.

Thanks Bauhouse!

An edited version, as concise as I could make it:

Section

A section is set of data input fields that are used to create a content entry page in the Symphony admin area. Create sections to dynamically build the database structure for your site and the navigation system of the Symphony admin area. Each section defines a set of related fields in the database that will be used to structure the XML output for transformation by XSLT stylesheets and templates.

A section is added as a menu item in the Publish menu of the main navigation of the Symphony admin, unless a preference is set to do otherwise. Each item in a section is a data entry field that will be displayed in the content entry page as configured, with preferences for list column view, placement, validation and other applicable settings.

Navigate to a section in the publish menu to view a paginated list of entries created in a section, with columns of data displayed for each field that has been set to “Show column”. Select an entry from the list to view the content entry page in order to create, view, edit or delete entries for the selected section.

If we’re talking a strict glossary, should they be very succinct?

XSLT Utility

An XSLT include file used for re-usable XSLT templates. Templates in Utilities are generally used for functions (date formatting, string truncation, pagination etc.) or page layout and content output.

Event

A PHP file that executes on page load or on form submission. These are most commonly used to insert or update content in a section.

Section

The equivalent of a database table, a Section represents an “entity” in your website such as a blog post, a comment or a user. A Section comprises Fields which store individual pieces of data (e.g. name, age, date).

Bauhouse, your definitions are excellent but possibly better suited to an interface walkthrough than a glossary?

Data Source

A controller that fetches data (from the database or from external XML sources) and exposes it as XML to the XSLT templating layer. Data Sources have highly-configurable filtering and output options, and can accept filter input from the front-end or from other Data Sources.

Yeah, Nick, I think you’re right. Succinct is better.

Thanks Mark for the initiative. Thanks Stephen, Craig and Nick for the help with content. I’ve put up the rough version on the glossary page.

Succinct is good for glossary. If further explanation is required, then the subject could be linked to other parts of the documentation.

Agreed. Thanks for your help everyone!