Blocks Reference Manual

Installation

To install the Blocks plugin:

• Download Blocks from our website.
• Double click the Blocks.stack file.
• If RapidWeaver is running, restart.

Blocks is now installed ready to use. 

Getting Started

To get started, you should have a Blocks page in a RapidWeaver file already created. If you don't have a Blocks page already, create one by choosing Add Page in RapidWeaver and selecting Blocks.

Block Types

Styled Text Block

A Styled Text Block is like a mini-Style Text Page that you can put anywhere on your Blocks page. Each Styled Text Block can contain text, graphics, and some HTML markup.

Image Text Block

An Image Text Block is a text block that will be converted into an image when your page is published. The advantage of using an Image Text blocks is that you are free to use any fonts, styles, colors, and special characters you like. You're not restricted to "Web safe" fonts. The disadvantage is that images are much slower to download -- so it's best to use Image Text only when you really need it.

HTML Code Block

An HTML Code Block is a direct link to the code on your page. If you have a snippet of HTML, Javascript, or PHP that you need to put somewhere on your page, an HTML Code Block lets you add that code and place it where you want.

Page Block

A Page Block lets you incorporate other pages from your RapidWeaver site into a block on your Blocks page.

Image Block

Image Blocks are automatically created when you drag an image into the Blocks page.

Adding Blocks

To add a block to your layout click on one of the Block buttons from the toolbar or drag an image from the Finder into your layout. Once you've added a block you can use the Inspector button to open the Block Inspector window and configure your new block. See below for more info on using the Block Inspector palette. To add an Image Block just drag an image from the Finder into the blocks edit view and drop it anywhere.

Using Blocks

Selecting Blocks

Click

To select a block, click on it. Small square handles appear on the corners to show that the block is selected. To deselect a block, click anywhere else in the RapidWeaver window.

Shift-Click

To select more than one block, hold down the Shift key or the Command(Apple) key on your keyboard while you continue to click on more blocks. While holding down Shift or Command, clicking on a block toggles its selection.

Drag

You can drag a selection area around several blocks. As the selection area touches each block it will become selected. To add or remove blocks from your selection just Shift-click.

Select All

Choosing Select All from the Edit menu will select all the blocks in your layout.

Hint: Once a block is selected you can interact with that block even if it is completely obscured by other blocks. It will act as if it is on the top-most layer, even if it is buried.

Moving And Resizing Blocks

To move a block, first select it, then click and drag to move it.

To resize a block, first select it, then click on one of the small square handles on the corners and drag the handle to reshape the block. Holding down the Shift key while you drag the handles constrains the block to its current aspect ratio.

Note: Image Blocks have a constrained aspect ratio by default. So the using Shift key works in reverse: it removes the aspect ratio constraint.

Nudging Blocks

To move a block by just one pixel use the arrow keys on your keyboard. If you'd like to move them a bit faster, hold down the Shift key. Shift-Arrow nudges by 10 pixels.

Editing Blocks

Text

To edit the text within a Styled Text Block, Image Text Block, or an HTML Code Block, first select the block, then click on the block once more to edit. To stop editing click outside the block.

Hint: It may seem as though you need to double-click in order to edit the text, but this is not the case. A single-click on a block that is already selected will always enable editing in that block.

Pages

The page block incorporates content from other pages. Edit the content of Page Blocks by editing the other pages. Then use the Block Info window to configure the page block to incorporate that page.

Duplicating Blocks

Copy-and-Paste

Just as in any Macintosh application you can copy any block (or group of blocks) and paste them to produce a copy. You can also Cut or Copy blocks from one Blocks page and paste them into another Blocks page.

Option-Drag

If the option key is held while dragging a block then a duplicate of the block will be produced.

Deleting Blocks

Clear Menu

Choosing Clear from the Edit menu will delete the selected blocks.

Delete Key

Pressing the delete key, backspace key, or forward delete key on your keyboard will also delete the selected blocks.

The Toolbar

The Blocks toolbar gives you quick access to the things you'll do the most in Blocks: creating new blocks, adding links, and changing text styles.

Text

