Front-End API

This section is a reference for the code you can use in the view.php file of your custom blocktype (AFTER you've created it via the dashboard interface).

The Foreach Loop

This is how you retrieve the repeating item data. The field_handles are whatever you defined in the dashboard interface when creating the blocktype.

foreach ($controller->getRepeatingItems() as $item) {
  $item->field_handle_1->display(option1, option2, etc.);
  $item->field_handle_2->display(option1, option2, etc.);
}

All of the sample code that follows is assumed to be inside the repeating items loop...

File fields

In these examples, the field handle is my_file...

• Output "force download" link to file (clicking link will download the file even if browser is capable of displaying it)
  Link text is the same as the getTitle() function (see below)

  $item->my_file->display();
  

  Outputs empty string if user leaves field blank.

• Output "view inline" link to file (clicking link will display file in browser if possible)

  $item->my_file->display(false);
  

  Outputs empty string if user leaves field blank.

• Get the file title:

  $title = $item->my_file->getTitle();
  

  Returns file's title attribute if user leaves editable title text blank or if "Editable Title Text" option is disabled.

• Get the "raw" (unescaped) file title:

  $raw_title $item->my_file->getTitle(false);
  

  Returns file's title attribute if user leaves editable title text blank or if "Editable Title Text" option is disabled.

• Get the file URL ("force download" behavior):

  $download_url = echo $item->my_file->getHref();
  

  Returns empty string if user leaves field blank.

• Get the file URL ("view inline" behavior):

  $view_url = $item->my_file->getHref(false);
  

  Returns empty string if user leaves field blank.

• Get the C5 File Object (on which you call ->getDescription(), ->getAttribute(), etc.)

  $file = $item->my_file->getFileObj();
  if ($file) {
    //do something
  }
  

  Returns null if user leaves field blank.

• Note about file permissions: If you have "Advanced Permissions" enabled for your site and you restrict the "view" permissions of a file, then the file will only be outputted if the user viewing the site has the appropriate permissions. If the user viewing the site doesn't have access to a chosen file, then the various functions above will behave as if the file was not provided (e.g. the display() function will output an empty string, the getFileObj() function will return null, etc.).

Image fields

In these examples, the field handle is photo...

• Output <img> tag for the original (non-resized) image
  This image tag will include width and height attributes
  Alt text is the same as the getAltText() function (see below)

  $item->photo->display(); //results in <img src="path/to/image.jpg" width="xxx" height="yyy" alt="alt text" />
  

  Outputs empty string if user leaves field blank.

• The display() function for image fields accepts the same arguments as the C5 image helper's getThumbnail() function:

  $item->photo->display(200, 100); //resize proportionally: max 200px wide, max 100px tall
  $item->photo->display(200); //resize down to 200px wide, and whatever height matches that proportionally
  $item->photo->display(0, 100); //resize down to 100px tall, and whatever width matches that proportionally
  $item->photo->display(150, 150, true); //cropped to 150px square
  

  Outputs empty string if user leaves field blank.

• Responsive Web Design note: Images can be "responsive" even with the width/height attributes! Just add this to your CSS: img { width: auto; max-width: 100%; height: auto; }

• Get image alt text:

  $alt = $item->photo->getAltText();
  

  Returns image file's description attribute (or title attribute if description is empty) if user leaves editable alt text blank or if "Editable Alt Text" option is disabled.

• Get the "raw" (unescaped) image alt text:

  $raw_alt = $item->photo->getAltText(false);
  

  Returns image file's description attribute (or title attribute if description is empty) if user leaves editable alt text blank or if "Editable Alt Text" option is disabled.

• Get an "image object" (similar to the C5 image helper's getThumbnail() function, except it could be for the original image as well as a thumbnail) Note that this function accepts the same width/height/crop arguments as the display() function above

  • original (not resized) image:

    $img = $item->photo->getImageObj();
    if ($img) {
      echo $img->src; //path to original (unresized) image file
      echo $img->width; //original image width
      echo $img->height; //original image height
    }
    

  • proportionally resized thumbnail:

    $img = $item->photo->getImageObj(200, 100);
    if ($img) {
      echo $img->src; //path to thumbnail
      echo $img->width; //width of resized image
      echo $img->height; //height of resized image
    }
    

  • cropped thumbnail:

    $img = $item->photo->getImageObj(150, 150, true);
    if ($img) {
      echo $img->src; //path to cropped thumbnail
      echo $img->width; //width of cropped image
      echo $img->height; //height of cropped image
    }
    

  Returns null if user leaves field blank.

• Get the C5 File Object for the image (on which you can call ->getDescription(), ->getAttribute(), etc.)
  Note that unlike getImageObj(), this function has no arguments (because it doesn't do any resizing)

  $file = $item->photo->getFileObj();
  if ($file) {
    //do something
  }
  

  Returns null if user leaves field blank.

• Note: If for some reason you want to call the C5 image helper's getThumbnail() function yourself, you'll need to pass it the result of the getFileObj() function (NOT getImageObj()).

• Note about file permissions: Images follow the same permissions rules as files -- see note at the end of the "File Fields" section above for details.

WYSIWYG fields

In these examples, the field handle is content...

• Output the html from the rich text editor:

  $item->content->display();
  

  Outputs empty string if user leaves field blank.

• Get the content (without outputting it):

  $content = $item->content->getContent();
  

  Returns empty string if user leaves field blank.

• Note that unlike most other field types, there is no concept of "raw" versus "escaped" data for wysiwyg fields (because the whole point of the rich text editor is to generate actual HTML).

Textbox fields

In these examples, the field handle is title...

• Output the text:

  $item->title->display();
  

  Outputs empty string if user leaves field blank.

• Get the text (without outputting it):

  $text = $item->title->getText();
  

  Returns empty string if user leaves field blank.

• Get the "raw" (unescaped) text:

  $raw_text = $item->title->getText(false);
  

  Returns empty string if user leaves field blank.

Textarea fields

In these examples, the field handle is description...

• Output the text:

  $item->description->display();
  

  Outputs empty string if user leaves field blank.

• Get the text (without outputting it):

  $text = $item->description->getText();
  

  Returns empty string if user leaves field blank.

• Get the "raw" (unescaped AND without being passed through nl2br()) text:

  $raw_text = $item->description->getText(false);
  

  Returns empty string if user leaves field blank.

Link fields

In these examples, the field handle is some_link...

• Output <a> tag to the linked page or url.
  Link title is the same as the getText() function (see below)

  $item->some_link->display(); //includes `target="_blank"` for external urls, but not for site pages
  $item->some_link->display(true); //ALWAYS includes `target="_blank"`
  $item->some_link->display(false); //NEVER includes `target="_blank"`
  

  Outputs empty string if user leaves field blank.

• Get the link href:

  $href = $item->some_link->getHref();
  

  Returns empty string if user leaves field blank.

• Get the link text:

  $text = $item->some_link->getText();
  

  Returns page name (for site pages) or the url (for external urls) if user leaves editable link text blank or if "Editable Link Text" option is disabled.

• Get "raw" (unescaped) link text:

  $raw_text = $item->some_link->getText(false);
  

  Returns page name (for site pages) or the url (for external urls) if user leaves editable link text blank or if "Editable Link Text" option is disabled.

• Determine if user entered a site page or an "external url":

  $is_page_link = $item->some_link->isPageLink();
  if ($is_page_link) {
    //user chose a site page from page chooser control
  } else {
    //user entered an "external url" (or they left both controls blank)
  }
  

  Returns false if user leaves field blank.

• [Added in version 1.2]: Get the C5 Page/Collection Object (on which you call ->getCollectionName(), ->getCollectionDatePublic(), ->getAttribute(), etc.)

  $page = $item->some_link->getPageObj();
  if ($page) {
    $some_attribute = $page->getAttribute('some_custom_attribute_handle');
    //do something...
  }
  

  Returns null if user leaves field blank or if the link is an external link.

Page fields

This field type is similar to the "Link" type -- but they differ in that the purpose of a "Link" field is to get a url that can be placed into an <a> tag, whereas the purpose of the "Page" field is to get a Concrete5 Page Object.
Another way to think about this is like the difference between the autonav and page_list blocks. Autonav is for nav menus where you just need the page titles and links, but Page List templates often display a lot more information about the page (publish date, image attributes, descriptions/teasers, etc.).

In these examples, the field handle is the_page...

• Output <a> tag to the chosen page. Link text will be the page name. Note that this function exists to maintain consistency with other field types -- you will probably never need to use it in actual code.

  $item->the_page->display();
  

  Outputs empty string if user leaves field blank.

• Get the C5 Page/Collection Object (on which you call ->getCollectionName(), ->getCollectionDatePublic(), ->getAttribute(), etc.)

  $page = $item->the_page->getPageObj();
  if ($page) {
    $title = $page->getCollectionName();
    $url = Loader::helper('navigation')->getLinkToCollection($page);
    $img_attr = $page->getAttribute('some_custom_attribute_handle');
    $thumb = $img_attr ? Loader::helper('image')->getThumbnail($img_attr, 300, 200) : false;
    
    echo '<h2><a href="' . $url . '">' . $title . '</a></h2>';
    if ($thumb) {
      echo '<img src="' . $thumb->src . '" width="' . $thumb->width . '" height="' . $thumb->height . '" alt="" />';
    }
  }
  

  Returns null if user leaves field blank.

Date fields

[Date fields were added in version 1.2]

In these examples, the field handle is start_day...

• Output the date in the C5 default format:

  $item->start_day->display();

  Outputs empty string if user leaves field blank.

• Output the date in a different format:

  $item->start_day->display('F jS, Y');

  See https://php.net/date for date formatting options.

  Outputs empty string if user leaves field blank.

• Get the date in the C5 default format:

  $start_date = $item->start_day->getDate();

  Returns empty string if user leaves field blank.

• Get the date in a different format:

  $start_date = $item->start_day->getDate('F jS, Y');

  See https://php.net/date for date formatting options.

  Returns empty string if user leaves field blank.

NOTE about using alternate date formats: In order to make the date picker work for non-U.S. date formats, you need to define the following 2 settings in your config/site.php file:

define('DATE_APP_GENERIC_MDY', 'j/n/Y'); //as per https://php.net/date
define('DATE_APP_DATE_PICKER', 'd/m/yy'); //as per https://api.jqueryui.com/datepicker/#utility-formatDate

The two definitions must equate to the same format, although they each use different codes!

DATE_APP_GENERIC_MDY is used in PHP code and hence must be a valid format as per the date() function (see https://php.net/date).

DATE_APP_DATE_PICKER is used in Javascript code for the JQueryUI date picker widget, and hence must be in a different format (see https://api.jqueryui.com/datepicker/#utility-formatDate).

Checkbox fields

[Checkbox fields were added in version 1.2]

In these examples, the field handle is is_special...

• Output "Yes!" if the box was checked, or "No." if it wasn't checked:

  $item->is_special->display('Yes!', 'No.');

  If you don't pass in a 2nd argument to the display function, an empty string will be outputted when the box is unchecked.

• Determine if the box was checked:

  $is_checked = $item->is_special->isChecked();
  if ($is_checked) {
    //do something...
  }

Select List fields

[Select List fields were added in version 1.2]

Select List fields come in two different types: Dropdown List (which only allow a single selection) and Checkbox Lists (which allow multiple selections).

Populating Select Options

When you are creating your custom blocktype via the Designer Content Pro dashboard page, you enter all of the options that will populate the dropdown or checkbox list via the "Select Options" text area. Enter one option per line, and each option must contain a "handle" and a "label", separated by a colon. For example:

1: First Choice
2: Second Choice
3: Third Choice

In the above example, "1", "2", and "3" are the handles (which become the dropdown or checkbox values), and "First Choice", "Second Choice", and "Third Choice" are the labels (which become the dropdown or checkbox labels).

Handles can only contain letters (lowercase and uppercase), numbers, and underscores. Labels can contain any characters. For example, the following handles are all valid:

first_choice: First Choice
2nd_choice: Second Choice
Third_Choice: Third Choice

...but none of the following handles are valid:

first choice: First Choice
second.choice: Second Choice
third_choice!: Third Choice

Also note that every handle must be unique within a field

Last but not least, you can specify a "header option" for dropdowns by leaving the handle blank:

: --Choose One--
first: First Choice
second: Second Choice
third: Third Choice

This "header option" is especially useful when you wish to make a dropdown field "required" without defaulting to the first item in the list

Working With Select Field API

In these examples, the field handle is your_choice:

• Output the chosen label (for dropdown lists) or a comma-separated list of chosen labels (for checkbox lists):

  $item->your_choice->display();

  Outputs empty string if nothing was selected/checked by user.

• Determine if a particular option handle was selected/checked:

  $first_choice_is_selected = $item->your_choice->isChecked('first_choice');
  if ($first_choice_is_selected) {
    //do something...
  }
  

• Get the handle of the selected option:

  $selection = $item->your_choice->getSelectedHandle();
  if ($selection == 'first_choice') {
    //do something...
  } else if ($selection == 'second_choice') {
    //do something else...
  } else {
    //etc.
  }
  

  This function is intended for use with dropdown lists. If you call it on a checkbox list, only the first checked option handle will be returned.

  Returns empty string if nothing was selected/checked by user.

• Get the handles of all checked options:

  $selections = $item->your_choice->getSelectedHandles();
  foreach ($selections as $selected_handles) {
    //do something...
  }
  

  This function is intended for use with checkbox lists. If you call it on a dropdown list, an array with 1 element will be returned.

  Returns empty array if nothing was selected/checked by user.

• Get the label of the selected option:

  $label = $item->your_choice->getSelectedLabel();
  echo $label;

  This function is intended for use with dropdown lists. If you call it on a checkbox list, only the first checked option label will be returned.

  Returns empty string if nothing was selected/checked by user.

• Get the labels of all checked options:

  $labels = $item->your_choice->getSelectedLabels();
  echo '<ul>';
  foreach ($labels as $label) {
    echo '<li>' . $label . '</li>';
  }
  echo '</ul>';
  

  This function is intended for use with checkbox lists. If you call it on a dropdown list, an array with 1 element will be returned.

  Returns empty array if nothing was selected/checked by user.

• Get an associative array of all selected options (handles as array keys, labels as array values):

  $selections = $item->your_choice->getSelections();
  echo '<ul>';
  foreach ($selections as $handle => $label) {
    echo '<li>' . $handle . ': ' . $label . '</li>';
  }
  echo '</ul>';
  

  Returns empty array if nothing was selected/checked by user.

• Get an associative array of all select options defined for the field (regardless of whether or not they were selected/checked by the user):

  $all_options = $item->your_choice->getAllOptions();
  echo '<ul>';
  foreach ($all_options as $handle => $label) {
    echo '<li>' . $handle . ': ' . $label . '</li>';
  }
  echo '</ul>';