TWO IMPORTANT THINGS TO BE AWARE OF:

1. You must have write permissions enabled on your site's /blocks/ directory at the time you first create the block. Ideally you should create the blocks on your own local computer before deploying to your server (using WAMP or MAMP, for example). If this is not an option, you will need to log into your server via FTP or CPanel and manually set the permissions of the /blocks/ directory to allow the web server process to write to it. After you've created the block, remember to go back and reset permissions to what they were before (to avoid potential security issues).
2. IF using version 3.0.2 or lower, *OR* Concrete5.5.1 or lower, *OR* your site contains block types made with an older version of Designer Content (prior to version 3.1): You should always keep this addon installed on your site (if you've created any blocks with it), otherwise the add/edit dialogs may not work properly. Although the blocks you create with this tool are isolated to their own directory in your site (they do not exist in this addon's package directory), they still rely on library code contained in the addon package to address some bugs in the core system, as well as language translations (if you are a non-english user). If you uninstall the package, the blocks will still remain on your site and they will continue to display properly when visitors view the pages they're on, but when users try to add new blocks or edit blocks on the page, they will run into some buggy behaviour related to combining the WYSIWYG editor and the image/page selectors controls in the same add/edit dialog. Note that if your site does not contain any block types made with an older version of Designer Content (prior to 3.1), and you are using Designer Content version 3.1 or higher, and your site is running Concrete5.5.2 or higher, you do *not* need to keep the Designer Content package installed!!

See the bottom of this page for some other (less-important) details.

 

INSTRUCTIONS FOR USE:

1. For Concrete5.5.0 and higher, go to Dashboard -> Stacks & Blocks -> Designer Content. For Concrete5.4.2.2 and lower, go to Dashboard -> Pages and Themes, then click "Designer Content" in the grey bar at the top of the page (to the right of "Single Pages").
2. Enter a block handle, a block name, and optionally a description for the block
3. Start adding fields that you want users to be able to edit when they add this block to a page. The "Field Label" will be displayed next to the field in the add/edit dialog (so the user knows what field they're editing), and the "Wrapper HTML" is outputted to the browser when the block is displayed on a page (so that you can style the user's content appropriately). See the "FIELD TYPES" section below for more details about each field's settings.
4. The order of the fields is important -- this determines both the order that the fields are displayed in the add/edit dialog, AND the order that their HTML is outputted when a page containing the block is viewed. You can change the order of the fields using the "[Move Up]" and "[Move Down] links on the right side of tha page.
5. After you have configured the fields that you want in this block and placed them in the proper order, click the "Make This Block!" button.
6. That's it! The block you just created is now installed in your site and ready to be added to pages, just any other block. If you want to examine the block's code files, you can find them in your site's /blocks/ directory (not /concrete/blocks/, and not /packages/). If you change your mind and don't want this block in your site anymore, simply uninstall it from Dashboard -> Add Functionality like you would any other block or addon (note that you should only uninstall the block you created, not the Designer Content package).

 

FIELD TYPES:

• Text Box: Provides a simple textbox for your user to enter plain text into. This is most useful for headings and titles where you want to ensure that the text is placed inside an h1/h2/h3/etc. tag. The tag goes into the Wrapper HTML boxes (Wrapper HTML Open could be "<h2>", and Wrapper HTML Close could be "</h2>" for example). Wrapper HTML is never shown to the user when they edit the block (all they see is the Field Label and the textbox that they use for data entry) -- rather, it is outputted in the markup when someone views a page with this block in it. The "Maximum Number Of Characters" option lets you restrict the length of the text that can be entered by the user. You can leave this field blank if you do not want to limit the entry length.
• Text Area: Provides a multi-line textbox for your user to enter plain text into. Any newlines entered into this box will be outputted as html "<br />" tags.
• WYSIWYG Editor: Provides a TinyMCE Editor just like Concrete5's built-in Content block. The "Default HTML Content" box can be used for "starter content" that is initially displayed in the editor when a user first adds one of these blocks to a page -- see the "Default Table Style" example below for more information about this technique. Note that unlike the other field types, there cannot be more than one WYSIWYG field per block (due to limitations of the core Concrete5 code). As of version 3.1, you can now have as many WYSIWYG editors in the same block as you want (requires Concrete version 5.5.2 or higher).
• Image: Provides an image selector for your user to choose an image from the file manager. The following options are available:
  • Required: Check this box to require that an image be chosen (note that there is no way to require alt text or a link)
  • Show Alt Text Field: Choose "Yes" to provide an input below the image chooser where the user can enter alt text for the image. If you choose "No", an empty alt attribute will be outputted to the image (alt="").
  • Show Link Field: Two options are available for allowing the user to choose where the image should link to when clicked. "Sitemap Page" allows the user to choose another page within the site (via a Sitemap popup), and "External URL" allows the user to enter a full URL to any other website.
  • Image Sizing: Choose "Resize Proportionally" to automatically scale down the user's chosen image when displayed so that it is never larger than the given width and/or height (note that you can enter just one of the dimensions if you only care about restricting the width or the height but not both). Choose "Resize+Crop To Fit" to automatically scale and crop the user's chosen image when displayed so that it matches an exact width and height (note that the image is always cropped to the center). Both options (Resize Proportionally and Resize+Crop To Fit) will always only make images smaller -- images will never be enlarged (so if the pixel dimensions you enter are larger than the chosen image, the image size will not be changed at all).
• File Download: Provides a file selector for your user to choose a file from the file manager to make it available for download. The file download link HTML is outputted with a CSS class containing the file extension, which allows you to set different icons for different file types (for example, "file-pdf" or "file-xls").
• Page Link: Provides a page selector for your user to choose a page from the sitemap, along with a "Link Text" field for the anchor text of the link. Note that you cannot place CSS classes on the <a> tags themselves -- to style these, you need to add some Wrapper HTML with the class and refer to it that way (for example, if the wrapper has <span class="read-more">,
  your CSS would be ".read-more a { ... }" instead of "a.read-more { ... }").