The Text button adds a Styled Text Block to your page. Styled Text Blocks are the basic building blocks of a Blocks page. Styled Text Blocks can contain text and graphics, just like a mini-Styled Text Page. In fact, almost every option available to a Styled Text Page is available to a Styled Text Block. To add a Styled Text Block, click on the Text button.

Image Text

The Image Text button adds a Image Text Block to your page. An Image Text Block is a text block that will be converted into an image when your page is published. The advantage of using an Image Text blocks is that you are free to use any fonts, styles, colors, and special characters you like. You're not restricted to "Web safe" fonts. The disadvantage is that images are much slower to download -- so it's best to use Image Text only when you really need it. To add an Image Text Block, click on the Text button.

HTML

The HTML button adds an HTML Code Block to your page. An HTML Code Block can be used to enter raw HTML into a block. The HTML code that is entered into the block will be rendered inside the confines of the block size.

• Hint: A great way to test out your HTML code is to use an HTML Page. After you get your HTML Page to be just right, copy the text from that page into an HTML Code Block.
• Hint: An HTML Code Block can easily be used to include inline Javascript in your site. To ensure that your script is loaded before your other, blocks make sure that you choose the lowest layer for the block that contains your Javascript. In the Block Info Palette, under the Object tab, choose To Back in the Layer section. See below for more info.

• Note: If you add PHP content don't forget to change the filename extension of your Blocks page to "php". To change the filename extension use the Page Inspector located in the Windows menu, the setting is located under the Info tab. And of course, you'll need to have a server that supports php content as well. For more details about the Page Inspector, the Contact Form, and PHP content please refer to the RapidWeaver manual.

Page

The Page button adds a Page block to your page. A Page block incorporates the content from another page on your site into a block. To add a Page block click on the Page button. To configure a Page block click on it to select it and choose a page from the popup menu in the Block Info under the Content tab.

• Hint: Not every page or every combination of pages can be added together. The content on each page must be compatible with the content that it is being combined with. For example: You cannot add two slideshows to the same page as their internal javascript was not designed to be shared.
• Hint: Choosing Stretch to fit content from the Block Inspector under the Block section Layout tab will help to accommodate pages with a flexible length.

• Note: If you add content from a PHP page (such as a Contact Form or RapidBlog) don't forget to change the filename extension of your Blocks page to "php". To change the filename extension use the Page Inspector located in the Windows menu, the setting is located under the Info tab. And of course, you'll need to have a server that supports php content as well. For more details about the Page Inspector, the Contact Form, and PHP content please refer to the RapidWeaver manual.

Add/Remove Link

The Add Link and Remove Link buttons can be used to edit the links on your page. Select the item that you'd like to link, such as an Image block, an Image Text block or some text in a Text block, then choose Add Link. The standard RapidWeaver link panel then lets you specify the link.

To remove a link, select the object then click Remove Link.

Buy Blocks

When you are ready to purchase Blocks, click the Buy Blocks button. If the Buy Blocks button is not visible, then either you need to update to the latest version or your RapidWeaver window is not wide enough to display all of the buttons. Simply resize the window wider to view all of the buttons.

• Note: Once you've purchased Blocks the Buy Blocks button will no longer appear.

Fonts

The Fonts button brings up the standard Mac OS X font palette. You can use the font palette to change the text in your Styled Text Blocks however it's safest to choose fonts that are from the "Web" collection. In an Image Text block you can choose any font available on your system since it will be rendered to an image before being published.

• Note: The font window contains all the fonts available on your Macintosh. Most of these fonts will not be available on many machines that can browse to your pages. To create a consistent experience for all the people viewing your site it's very important to choose fonts only from the "Web" category. Choosing other fonts will force browsers to replace those fonts with fonts they do know -- which can cause significant changes to your layout.

Colors

The Colors button brings up the standard Mac OS X color palette. The color palette is used for many purposes, such as setting background colors, stroke colors, and the color of text. To change the color of your text, select the text, open the color palette by clicking the Colors button, then choose a new color.

Smart Info

