Skip to content

Instantly share code, notes, and snippets.

@brendo

brendo/markup.md

Created March 10, 2012 16:27
Show Gist options
  • Save brendo/2011939 to your computer and use it in GitHub Desktop.
Save brendo/2011939 to your computer and use it in GitHub Desktop.
Download ZIP
Symphony 2.3 Markup Transition
Raw
markup.md

Markup and You

Symphony 2.3 features a significantly improved UI over it's predecessors due to the hard work of the UX Working Group and contributions by other dedicated members of the Symphony community. In making these changes, there's been a number of minor updates to the HTML, CSS and JS throughout the backend. The purpose of this guide is to help document some of these new features, and outline differences that extension developers can implement while updating their extension for 2.3. Eventually a dedicated style guide for Symphony will be available, but this will fill the void for the meantime.

HTML

Apply

In the past adding a With Selected select box to the bottom of your page was done by using the Widget::Select and Widget::Input functions. This is no longer required with the new Widget::Apply function that takes a single parameter, an array of options.

CSS

  • Symphony now utilises @media-queries to provide an optimised layout for content editors when the screen size dips below 700px.

  • Something about the .tabs styling/structure expected

Columns

Columns need a wrapping element (.columns) and multiple columns (.column). Additionally, the wrapper has to declare how many columns it should display per row. Symphony knows the following classes:

  • .two
  • .three
  • .four

Example:

<fieldset class="two columns">
    <label class="column">…</label>
    <label class="column">…</label>
</fieldset>

The two column mode knows a special setup known from the publish area: a primary and a secondary column.

Example:

<fieldset class="two columns">
    <label class="primary column">…</label>
    <label class="secondary column">…</label>
</fieldset>

The old classes .group and .compact have been deprecated, see symphony.legacy.css.

JS

  • The Duplicator plugin
  • Something about the new Drawer plugin
  • Something about the new Notify plugin
@nilshoerrmann
Copy link

