Customizing Your Portal
A Word of Caution
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, I 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. The CSSFW utilizes advanced implementations of floats, position, and margins to make the layout possible. If you don't have a strong command of the XHTML and CSS, you will probably run into problems when dealing with layouts and positioning.
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.
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
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.
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
- Download the Theme Template
- Rename the file to whatever you want to call your theme (ex. shaun-cederholm-theme.css)
- Upload it to wherever you are going to be hosting your theme
- Go to your Dashboard in your Portal
- Go to the Settings tab
- Point your "Custom Theme URL" to wherever you uploaded the theme-template
- Start making your theme from the template!
Recommended Development Resources
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 and CSS Tutorials. And Stuff.” A great user-friendly reference for HTML and CSS with plenty of examples and caveats.