Clicking the Smart Info button opens the Smart Block™ Heads-Up Display (or HUD). The Smart Block HUD will display information about the Smart Block tags of the block that's selected. See this page for more information about how to use Smart Blocks, Smart Block Tags, and how they can help make your HTML code more user friendly.

Blocks Library

Clicking the Library button opens the Blocks Library. The Blocks Library is used to store, edit, and share reusable pages and blocks from your layout. See below to learn more about how to use the library, how to create Library Blocks, and how to share library Blocks.

Inspector

Clicking the Inspector button opens the Block Inspector palette. The Block Inspector palette is used to set all the properties of the blocks on your page. See below for more information.

The Block Inspector Palette

Block Tab > Layout

Size & Position

Dragging each block is an easy way to move them into their desired position, but when you need finer control you can use the Size & Position controls to fine tune your blocks. 

Text blocks will resize and reflow the text to fit into the space provided. You cannot make a block smaller than its content.

Image Blocks will resize the image as your change the size of the block.

Clicking on the lock icon next to each field will lock that property. If all the locks are clicked then the Block will neither move nor resize.

Checking the Stretch to fit content checkbox will ensure that the block "just fits" the content.

Layer

When blocks overlap they stack up. Each block is on its own layer. As blocks are created, they appear on the top of the stack. The oldest blocks appear on the bottom. You can change the order that your blocks are stacked in by using the buttons in the Layer section. Clicking To Front moves the selected block to the very top of the stack (to the top layer). The block that is at the top will show on top of any blocks that are below it. Clicking To Back moves the selected block to the very bottom of the stacking order (the bottom layer). The block that is on the bottom will show underneath any blocks that are above it. Clicking Forward and Backward moves the selected block up or down one position respectively.

Block Tab > Style

Background

The background color of each block can be set to any color, but by default is that it will be transparent. To choose a new background color for the selected block click the Background checkbox then click the color well next to the Background label. Choose a color from the color palette. Use the magnifying glass on the upper left side of the color palette to find a color from your screen.

Stroke

The stroke of a block is the border outline of the block. You can set the Width and Color of the stroke. The default is to inherit the stroke styles from your theme. In most cases your theme will not have a default stroke and will default to transparent. To choose settings different than the stroke styles from your theme click the Stroke checkbox then set the Width and Color as desired. When the Stroke Width is set to 0px, no stroke will appear even if you have selected a color. Adding a larger stroke will make the block larger overall. The content of the block will always be exactly the size that is set under the Object tab.

Margin

The margin width is the amount of space between the content of a block and the stroke (or the outer edge if there is no stroke). Adding more margin to a block will make the block larger overall. The content of the block will always be exactly the size that is set under the Object tab.

Content Tab > Text

Overflow

Because the fonts on each web browser differ and users themselves can change their font settings, the font that they see is very likely to be quite different to the font that you use in Edit mode. For this reason Blocks gives you some tools to help with the messy situation of text that overflows the boundary of its Block.

In most cases it's sufficient to Hide overflowing content and have Blocks attempt to shrink the text (using dynamic Javascript while the page is being loaded) to fit inside the Block. In some cases this can have undesired effects or you may just want more control. In these cases you can choose to turn off the shrinking (this is a page-wide global setting) and either show or scroll the text that does overflow.

Font Shrinking

Because blocks are fixed in size and the text that they contain may vary in size depending on the Theme, the browser used to view the page, the OS the viewer is using, and the preferences the user has set for their browser it is often the case that when a page is viewed the text no longer fits inside the block as it seemed to while designing the page layout.

Blocks compensates for these variables by automatically shrinking the text until it just fits inside the block as it was intended. This is done with a javascript at the time that the page is viewed so that each users personal preferences will be accounted for.

This behavior can lead to a side-effect where each block of text is not rendered in exactly the same size font -- even when that may have been the intention. If this affect is hurting your page you can check the Don't shrink Text to fit Blocks checkbox and the javascript will not run on the page.

Content Tab > Image

Image blocks and Image Text blocks can have their name and alt-tag specified. Alt-tags are used for accessibility and for clarification on browsers without full graphics support (phones and text terminals). A default alt tag is specified for all images so that your page meets CSS validation standards, however it's good practice to specify a more specific tag for each of your images.