• External URL: Provides a textbox for your user to enter any URL. By default, these links will be opened in a new window, but you can uncheck the "Links Open In New Window" box to disable this.
• Date Picker: Provides a javascript calendar control that can be used to choose a specific date. The output of the date can be customized using a PHP date format string (see http://php.net/date#refsect1-function.date-parameters for details).
• Dropdown List: Provides a dropdown list from which your user makes a choice. You enter the list of choices in the "Dropdown Choices" textbox, and optionally add a "heading" choice (the first item in the list that appears by default, generally used to give instructions to the user -- e.g. "Choose One"). Note that the dropdown list does not provide any front-end functionality -- you must edit the view.php file after the block type has been generated to give it the proper functionality. The view.php file will contain the various php "if" statements that correspond to each dropdown choice, and it is up to you to "fill in the blanks" in terms of what each choice actually does (for example, you could show certain HTML if a certain choice is made).
• Static HTML: Unlike the other field types, this is not editable by the user and does not show up in the add/edit dialog -- its purpose is to allow you as the designer to ensure certain HTML always appears when this block is displayed on a page. This is similar to the "Wrapper HTML" options, except that Static HTML is ALWAYS displayed (whereas "Wrapper HTML" is only displayed if the user enters content for that particular field). This is primarily used for HTML that defines the overall structure of your block's display (as opposed to defining styles and positions of individual fields within the block). For example, if the block you're creating should always be surrounded by a border when viewed on a page, you can place Static HTML at the top of your field list containing <div style="border: 1px solid black;">, then add another Static HTML to the bottom of the field list containing "</div>" (to close the opening div in the first Static HTML).

 

USAGE EXAMPLES:

• EMPLOYEE BIO BLOCK: Let's say some of the pages in your site's design call for little boxes showing a picture of a person, with their name as a heading, and normal text below the heading. The heading and text should be placed to the right of the image, and the text should not wrap around the image when it extends lower than the image height. To create this block, you could add the following fields:
  
  • STATIC HTML: <div class="employee-bio">
    (This is the div that wraps the entire chunk of content. The class would be defined in your theme's CSS file and determine how this block is placed in the overall page layout, if it has a border or shadow, a background color, etc.)
  • TEXTBOX: Label is "Employee Name", check the box for "Required". Wrapper HTML Open: <h2>. Wrapper HTML Close: </h2>
    The wrapper div ensures that the name entered by the user will be displayed on the page inside an h2 tag -- by entering it here as a wrapper, you can ensure that your styles are maintained and also make the process simpler for the user because they don't have to remember how to set it themselves like they would in the WYSIWYG editor.
  • IMAGE: Label is "Employee Photo", check the box for "Required", and set the maximum width and height. Wrapper HTML Open: <div class="employee-photo">. Wrapper HTML Close: </div>. Note that you don't necessarily need the wrapper HTML because you could style this in your CSS via ".employee-bio img { ... }", but then if the user inserts another image into the WYSIWYG editor below, those will pick up that style as well and probably not look so great. Alternatively you could not use any wrapper HTML and instead use the "first child" selector in your CSS like this: ".employee-bio > img { ... }" to make sure the style only applies to images that are immediately inside the element having the "employee-bio" class (and not inside other divs that are themselves inside the "employee-bio" div).
  • CONTENT: Label is "Brief Bio". Leave the default HTML empty.
  • STATIC HTML: </div>
    (This closes the "employee-bio" div up top)

 

• DEFAULT TABLE STYLE: Let's say some of the pages on your site contain charts (tables) of product information. You have styles set up in your CSS, but inserting tables into the WYSIWYG editor and making sure they have the appropriate style attached can be challenging. What you can do is create a custom block with just one WYSIWYG Editor field and place some sample table markup as the default HTML, so when the user adds a new block one of these "product data table" blocks, it will start out with a table already in it and some sample rows showing where to input data. You can also wrap the WYSIWYG content in a div so that you can set CSS styles that apply only to tables within that div. For example:
  
  • Static HTML: <div class="product-details">
  • WYSIWYG Editor: Label is "Product Table", Default HTML Content is:
    

    <table>
      <tr><th>Product</th><th>SKU</th><th align="right">Price</th></tr>
      <tr><td>Sample Product 1</td><td>12345</td><td align="right">$100.00</td></tr>
      <tr><td>Sample Product 2</td><td>67890</td><td align="right">$50.00</td></tr>
    </table>

  • Static HTML: </div>
    (This closes the "product-details" div up top)

(Note that you will need to set the "Rich Text Editor" in Dashboard -> Sitewide Settings to "Advanced" or "Office" mode, or enter "Custom" settings that include the table controls in order for users to be able to effictively edit the table when they add a block).

 

OTHER DETAILS:

• At this time, you cannot change a block type (i.e. add more fields, remove fields, or change field settings) after you have created it using the dashboard interface. You CAN modify the block's code files (in your site's /blocks/ directory), but you should only try this if you know what you're doing. Another option (assuming users have not yet added any of these blocks to the site) is to simply uninstall the block and then re-create it with different field settings (although you probably want to give it a different block handle -- see the following note).
• If for some reason you uninstall and then re-install the Designer Content addon package, you should immediately clear your site cache (Dashboard -> Sitewide Settings, scroll down a bit and click the "Clear Cache" button). If you don't do this, you might see some strange errors on the pages containing the custom blocks you created, as well as in the dashboard when trying to create new blocks.