# Components This page is living documentation for your Portal theme. If you would like to update your theme, [click here to download the source files](/files/portal-theme.zip). *__Note:__ This page is only visible to site admins and other power users. Typical developer accounts will not have access to this page, nor will it show up in the navigation menu for them.* ## Brand Elements ### Colors ### Font Stacks

Helvetica Neue, Arial, sans-serif

Georgia, Times, serif

Menlo, Monaco, Courier New, monospace

--- ## The Grid Your theme uses a fluid, mobile-first grid system based on simple fractions—halves, thirds, and fourths. It supports nesting, and includes special classes for offsets and content choreography. ### Base Grid The `.container` class centers content on the page and restricts it to a maximum width. To create a grid, add a `div` with a `.row` class. You can create grids within a row by creating `div` elements with the `.grid-$size` class. ```html ``` ### Offsets Push grids to the right by adding an `.offset-$size` class. Center grids with the `.float-center` class. ```html ``` ### Grids on Small Viewports The grid activates on medium-sized viewports by default. You can toggle the grid on smaller screens by adding a simple class—`.row-start-xsmall` or `.row-start-small`—to the desired `.row` element. **Extra Small Screens** **Small Screens** ```html Extra Small Screens Small Screens ``` ### Content Choreography Flip the display order of a grid on bigger viewports by adding the `.grid-flip` class. ```html ``` ### Dynamic Grids Create grids that vary in size based on screen width using the `.grid-dynamic` class. ```html ``` ### Full Width Layouts Make any piece of content go full width (run from one edge of the viewport to the other) by adding the `.full-width` class. ```html

This content will have the normal amount of padding on the left and right.

The image above will also run edge-to-edge.

``` ### Hiding Headings You can hide the automatically generated heading on a page by setting `mashery.globals.noHeading` to `true` inline on that page. ```html The rest of your content... ``` --- ## Typography Your theme uses relative sizing (ems and % instead of pixels) for everything. *New to relative sizing? [Learn more.](http://gomakethings.com/working-with-relative-sizing/)* ### Text Basics ```html Default text Muted text Small text Large text Hero text Remove bold from text Remove italics from text Hyperlinks Hyperlinks with no underline Bold and italics ``` **Note:** Because Your theme uses relative sizing, you should always apply `.text-large` and `.text-small` classes to a `span` element and not directly to a `p`. Otherwise, your spacing will get all messed up. The `.text-*` classes can be found in `_overrides.scss` for better cascade inheritance. ### Block-Level Links Use the `.link-block` class to create block-level links that are styled like regular text. Add the `.link-block-styled` class to the sections of text you want styled like a traditional link.

This is a block-level link

This whole section is a clickable link. Hover over it to see.
Only this text is styled like a link →

```html

A block-level link

This whole section is a clickable link. Hover over it to see.

Only this text is styled like a link →

``` --- ## Lists Your theme includes styling for ordered, unordered, unstyled, inline, breadcrumb, and definition lists.

Definition List

Encloses a list of pairs of terms and descriptions. Common uses for this element are to implement a glossary or to display metadata (a list of key-value pairs).

Here's another term

And another definition.

```html Ordered

1. Item 1
2. Item 2
3. Item 3

Unordered

• Item 1
• Item 2
• Item 3

Unstyled

• Item 1
• Item 2
• Item 3

Inline

• Item 1
• Item 2
• Item 3

Inline Responsive

• Item 1
• Item 2
• Item 3

Inline Divided

• Item 1
• Item 2
• Item 3

Inline Breadcrumbs

• Item 1
• Item 2
• Item 3

Definition List

Encloses a list of pairs of terms and descriptions. Common uses for this element are to implement a glossary or to display metadata (a list of key-value pairs).

Here's another term

And another definition.

``` *For semantic reasons, `.list-unstyled` and `.list-inline` should only be applied to unordered lists.* --- ## Headings Your theme includes styling for `h1` through `h6` headings.

h1. Heading 1

h2. Heading 2

h3. Heading 3

h4. Heading 4

h5. Heading 5

h6. Heading 6

```html