Images can use the image format that is defined in the RapidWeaver Page Inspector or you can specify a format just for that image. This allows you to have several types of images on a single page -- useful if you have some images that you'd like to display in a more compressed format and some you'd like to display in a high quality format.

Content Tab > Page

The Page Block popup menu will become active when a Page block is selected in your layout. This popup menu will allow you to specify which other page you'd like to incorporate into the page block. The content of the page block is not edited within Blocks. The content is edited by editing the page that you include.

Not all page styles are able to be included in a page block. You cannot included other Blocks pages, HTML, Contact Forms, or Offsite pages. Some combinations of content do not work well together. As there are many combinations of possible pages with various content that could be combined YourHead may not have tested all combinations. Test your page in preview mode to determine if there are any incompatibilities.

Page Tab

Master Page

Each Blocks page can subscribe to another Blocks Master Page. All the blocks on the master page will be included on the subscribing page. All of the blocks that come from the master page will fixed in the size, shape, and style defined by the master. Blocks inhereited from a Master Page will selected with a red highlight rectange to distinguish inherited blocks from other blocks. Although the size, position, and style of inherited blocks is unchangable, the content may be modfied. Each page that subscribes to a Master Page can contain its own content.

• Note: To modify the content of an image block drag and drop the new image on top of the old image in edit mode. This will scale the new image to fit into the space of the old image so results are best if both new and old images are the same size.
• Hint: See Master Pages in action in our screencast: Click to view.

Background

The background color of the content area can be set to any color you like. By default the content area inherits its color from your page's theme. To select a new background color click the Background checkbox then click the color well next to the Background label. Choose a color from the color palette. Use the magnifying glass on the upper left side of the color palette to find a color from your screen.

Content Size

Blocks is designed to edit the content area within your web page. You can change the size of the Blocks content area to match the page theme and your personal preference. It's important that your content area fit the area that your theme provides; extending it beyond those bounds can result in cropped content and browser incompatibilities. To change the size of the page, enter the desired size in the Content Width and Content Height edit areas.

You can also choose the width to be fluid, meaning that it will be as wide as the page theme allows -- this is great if you're using a variable width theme. To use a fluid width, check the Use a fluid width checkbox and enter a percentage into the Fluid Width field. The percentage that you enter will be the percentage of the theme's content area that will be used by Blocks.

• Note: Internet Explorer 6 for Windows will have trouble drawing your page if the content width is larger than the available space your theme provides. The default width is small enough that it should work with most themes. If you want to increase it, start small and test test your published pages in IE 6 to ensure that everything is working as you expect.

Alignment

If your blocks content area is smaller than area that the theme provides, the content can be aligned left, right, or center into the content area. What you choose will depend on the overall alignment of the theme.

Internet Explorer Compatibility

Under normal circumstances all the content that Blocks produces is confined to the content area of your page. All themes define this area specifically for use by plugins like Blocks. When content is too big to fit within this area Blocks automatically crops the content so that it does not overflow. This is because when content overflows outside of its container it can cause some browsers (usually Internet Explorer for Windows) to render the page strangely.

If you are absolutely certain that you will not be deploying to Internet Explorer and you don't mind bending a few of the CSS rules then you can choose to display content that overflows. It's strongly recommended that you test you page on all browsers that the page will be viewed with as even non-IE browsers may have some difficulties.

Settings Tab

Guides

The alignment guides in blocks are great for lining up content on your page but they can sometimes get in the way. Sometimes it's nice to turn them off. Unchecking Show Guides will disable all the guides. Unchecking Show Center Guides or Show Edge guides will disable those guides individually.

The snapping of the guides can be enabled and disabled separately from the visible guides themselves. So that you can have the snapping effect without the visual guides or have the visual guides with no snapping. To disable snapping uncheck the Snap To Guides checkbox.

Grid

The alignment grid places guides at intervals across your page. You can specify the interval and if your blocks snap to the grid. If you turn of the Snap To Grid option then the grid is merely a visual alignment tool but will not actually have any affect on your block placement.

