Customizing Your Portal

A Word of Caution

You can only change the markup in div#main. You may also change the content in div#sub via the sidebar editor in the CMS for custom pages. That's it! Also, a Mashery base CSS file is always included. Please design and develop accordingly.

Because Mashery provides CSS frameworks, it becomes extremely easy to make your own Mashery theme with only a few bits of knowledge about CSS. Just set the background colors, tweak some fonts and you're all set! It might not be the best looking theme in the world, but it's an easy way to start.

On the other hand, we would highly recommend that whoever makes a custom Mashery theme have a strong command of XHTML and CSS as well as knowledge of web standards. Starting out, you will get by with just changing the colors of things. But eventually you will likely need to tweak some widths, play with line-heights, and understand floats and positioning if you try to make some minor layout adjustments.

CSS and XHTML

CSS and XHTML are the two essential things you will need to know. If you are not already familiar with these, try checking out the tutorials at HTML Dog.

CSS Framework

Mashery uses a slightly modified version of the CSS Framework by Mike Stenhouse. Specifically, we are using the "Horizontal Nav, Local Nav, and Two Column" framework.

Mashery CSS Framework

We also have another layer of CSS that consists of the Mashery CSS Framework. The Mashery CSS Framework provides the basic layout for all Mashery portals sans color, graphics, and only the most basic elements of typography. On top of this layer is where you can place your own CSS theme.

Mashery does not want you to create a generic looking portal, but we do encourage you not to radically modify the layout. Adopting the standard Mashery layout is easy (because it's already mostly done for you), good for your users, and may make it more likely for users to use your API. The reason for this, is that developers will most likely be using your portal in conjunction with other Mashery portals, mixing and matching APIs for their own use. If all the Mashery portals have similar layouts, then users will only have to use one portal to learn how to use all of them. Obviously, this isn't cut in stone since you have the freedom to override anything when it comes to the look and feel of your portal. However, it is very easy to make your portal look unique and apply your own branding without changing the general layout.

Base CSS Files

CSS Framework

The CSS Framework is composed of several stylesheets which are interpreted before any others. Here is a list of some of them that you might want to be aware of, but for the most part you can ignore them and just build your theme as you go.

  • reset.css - Basically resets padding and margins for everything to 0.
  • typo.css - Some basic typography defaults. You will most likely override these anyway.
  • tools.css - Includes the venerable .clearfix class, works with both IE6 and IE7.

Mashery CSS Framework

The Mashery CSS Framework builds on the CSS Framework to create a basic Mashery Portal layout. It is worth looking through it and reading some of the comments to see how things fit together and common pitfalls.

Theme Template

The "Theme Template" is essentially a skeleton of what may become a theme for your Mashery Portal. It has a sample organization structure and a few helpful comments. It also has backgrounds set for some key elements that you will most likely want to change. If you view your portal with the Theme Template set as your CSS, you will see the backgrounds which will help you visualize which elements go where and what to change.

How to use the Theme Template

  1. Download the Theme Template
  2. Rename the file to whatever you want to call your theme (ex. shaun-cederholm-theme.css)
  3. Upload it to wherever you are going to be hosting your theme
  4. Go to your Dashboard in your Portal
  5. Go to the Settings tab
  6. Point your "Custom Theme URL" to wherever you uploaded the theme-template
  7. Start making your theme from the template!

Recommended Development Resources

Firebug

Firebug is a Firefox extension for developers. Version 1.0 introduced many new features and improvements, making it one of the most useful and easy to use extensions for front-end web development.

Tip: Using the CSS tab can be cumbersome and confusing. Just use the inspect button and click on the element you are interested in. Using the HTML pane on the left and the Style pane on the right will allow you to inspect or change the HTML and CSS style of different elements intuitively and easily.

HTML Dog

HTML and CSS Tutorials. And Stuff.” A great user-friendly reference for HTML and CSS with plenty of examples and caveats.

Docs Navigation