h1. Heading 1

h2. Heading 2

h3. Heading 3

h4. Heading 4

h5. Heading 5

h6. Heading 6

``` ### Semantic Heading Classes All heading values can also be applied as classes. For example, if a heading should be an `h1` element semantically, but you would like it to be styled as an `h4` element, you can apply `class="h4"` to the `h1` element.

This is an h1 heading that's styled as an h4 heading

```html

This is an h1 heading that's styled as an h4 heading

``` --- ## Quotes and Citations

Someone once said something so important, it was deemed worthy of repeating here in the form of a blockquote. This is that blockquote. - Someone

You can also include superscripts<sup>1</sup> and subscripts<sub>xyz</sub>. ```html

Someone once said something so important, it was deemed worthy of repeating here in the form of a blockquote. This is that blockquote. - Someone

You can also include superscripts<sup>1</sup> and subscripts<sub>xyz</sub>. ``` --- ## Code Inline code: `.js-example`. ```css /* Preformatted Text */ .js-example { color: #272727; background: #ffffff; } ``` ```html

Inline code: .js-example

	
		/* Preformatted Text */
		.js-example {
			color: #272727;
			background: #ffffff;
		}
	

``` You'll need to escape brackets contained in code by typing `<` for `<` and `>` for `>`. --- ## Syntax Highlighting Syntax highlighting is provided by [Prism by Lea Verou](http://prismjs.com/). It includes support for: * Bash * CSS * C-like languages * HTTP * Markup/HTML * Java * JavaScript * PHP * Python * Ruby * Sass/scss Add `class="lang-*"` to your `code` element, where `*` is the language to be highlighted. ```html

		/* Your code here...  */
	

		// Your code here...
	

``` ***Note:*** *The syntax highlighter tool in TinyMCE will automatically add the correct markup and classes and highlighting for you.* ### Language Table | Language | Class | |-------------|-------------------------------| | Bash | `.lang-bash` | | CSS | `.lang-css` | | C, C#, C++ | `.lang-clike` | | HTTP | `.lang-http` | | Markup/HTML | `.lang-markup`/`.lang-html` | | Java | `.lang-java` | | JavaScript | `.lang-javascript`/`.lang-js` | | PHP | `.lang-php` | | Python | `.lang-python` | | Ruby | `.lang-ruby` | | Sass | `.lang-sass` | | scss | `.lang-scss` | --- ## Lines Add lines to your markup using the `hr` element. --- ## Backgrounds Add background colors with a handful of helper classes. ```html ``` ### Hero Image Backgrounds Use the `.bg-hero` class with one of the above background colors to create a background hero image. This class ensures that the image fully covers the background. You will need to specify a background image (using either the inline CSS feature in the Dashboard or by adding inline CSS to the element directly). You may also wish to add a minimum height (or heights at different breakpoints) depending on the image. ```html ``` ### Hero Video Backgrounds In addition to the `.bg-hero` class, also add the `.bg-hero-video` class. Within the `.bg-hero` element, add a `div` with the `.bg-hero-video-player` class and include your video in it. This can be either an iframe video or an HTML5 `video` element. You should also include an empty `div` with the `.bg-hero-video-overlay` class if you'd like to add a semi-transparent overlay on the video (to make your text easier to read). Create a `div` with the `.bg-hero-video-text` class and add your hero content to it. ```html ``` --- ## Buttons Button styles can be applied `a`, `button`, and `input type="submit"` elements using the `.btn` class. Use `.active` and `.disabled` classes to change the appearance of buttons. ```html Button Button Secondary Button Large Button Block Button Block Active Secondary Active Disabled Secondary Disabled ``` --- ## Forms Labels, legends and inputs are styled as full width block elements (with the exception of checkboxes and radio buttons).

Label Option 1 Option 2 Option 1 Option 2 Select 1 Select 2 Select 3

```html

Label Option 1 Option 2 Option 1 Option 2 Select 1 Select 2 Select 3

``` ***Tip:*** *Wrap checkboxes and radio buttons inside a `label` to make them easier to click.* ### Form Layouts Use the grid system to add structure to your forms.

Name

Message

Submit

```html

Name

Message

Submit

``` ### Condensed & Inline Inputs For smaller forms, add the `.input-condensed` class to your input fields. For inline form elements, add the `.input-inline` class.

```html

``` --- ## Tables Simple, easy-to-read tables.

First Name	Last Name	Super Hero
Peter	Parker	Spiderman
Bruce	Wayne	Batman
Clark	Kent	Superman

```html

First Name	Last Name	Super Hero
Peter	Parker	Spiderman
Bruce	Wayne	Batman
Clark	Kent	Superman

``` ### Zebra Striped Table Add the `.table-striped` class to add zebra stripes to your table.

First Name	Last Name	Super Hero
Peter	Parker	Spiderman
Bruce	Wayne	Batman
Clark	Kent	Superman

```html ... ``` ### Condensed Table Add the `.table-condensed` class for more compact tables.

First Name	Last Name	Super Hero
Peter	Parker	Spiderman
Bruce	Wayne	Batman
Clark	Kent	Superman

```html ... ``` ### Combining Classes Classes can be combined as needed.

First Name	Last Name	Super Hero
Peter	Parker	Spiderman
Bruce	Wayne	Batman
Clark	Kent	Superman

```html ... ``` --- ## Navigation Your theme includes an expand-and-collapse navigation menu on smaller screens. ### Getting Started #### Markup *__Note:__ This is already done for you in your theme setup file.* Turn any button or link into a toggle for your navigation menu by adding the `[data-nav-toggle]` attribute, and give it a value that matches the selector of the area(s) you're trying to expand. ```html ``` #### JavaScript The script will not run until initialized in a `portalAfterRender` event. This is done for you already in the `Body JavaScript` section under `Portal > Portal Setup` in the API Control Center. ```js // Expand-and-collapse nav on small viewports astro.init(); ``` ### Global Settings You can pass options and callbacks into Astro through the `init()` function: ```javascript astro.init({ selector: '[data-nav-toggle]', // Navigation toggle selector toggleActiveClass: 'active', // Class added to active dropdown toggles on small screens navActiveClass: 'active', // Class added to active dropdown content areas on small screens initClass: 'js-astro', // Class added to `` element when initiated callback: function ( toggle, navID ) {} // Function that's run after a dropdown is toggled }); ``` *__Note:__ If you change the `selector`, you still need to include the `[data-nav-toggle]` attribute in order to pass in the selector for the navigation menu.* ### Use Astro events in your own scripts You can also call Astro's navigation toggle event in your own scripts. #### toggleNav() Expand or collapse a navigation menu. ```javascript astro.toggleNav( toggle, // Node that toggles the dropdown action. ex. document.querySelector('#toggle') navID, // ID of the navigation content wrapper. ex. '#nav-menu' options, // Classes and callbacks. Same options as those passed into the init() function. event // Optional, if a DOM event was triggered. ); ``` **Example** ```javascript astro.toggleNav( null, '#nav-menu' ); ``` #### destroy() Destroy the current `astro.init()`. This is called automatically during the init function to remove any existing initializations. ```javascript astro.destroy(); ``` --- ## Dropdown Menus You can add dropdown menus to your primary navigation menu with the `addDropdown()` function. The function accepts three arguments: 1. The URL in your navigation to add the dropdown to, 2. The items to add to it (as an array of data), and 3. Optionally, text to use for link it's replacing (which gets added as an item in the dropdown menu). ```js var dropdownData = [ { title: 'Hello', url: '#hello' }, { title: 'World', url: '#world' } ]; // The "/docs" link will be added as the first item in the dropdown, with the label "Overview" addDropdown('/docs', dropdownData, 'Overview'); ``` Add this to the `Body JavaScript` section under `Portal > Portal Setup` in the API Control Center. --- ## Docs Expand-and-Collapse Navigation If you have a nested documentation structure, you can add expand-and-collapse functionality to your docs navigation with `docsNavCollapse.js`. The script will not run until initialized in a `portalAfterRender` event. This is done for you already in the `Body JavaScript` section under `Portal > Portal Setup` in the API Control Center. ```js docsNavCollapse(); ``` You can optionally pass in an object of options to configure the script's behavior. ```js docsNavCollapse({ selector: '#nav-docs', // The selector for your docs nav section (only needed if you change it from the default) className: 'docs-nav-dropdown', // The class to add to the dropdowns for styling purposes overview: 'Overview' // The text to use for the link to the section homepage }); ``` --- ## Image Styling Add simple `.img-*` classes to any img element to add styling. You can combine classes for additional styling options. Mix-and-match as desired. ```html ``` --- ## Responsive Videos Your theme comes bundled with [fluidvids.js](https://github.com/toddmotto/fluidvids), a lightweight script that makes iframe videos responsive.

The script will not run until initialized in a `portalAfterRender` event. This is done for you already in the `Body JavaScript` section under `Portal > Portal Setup` in the API Control Center. ```javascript // Responsive iFrame Videos fluidvids.init({ selector: ['iframe', 'object'], players: ['www.youtube.com', 'player.vimeo.com'] // players to support }); ``` --- ## Sticky Footer If there's not a lot of content on a page, the footer may not be tall enough to fill the rest of the page, resulting in a gap at the bottom of the page. The `stickyFooter.js` plugin pushes the footer down to the bottom of the page even on pages without much content. The script will not run until initialized in a `portalAfterRender` event. Pass in a unique selector for the footer as an argument. This is done for you already in the `Body JavaScript` section under `Portal > Portal Setup` in the API Control Center. ```javascript stickyFooter('#footer'); ``` --- ## Enhanced Documentation Create beautiful, single-page documentation with toggleable code examples. Inspired by [Stripe](https://stripe.com/docs/api) and [PayPal's](https://developer.paypal.com/docs/api/) API documentation, and the [Slate open source project](https://github.com/lord/slate). [View the demo.](https://stagingcs1.mashery.com/docs/read/Better_Docs) ### Getting Started #### Markup Better docs automatically pulls `pre` and `blockquote` elements over to the right side of the page. You can write your docs in true HTML, use the WYSIWIG editor, or use markdown. Code examples wrapped in `pre` elements can also be toggled, so the developer can pick their language and only see examples in that language. Make sure to add a language class to your `pre` elements (ex. `pre class="lang-javascript`) for this to work. Code examples should be placed *above* the descriptive text for proper alignment. **Markdown** This example API documentation page was created with Better Docs. Feel free to edit it and use it as a base for your own API's documentation. ## Authentication > To authorize, use this code: ```bash # With shell, you can just pass the correct header with each request curl "api_endpoint_here" -H "Authorization: meowmeowmeow" ``` ```ruby require 'kittn' api = Kittn::APIClient.authorize!('meowmeowmeow') Make sure to replace meowmeowmeow with your API key. ``` ```python import kittn api = kittn.authorize('meowmeowmeow') ``` ```js const kittn = require('kittn'); let api = kittn.authorize('meowmeowmeow'); ``` >Make sure to replace meowmeowmeow with your API key. **HTML** ```html

This example API documentation page was created with Better Docs. Feel free to edit it and use it as a base for your own API's documentation.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: meowmeowmeow"

require 'kittn'

api = Kittn::APIClient.authorize!('meowmeowmeow')
Make sure to replace meowmeowmeow with your API key.

import kittn

api = kittn.authorize('meowmeowmeow')

const kittn = require('kittn');

let api = kittn.authorize('meowmeowmeow');

Make sure to replace meowmeowmeow with your API key.

``` #### Programming Language Toggle Add an empty `div` with the `.better-docs-nav` class. Your language toggle menu will automatically be injected here. ```html ``` You can include as many of these as you want in your markup. They'll update together, meaning that changing the language on one updates all of them and toggles programming languages through the documentation. You may want just one of them at the top of the page, or one above every code example. #### JavaScript Better Docs will not run until initialized in a `portalAfterRender` event. This is done for you already in the `Body JavaScript` section of `Portal > Portal Setup` in the API Control Center. You need to pass in the selector for your content as the first argument (this is typically the `.content` class). You also need to pass in a few options as an object for the second argument. `langs` are the languages you want to support. Each language needs a `selector` (the language name that appears after `lang-` or `language-` on the `pre` element class), and the `title` you want to appear in the language selector. You should also specify a `langDefault`, the language that Better Docs will show by default when the page loads. ```js // Enhanced documentation var docs = {}; if (document.querySelector('.better-docs-nav')) { docs = new BetterDocs('.content', { langs: { bash: { selector: 'bash', title: 'Bash' }, js: { selector: 'javascript, js', title: 'JavaScript', }, ruby: { selector: 'ruby', title: 'Ruby' }, python: { selector: 'python', title: 'Python' } }, langDefault: 'js', wideLayout: (document.documentElement.classList.contains('js-theme-sidebar') ? true : false), }); } ``` *__Note:__ Any language you don't specify in your options will always be visible.* #### Self-Destruct To prevent Better Docs styles from impacting other documentation pages, you'll need to destroy your initialization on other pages. Add a self-destruction listener in a `portalBeforeRender` event. ```js // Destroy instantiation on Ajax page reload window.addEventListener('portalBeforeRender', function () { if ('destroy' in docs) { docs.destroy(); } }, false); ``` ### Global Settings You can pass options into Better Docs on initialization. ```js var docs = new BetterDocs('.content', { // Only run on certain pages // This should match a window.mashery.contentType or window.mashery.contentId restrictToPages: 'docs', // Table of Contents // Automatically generated tocSelector: 'h2, h3, h4, h5, h6', // Headings to use to generate table fo contents tocHeading: '', // A heading to include above the table of contents tocLocation: '#nav-docs', // Where to inject the table of contents (defaults to below the current page navigation) currentPageSelector: '.current-page', // Selector for the current page in the docs sub navigation tocLocationReplace: false, // If true, replaces the navigation menu entirely // Languages langs: null, // The languages to include in the toggle menu langDefault: null, // The language to show by default langsNav: '.better-docs-nav', // The selector for the language toggle menu // Styles wideLayout: true, // Use a wide layout (docs and examples side by side) instead of a tranditional stacked layout wideLayoutBg: true, // Include a background color behind the code examples initClass: 'better-docs', // The class to add to the document element after Better Docs loads wideLayoutClass: 'better-docs-wide', // The class to add when wide layouts are enabled wideLayoutBgClass: 'better-docs-wide-bg', // The class to add when background color for wide layouts is enabled contentClassSuffix: '-content' // The suffix to add to the wide layout classes for the content area }); ``` ### Use Better Docs methods in your own scripts You can also call Better Docs methods in your own scripts. #### toggleLang() Toggle a programming language in the examples. ```js var docs = new BetterDocs('.content', { // ... }); docs.toggleLang('ruby'); ``` #### destroy() Destroy the initialization. ```js var docs = new BetterDocs('.content', { // ... }); docs.destroy(); ``` --- ## Display the Latest Blog Posts You can add a list of your latest blog posts to any page in your Portal. ### Demo ### Getting Started #### Markup Add a div with the `#latest-blog-posts` ID. ```html ``` For additional style, you can add "loading" placeholders that will disappear after the content is loaded by creating `div` elements with the `.placeholder` and `.placeholder-sentence` classes. ```html ``` #### JavaScript The script will not run until initialized in a `portalAfterRender` event. This is done for you already in the `Body JavaScript` section under `Portal > Portal Setup` in the API Control Center. ```js // Get the latest blog posts latestBlogPosts(); ``` ### Global Settings You can pass options into Latest Blog Posts when initializing. ```javascript latestBlogPosts({ selector: '#latest-blog-posts', // The selector for the div to render the posts into listClass: 'latest-blog-posts-list', // The class added to the latest posts list (used for styling) count: 5, // The number of posts to display excerptLength: 250, // The length of the blog post excerpt in characters listType: 'ul', // The list type (`ul` or `ol`) // The template for each post // Must pass in `post` as an argument and return a string // post.author - the post author // post.authorUrl - the URL of the author's profile // post.excerpt - the excerpt content // post.published - the date the post was published // post.title - the post title // post.url - the post URL template: function (post) { var template = '

' + '' + post.title + '
' + 'By ' + post.author + ' on ' + post.published + '
' + post.excerpt + '...' + '

'; return template; } })l ``` --- ## Utility Classes You can adjust text alignment, spacing, and visibility using a few simple CSS utility classes. ### Text Alignment | Class | Alignment | |----------------------|----------------------------------| | `.text-left` | Left | | `.text-center` | Centered | | `.text-right` | Right | | `.text-right-large` | Right *(only on bigger screens)* | ### Floats | Class | Float | |-----------------|----------| | `.float-left` | Left | | `.float-center` | Centered | | `.float-right` | Right | | `.float-middle` | Middle | | `.float-bottom` | Bottom | The `.float-middle` and `.float-bottom` classes should be applied to block level elements, and require a parent `div` with a `.float-*-wrap` class. ```html ``` Clear floats by wrapping floated content in a `div` with the `.clearfix` class. ```html ``` ### Margins | Class | Margin | |------------------------|--------------------| | `.no-margin` | all: `0` | | `.no-margin-top` | top: `0` | | `.no-margin-bottom` | bottom: `0` | | `.margin-top` | top: `1.5625em` | | `.margin-bottom` | bottom: `1.5625em` | | `.margin-bottom-small` | bottom: `0.5em` | | `.margin-bottom-large` | bottom: `2em` | | `.margin-left` | left: `1.5625em` | | `.margin-left-small` | left: `0.5em` | | `.margin-right` | right: `1.5625em` | | `.margin-right-small` | right: `0.5em` | ### Padding | Class | padding | |-------------------------|--------------------| | `.no-padding` | all: `0` | | `.no-padding-top` | top: `0` | | `.no-padding-bottom` | bottom: `0` | | `.padding-top` | top: `1.5625em` | | `.padding-top-small` | top: `0.5em` | | `.padding-top-large` | top: `2em` | | `.padding-bottom` | bottom: `1.5625em` | | `.padding-bottom-small` | bottom: `0.5em` | | `.padding-bottom-large` | bottom: `2em` | | `.padding-left` | left: `1.5625em` | | `.padding-right` | right: `1.5625em` | ### Visibility Hide content using the `[hidden]` attribute. ```html ``` If you have text that you don't want displayed on screen, but that should still be in the markup for screen readers (for example, a search form label), simply apply the `.screen-reader` class.

```html

Search this site

``` For visually hidden content that should become visible on focus (such as a [skip nav link](http://webaim.org/techniques/skipnav/) for sighted users navigating by keyboard), also add the `.screen-reader-focusable` class. ```html Skip to content ``` ### Visibility based on logged-in status The Mashery Portal provides high levels of custom access for pages and documentation based on whether or not a user is logged in, is a member of a particular role or group, and so on. However, these access levels apply to the entire page. You can selectively hide or show pieces content within a page or documentation only for logged-in users using the `.hide-logged-in` and `.hide-logged-out` classes. ```html ```