Outlines

Each block has a pale translucent blue outline that helps you to identify its boundaries. These can be helpful, but when you page contains a lot of overlapping transparent content they can also clutter up your visualization of the look of the page. To disable the block outlines uncheck the Show Block Outlines checkbox.

The Blocks Library

The Blocks Library is a place to store commonly used blocks. You can add your own library blocks, edit their attributes, share library blocks with other Blocks users, and drop in library blocks that others share with you.

The Blocks Library can store either single blocks or whole pages. Library Pages store not only every block from the layout but also the page width, height, and background color. Library Blocks store an entire block along with all its properties, content, and styles.

Creating a Library Block

To create a library block first open the Blocks Library window by clicking on the Library button in the toolbar. Next select the block in your layout that you would like to add to the Blocks Library. Click the "+" button on the bottom left corner the Blocks Library window. This will add the block selected block to the Blocks Library.

See below on how to customize the details of the newly created Library Block.

Creating a Library Page

To create a library page first open the Blocks Library window by clicking on the Library button in the toolbar. Click the "+" button on the bottom left corner the Blocks Library window. This will add your Blocks page to the Blocks Library. See below on how to customize the details of the newly created Library Block. Note: You can only add pages that contain at least one block. Empty pages cannot be added.

Removing a Library Block

To remove a Library Block from the Blocks Library click on the Library Block in the Blocks Library window. It will select and its background will turn a lighter shade. Click the "-" button at the bottom left of the Blocks Library window. You will be asked to confirm the action and then the block will be removed. Warning: removing a block is permanent. It not only removes it from the Blocks Library window but also deletes the associated file.

Sharing a Library Item

Each item in the Blocks Library is actually a file in the Finder. These files can be email to friends or added to a RapidWeaver File Sharing page. To find a library item in the finder first open up the Blocks Library window by clicking on the Library button in the toolbar. Select the library item in the Blocks Library window by clicking on it. Next click the "Details" triangle to reveal the details for the block. Then just click the small arrow next to the File Name. This will open up the Finder and select the file. Simply drag this file to your email or File Sharing page.

Adding a Shared Item

When someone shares a block that they have created you'll want to add it to your Blocks Library. Simply drag the Library Block file to your Blocks page. The library item will be copied to your Blocks Library and will be displayed in the Blocks Library.

Customizing the Details

Although library item is always given a preview icon that represents how it appears in Edit view and a default name sometimes you may want to customize these details to help you recognize and use the block more effectively. To start click on library item that you'd like to edit. Click on the "Details" triangle to reveal the extra details. Any of the text can be simply edited by clicking and editing. There is no need to save your changes, they will be automatically stored in the Library Block file whenever you make a change. To change the preview icon simply drag and drop a new image into the image well. The new preview will be stored in the library block and scaled to the appropriate size.

Smart Blocks

Smart Block HUD

The Smart Block HUD (Heads Up Display) displays special, user-defined, properties of the selected block. By default the Smart Block window is empty, but by adding Smart Block Tags to the content the Smart Block HUD will be updated with an interface for each tag. Building an interface for a block is a nice way to simplify a complex or repetitive coding task.

Smart Block Tags

// create a text input in the Smart Info window<br>

// assign the contents to a variable called "a_var"<br>

<blocks type='input' id='a_var' />

// create a color well in the Smart Info window<br>

// assign the contents to a variable called "a_color"<br>

<blocks type='color' id='a_color' />

// create a slider in the Smart Info window<br>

//with a minimum value of -100 and a max of 100<br>

// assign the selected value to a variable called "a_num"<br>

<blocks type='slider' id='a_num' min='-100' max='100' />

// use a variable called "a_var"<br>

// replace the whole markup  element with the contents of "a_var"<br>

//nothing is displayed in the Smart Info window<br>

<blocks id='a_var' />

// read the "height" property of the block<br>

// replace the whole markup element with the contents of the height property<br>

<blocks type='property' id='height' />

// other properties include:<br>

width, x, y, backgroundColor, strokeWidthTop, marginWidthTop, strokeColor, etc.</code>