diff --git a/MANIFEST.in b/MANIFEST.in index 00855ff338..bada0293f7 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,3 +1,6 @@ +include README.md +include LICENSE.md +include THEMING.md recursive-include tendenci/addons * recursive-include tendenci/apps * recursive-include tendenci/bin * diff --git a/THEMING.md b/THEMING.md new file mode 100644 index 0000000000..d7c3a029eb --- /dev/null +++ b/THEMING.md @@ -0,0 +1,573 @@ +# Theme Guidelines + +- Authors: John-Michael Oswalt +- Last update: 2013-10-02 + +The main sections are: + +- Theme Structure +- Stylesheet Conventions +- Template Conventions +- HTML and Class Name Conventions +- Full Theme Examples + +## Theme Structure + +A theme should be installed in the themes folder of the site root. The themename should be lowercase with hyphens replacing spaces, like `theme-name`. The file tree should be as follows: + + +- theme-name + + - theme.info + - screenshot.png + - settings.json + + - media + + - css + + - styles.css + + - fonts + + - Font-name.eot + - Font-name.svg + - Font-name.ttf + - Font-name.woff + + - img + + - apple-touch-icon.png + - favicon.ico + - header-background.jpg (optional) + - logo.png + + - js + + - jquery.cycle.all.min.js + - jcarousellite.min.js + + - templates + + - homepage.html + - default.html + - header.html (optional) + - footer.html (optional) + - sidebar.html (optional) + +### Root + +**theme.info** - This file contains a set of attributes associated with a theme. See the example below for some common attributes. + + name = Theme Name + description = Theme Name custom theme for Tendenci CMS. + tags = homepage rotator, responsive + screenshot = screenshot.png + author = John Doe + author uri = http://example.com + version = 1.0 + create_dt = 2013-06-20 15:34:00 + +**screenshot.png** - This file is a full page screenshot of the theme after it has been loaded with the fixtures using the `load_npo_defaults` management command. + +**settings.json** - This file contains settings for the Tendenci site settings. These settings are written in json and are installed whenever the `update_settings`, `set_theme`, or `install_theme` command is run. + + +### Media + +#### css + +**media/css/styles.css** - This is the main stylesheet to be used for the site. It will include all css, including menus and media queries. + +#### fonts + +**media/fonts/Font-name.*** - These are the files for fonts used in the theme. Font files should be copied here, not referenced externally. The 4 formats of `.eot`, `.svg`, `.ttf`, and `.woff` should all be included. + +#### img + +**media/img/apple-touch-icon.png** - This is the file used by iOS devices when a site is saved to an iOS homescreen. + +**media/img/favicon.ico** - This is the favicon for our site. + +**media/img/header-background.jpg** (optional) - This is an example of another image used with the site theme. + +**media/img/logo.png** - This is the main logo for the site. This can be a `.png` or `.jpg`. + + +The `media/img` directory should hold all of the images used with the theme. + +#### js + +**media/js/jquery.cycle.all.min.js** - This is one optional library to use for rotators and sliders. + +**media/js/jcarousellite.min.js** - This is the other optional library to use for rotators and sliders. + +No other javascript libraries should be used for rotators or sliders. Any other necessary javascript libraries like hint, easing, etc. should be included in `media/js`. + + +### Templates + +**templates/default.html** - This file defines the HTML that is used when a page other than the homepage is loaded. + +**templates/footer.html** (optional) - This file should contain the HTML used in the footer. The footer is the last portion of HTML for the theme that would be shared by both the `homepage.html` and `default.html` templates. This file is used to prevent duplicate code in those templates and is **included** within those files. Javascript and CSS should NOT be included in this file. + +**templates/header.html** (optional) - This file should contain the HTML used in the header. The header typically includes the logo, login box, search box, and navigation that would be shared by both the `homepage.html` and `default.html` templates. This file is used to prevent duplicate code in those templates and is **included** within those files. Javascript and CSS should NOT be included in this file. + +**templates/homepage.html** - This file defines the HTML that is used when the homepage of the site is loaded. + +**templates/sidebar.html** (optional) - This file should contain the HTML used in the sidebar. The sidebar has content that would be shared by both the `homepage.html` and `default.html` templates. This file is used to prevent duplicate code in those templates and is **included** within those files. Javascript and CSS should NOT be included in this file. + +### Overridden Templates + +On occasion, it may be necessary to override a template used in the site. For example, if the default view of an article needed to be edited for this theme, the overridden template would reside in the theme at **templates/articles/view.html**. + +## Stylesheet conventions + +### Comments + +Specify the about comments, similar to WordPress, like so: + + /* + Theme Name: The Theme Name + Theme URI: http://tendenci.com/ + Description: Custom theme design for Tendenci + Designer: John Doe + Designer URI: http://example.com/ + Developer: Jane Doe + Developer URI: http://example.com/jdoe/ + Version: 1.0 + */ + +CSS comments are very similar, written like so: + + /* ------------------------------ + Reset HTML + ------------------------------ */ + +The header line begins with forward slash, asterisk, and a space, followed by 30 dashes. The footer line is the same, but in reverse. The name row has 4 spaces, then the name of the comments section. + +Comments should have empty line after them. The code should begin on the very next line. Comments should have 1 empty line above them. + +### Reset + +A standard CSS reset should be used like so: + + /* ------------------------------ + Reset HTML + ------------------------------ */ + html, body, div, span, object, iframe, + h1, h2, h3, h4, h5, h6, p, blockquote, pre, + abbr, address, cite, code, del, dfn, img, ins, kbd, q, samp, + small, strong, sub, sup, var, b, i, dl, dt, dd, ol, ul, li, + fieldset, form, label, legend, + table, caption, + article, aside, canvas, details, figcaption, figure, + footer, header, hgroup, menu, section, summary, + time, mark, audio, video { + margin: 0; + padding: 0; + border: 0; + font-size: 100%; + font: inherit; + vertical-align: baseline; + } + + article, aside, details, figcaption, figure, + footer, header, hgroup, menu, section { + display: block; + } + +This reset should have the comment above it as demonstrated. After this bit of code, an empty line should be present, followed by the next CSS comment denoting the next section. + +### Base HTML Elements + +Here is a sample of code that can be used for base HTML elements. + + /* ------------------------------ + Base HTML Elements + ------------------------------ */ + body { background-color: #ffffff; font-family: Helvetica, Arial, "sans-serif"; font:13px/1.231 sans-serif; *font-size:small; color: #333333; margin: 0; } + + h1, h1 a { font-size: 32px; line-height: 34px; text-decoration: none; font-weight: bold; margin-bottom: 10px; } + h2, h2 a { font-size: 24px; line-height: 26px; text-decoration: none; font-weight: bold; margin-bottom: 10px; } + h3, h3 a { font-size: 20px; line-height: 22px; text-decoration: none; font-weight: bold; margin-bottom: 6px; } + h4, h4 a, + h5, h5 a, + h6, h6 a { font-size: 16px; line-height: 18px; text-decoration: none; font-weight: bold; margin-bottom: 6px; } + + a { color: #0000ff; } + a:hover { color: #5555ff; } + a:visited, a:active { color: #BB55ff; } + + p { margin-bottom: 10px; line-height: 18px; } + + ul, ol { margin: 0 0 10px 24px; } + ol { list-style-type: decimal; } + + select, input, textarea, button { font:99% sans-serif; } + pre, code, kbd, samp { font-family: monospace, sans-serif; margin-bottom: 10px; padding: 8px; } + + small { font-size: 85%; } + strong, th { font-weight: bold; } + + td, td img { vertical-align: top; } + + sub { vertical-align: sub; font-size: smaller; } + sup { vertical-align: super; font-size: smaller; } + + blockquote { margin: 0 0 10px 20px; } + +Note that several variables are used in these base elements. You can also see the layout of a single style. Taking a closer look at the `p` tag, we can see some ways of writing our CSS. + + p { margin-bottom: 10px; line-height: 18px; } + +All of the styles are on 1 line. There is a space after the open bracket, and a space before the closing bracket. There is a space between a property and it's value, and there is a space between values. All values (especially the last one) are closed with a semi-colon. Below is an example of the same property without these spaces. + + p {margin-bottom:10px;line-height:18px;} + +Yuck. While this code will still work, it is hard to read and becomes more difficult to manage. Same goes for writing out properties on separate lines. The document becomes too long to quickly read and understand. + +### Extras + +Mostly this is just the clearfix code. This should be the last section of CSS in the document. + + /* ------------------------------ + Extras + ------------------------------ */ + .clear { clear: both; } + .clearfix:before, .clearfix:after { content: "\0020"; display: block; height: 0; visibility: hidden; } + .clearfix:after { clear: both; } + .clearfix { zoom: 1; } + + +### Main Sections + +Main sections of the stylesheet should be written like the above example, with a comment heading at the top. Styles should be written in a similar pattern to the HTML. See below for an example order of the CSS sections. + +- Reset +- Base HTML Elements +- Header +- Homepage Top (Rotator) +- Homepage Body +- Interior Body +- Interior Sidebar +- Footer +- Tendenci Overrides +- Extras +- Media Queries + +## Template conventions + +For the `homepage.html` and `default.html` templates, the following conventions apply. + +### Extends and Loading libraries + +An example `homepage.html` should start like this: + + {% load theme_tags %} + {% load nav_tags %} + {% load story_tags %} + {% load base_tags %} + + {% theme_extends 'base.html' %} + +Each library loaded at the top will make more template tags available for use. You should only include tag libraries that are used on the page, as loading unused libraries can increase page load times. + +The `theme_tags` library is **required** as it allows us to extend the `base.html` template with the `theme_extends` tag. This is a bit different than other Django apps. This is done this way in Tendenci to allow for theme previewing. + +The load for `base_tags` is not required, but is almost always used, so it should be included. + +The load for `nav_tags` and `story_tags` are optional, but are used frequently. + +### Available blocks + +The following blocks are available to be used. You are free to make up other blocks, but these blocks are specifically referenced in the `base.html` template. These blocks do not apply to overridden templates or to included templates like `header.html` and `footer.html`. + +Blocks are listed below in the order they typically appear in for a template. + +`{% block title %}` - Loads into the `