If you want to have your Duplicators styled even with JavaScript disabled, wrap it with <div class="frame" /> (which will be added on the fly, if you don't add it).

@brendo
Copy link
Author

brendo commented Mar 11, 2012

Thanks, added. Feel free to flesh out!

@nilshoerrmann
Copy link

This is how the current markup looks like:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">

        <!-- Core styles -->
        <link rel="stylesheet" type="text/css" media="screen" href="http://example.com/symphony/assets/css/symphony.css">
        <link rel="stylesheet" type="text/css" media="screen" href="http://example.com/symphony/assets/css/symphony.legacy.css">
        <link rel="stylesheet" type="text/css" media="screen" href="http://example.com/symphony/assets/css/symphony.grids.css">
        <link rel="stylesheet" type="text/css" media="screen" href="http://example.com/symphony/assets/css/symphony.frames.css">
        <link rel="stylesheet" type="text/css" media="screen" href="http://example.com/symphony/assets/css/symphony.forms.css">
        <link rel="stylesheet" type="text/css" media="screen" href="http://example.com/symphony/assets/css/symphony.tables.css">
        <link rel="stylesheet" type="text/css" media="screen" href="http://example.com/symphony/assets/css/symphony.drawers.css">
        <link rel="stylesheet" type="text/css" media="screen" href="http://example.com/symphony/assets/css/symphony.tabs.css">
        <link rel="stylesheet" type="text/css" media="screen" href="http://example.com/symphony/assets/css/symphony.notices.css">
        <link rel="stylesheet" type="text/css" media="screen" href="http://example.com/symphony/assets/css/admin.css">

        <!-- Core scripts -->
        <script type="text/javascript" src="http://example.com/symphony/assets/js/jquery.js"></script>
        <script type="text/javascript" src="http://example.com/symphony/assets/js/symphony.js"></script>
        <script type="text/javascript" src="http://example.com/symphony/assets/js/symphony.collapsible.js"></script>
        <script type="text/javascript" src="http://example.com/symphony/assets/js/symphony.orderable.js"></script>
        <script type="text/javascript" src="http://example.com/symphony/assets/js/symphony.selectable.js"></script>
        <script type="text/javascript" src="http://example.com/symphony/assets/js/symphony.duplicator.js"></script>
        <script type="text/javascript" src="http://example.com/symphony/assets/js/symphony.tags.js"></script>
        <script type="text/javascript" src="http://example.com/symphony/assets/js/symphony.pickable.js"></script>
        <script type="text/javascript" src="http://example.com/symphony/assets/js/symphony.timeago.js"></script>
        <script type="text/javascript" src="http://example.com/symphony/assets/js/symphony.notify.js"></script>
        <script type="text/javascript" src="http://example.com/symphony/assets/js/symphony.drawer.js"></script>
        <script type="text/javascript" src="http://example.com/symphony/assets/js/admin.js"></script>

        <!-- Context information -->
        <script type="text/javascript">
            Symphony.Context.add('env', {
                "page-namespace": "\/publish",
                "section_handle": "section-handle",
                "page": "index",
                "entry_id" :null,
                "flag": null
            }); 
            Symphony.Context.add('root', 'http://example.com');
        </script>

        <!-- Page title -->
        <title>Default Symphony Page — Symphony</title>
    </head>
    <body id="publish" class="section-handle index">
        <div id="wrapper">
            <header id="header">

                <!-- All notification will be wrapped with `<div class="notifier" />` by the Notify plugin -->
                <p class="notice">Your Symphony installation is up to date, but the installer was still detected. For security reasons, it should be removed. <a href="http://example.com/install/?action=remove">Remove installer?</a></p>

                <!-- Page title -->
                <h1>
                    <a href="http://example.com/">Default Symphony Page</a>
                </h1>

                <!-- Session information -->
                <ul id="session">
                    <li>
                        <a href="http://example.com/symphony/system/authors/edit/1/" data-id="1" data-name="Sam" data-type="developer">Sam Symphonist</a>
                    </li>
                    <li>
                        <a href="http://example.com/symphony/logout/" accesskey="l">Log out</a>
                    </li>
                </ul>

                <!-- Navigation -->
                <nav id="nav">

                    <!-- Author area, left aligned -->
                    <ul class="content">
                        <li class="active">Content
                            <ul>
                                <li>
                                    <a href="http://example.com/symphony/publish/section-handle/">Section Name</a>
                                </li>
                            </ul>
                        </li>
                    </ul>

                    <!-- Developer area, right aligned -->
                    <ul class="structure">
                        <li>Blueprints
                            <ul>
                                <li>
                                    <a href="http://example.com/symphony/blueprints/pages/">Pages</a>
                                </li>
                                <li>
                                    <a href="http://example.com/symphony/blueprints/sections/">Sections</a>
                                </li>
                                <li>
                                    <a href="http://example.com/symphony/blueprints/datasources/">Data Sources</a>
                                </li>
                                <li>
                                    <a href="http://example.com/symphony/blueprints/events/">Events</a>
                                </li>
                                <li>
                                    <a href="http://example.com/symphony/blueprints/utilities/">Utilities</a>
                                </li>
                            </ul>
                        </li>
                        <li>System
                            <ul>
                                <li>
                                    <a href="http://example.com/symphony/system/authors/">Authors</a>
                                </li>
                                <li>
                                    <a href="http://example.com/symphony/system/preferences/">Preferences</a>
                                </li>
                                <li>
                                    <a href="http://example.com/symphony/system/extensions/">Extensions</a>
                                </li>
                            </ul>
                        </li>
                    </ul>
                </nav>
            </header>

            <!-- Context -->
            <div id="context">

                <!-- Breadcrumbs -->
                <div id="breadcrumbs">
                    <nav>
                        <p>
                            <a href="http://localhost/test/symphony/publish/section-handle">My Current Path</a>
                            <span class="sep">›</span>
                        </p>
                    </nav>
                    <h2>Symphony Page</h2>
                </div>

                <!-- Actions -->
                <ul class="actions">
                    <li><a href="http://example.com/symphony/publish/section-handle/new/" title="Create a new entry" class="create button" accesskey="c">Create New</a></li>
                    <li><a href="http://example.com/symphony/blueprints/sections/edit/1" title="Edit Section Configuration" class="button">Edit Section</a></li>
                </ul>

                <!-- Horizontal Drawer, optional -->
                <div class="drawer" id="drawer-id" data-position="horizontal" data-default-state="closed" data-context="publish" data-label="Drawer Label">
                    <div class="contents"></div>
                </div>
            </div>

            <!-- Vertical left Drawer, optional -->
            <div class="drawer" id="drawer-id" data-position="vertical-left" data-default-state="closed" data-context="publish" data-label="Drawer Label">
                <div class="contents"></div>
            </div>

            <!-- Content area -->
            <div id="contents">
                <form action="http://example.com/symphony/publish/section-handle/?pg=1" method="post" class="fads">

                    <!-- Page content here, e. g. index table, at set of columns or settings -->

                    <!-- Actions, optional -->
                    <div class="actions">

                        <!-- Buttons, optional -->
                        <input name="action[save]" type="submit" value="Save Changes" accesskey="s">
                        <button name="action[delete]" class="button confirm delete" title="Action title" type="submit" accesskey="d" data-message="Action message">Delete</button>

                        <!-- "With selected …", optional -->
                        <fieldset class="apply inactive">
                            <div>
                                <select name="with-selected" disabled="disabled">
                                    <option value="">With Selected...</option>
                                    <option value="delete" class="confirm" data-message="Action message">Delete</option>
                                </select>
                            </div>
                            <button name="action[apply]" type="submit">Apply</button>
                        </fieldset>
                    </div>
                </form>

                <!-- Pagination, optional --> 
                <ul class="page">
                    <li>First</li>
                    <li>&larr; Previous</li>
                    <li title="Viewing 1 - 2 of 5 entries">
                        <form action="http://example.com/symphony/publish/section-handle/" method="get" class="paginationform">
                            <input name="pg" type="text" data-active="Go to page …" data-inactive="Page 1 of 3" data-max="3">
                        </form>
                    </li>
                    <li>
                        <a href="http://example.com/symphony/publish/section-handle/?pg=2">Next &rarr;</a>
                    </li>
                    <li>
                        <a href="http://example.com/symphony/publish/section-handle/?pg=3">Last</a>
                    </li>
                </ul>
            </div>

            <!-- Vertical right Drawer, optional -->
            <div class="drawer" id="drawer-id" data-position="vertical-left" data-default-state="closed" data-context="publish" data-label="Drawer Label">
                <div class="contents"></div>
            </div>
        </div>
    </body>
</html>

I'm not sure we need to write up what exactly changes: in my eyes, everything developers need to know is available in the markup.

@nilshoerrmann
Copy link

Regarding the Drawer: Similar to the note about the "With selected …" we should also point out in the HTML section that Symphony takes care of creating the markup. I'm not familiar with the provided functions or widgets but it should not only be mentioned under JS.

@nilshoerrmann
Copy link

Regarding the navigation: We should point out how to correctly add items to the .content and the .structure areas. Maybe @nickdunn could write this up – I remember a post from him regarding appending or prepending new menu items.

@nilshoerrmann
Copy link

Regarding tabs: Symphony doesn't provide any functionality to add the needed markup to a backend page. This is up to the developer so we should also point that out in the HTML area. I think @nickdunn made the latest changes to the tabs styles and he is the only one who has already implemented the new styles in his extensions (as far as I know) – so I'd leave documenting to him.

@nilshoerrmann
Copy link

My hopefully last comment for now – in the CSS section we should add information about:

  • .frame (this class is now used through out the system to provide a consistent layout of boxes, login forms, Duplicators)
  • unified button styling
  • symphony.legacy.css – a file gathering all style definitions that will be removed in a future Symphony version

I guess writing this up will be my job.

@nilshoerrmann
Copy link

I updated the documentation of the Documenter to provide information about the two different APIs we added recently (applying the plugin to .frame or ol).

Symphony doesn't make use of the new API itself – question is if we change this for RC 1 or if we leave the change for 2.3.1. I'm not sure personally: we might want to move the id for the field editor and for the Data Source filters from the list to the frame element – which would be some kind of a markup change. Thoughts.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment