Express Basics

Edit

Improvements?

Let us know by posting here.

Express in Concrete CMS

Express in Concrete CMS builds complex, relational database objects using Concrete attributes. It offers a simple API and handles relationships between objects with less overhead than using pages. If you've custom-built objects in Concrete websites, Express could streamline your process.

Creating Express Objects in Concrete CMS

Create Express objects in the Concrete CMS Dashboard by:

  1. Naming the object:
  2. Adding attributes:
  3. Setting up a form:

Using the Express Entry Block to Output Entry Data

This section covers how to showcase data from Express entries - specifically illustrating with an example of Marinas and Boats

Step-by-Step Implementation

  1. Linking Marina Pages with Express Entries: Create a custom page attribute to associate each Marina entry with its respective frontend page. Apply this attribute to the relevant pages:

  2. Adding Express Detail Block on Marina Pages: Insert an Express Entry Detail block on each Marina page, configured to reference the custom attribute.

  3. Custom Template for Displaying Boat Data: Develop a custom template for the block to exhibit details about boats associated with each marina.

    • Example of the custom template code: php <?php if (isset($entry) && is_object($entry)) { $boats = $entry->getBoats(); // Table structure and data display code } ?>

Creating Custom Block View Templates

For guidance on creating custom block view templates, click here.

This example demonstrates the flexibility of Concrete CMS in handling relational data through Express entities, leveraging magic methods for dynamic interaction with custom attributes and associations in an RDBMS environment.

Creating Express Objects Programmatically in Concrete CMS

This guide details how to programmatically create Express Objects in Concrete CMS, specifically for developers building Concrete packages.

Package Setup for Express Objects

Ensure you're familiar with Concrete package creation as described here before proceeding.

Building the Express Object

  1. Initializing Object Builder: Import Express facade in controller.php:

    use Express;

    Then initialize the Object Builder in install() method:

    public function install()
{
   $pkg = parent::install();
   $object = Express::buildObject('marina', 'marinas', 'Marina', $pkg);
}

  2. Adding Attributes: For adding custom attributes like 'Name' and 'Address':

    $object->addAttribute('text', 'Name', 'marina_name');
$object->addAttribute('address', 'Address', 'marina_address');

    For custom attribute settings (e.g., limiting countries):

    $settings = new \Concrete\Core\Entity\Attribute\Key\Settings\AddressSettings();
$settings->setCustomCountries(array("US","UK"));
$settings->setHasCustomCountries(true);
$settings->setDefaultCountry("UK");
$object->addAttribute('address', 'Address', 'marina_address', $settings);

  3. Saving the Object: Finalize and save the object:

    $object = $object->save();

Adding Associations

Create and save associations between Express Objects, like Marina and Boat:

$marina = Express::buildObject('marina', 'marinas', 'Marina', $pkg);
$boat = Express::buildObject('boat', 'boats', 'Boat', $pkg);

$builder = $marina->buildAssociation();
$builder->addOneToMany($boat);
$boat = $builder->save();
$marina = $marina->getEntity();

Building Express Object Forms

Create an Express form with attributes and field sets:

$student = Express::buildObject('student', 'students', 'Student', $pkg);
// Add attributes
$studentEntity = $student->save();

$form = $student->buildForm('Form');
$form->addFieldset('Basics')
    ->addAttributeKeyControl('first_name')
    ->addAttributeKeyControl('last_name')
    ->addTextControl('', 'This is just some basic explanatory text.')
    ->addAttributeKeyControl('bio');
$form = $form->save();

Set the default view and edit forms for the Express object:

$entityManager = $student->getEntityManager();
$studentEntity->setDefaultViewForm($form);
$studentEntity->setDefaultEditForm($form);
$entityManager->persist($studentEntity);
$entityManager->flush();

This documentation enables developers to leverage Concrete CMS for creating Express Objects and managing relational data programmatically, ideal for package development.

Express Entry Management: Creating, Reading, Searching, Updating, Deleting

Creating Express Entities

Prerequisite: Package Installation

To add Express Objects in install() method of a Package, follow instructions in the package creation documentation and Express Object Builder documentation. For instance, creating a student entity:

$student = Express::buildObject('student', 'students', 'Student');
$student->addAttribute('text', 'First Name', 'student_first_name');
$student->addAttribute('text', 'Last Name', 'student_last_name');
$student->addAttribute('textarea', 'Bio', 'student_bio');
$student->addAttribute('address', 'Address', 'student_contact_address');
$student->save();

Using the Express Entry Builder

Import Express facade in your package's controller.php, then use the Concrete\Core\Express\EntryBuilder in the install() method:

use Express;

// Within install() method
$address = new \Concrete\Core\Entity\Attribute\Value\Value\AddressValue();
$address->setAddress1('123 SW Test');
$address->setCity('Portland');
$address->setStateProvince('OR');
$address->setPostalCode('97200');

$entry = Express::buildEntry('student')
    ->setStudentFirstName('Andrew')
    ->setStudentLastName('Embler')
    ->setStudentContactAddress($address)
    ->save();

Adding Associations

Create Teacher object and associate with Student entries:

$teacher = Express::buildObject('teacher', 'teachers', 'Teacher');
$teacher->addAttribute('text', 'First Name', 'teacher_first_name');
$teacher->addAttribute('text', 'Last Name', 'teacher_last_name');
$teacher = $teacher->save();

// Create student entries
$student1 = Express::buildEntry('student')
    ->setStudentFirstName('Andrew')
    ->setStudentLastName('Embler')
    ->save();
$student2 = Express::buildEntry('student')
    ->setStudentFirstName('Jane')
    ->setStudentLastName('Doe')
    ->save();
$teacher = Express::buildEntry('teacher')
    ->setTeacherFirstName('Albert')
    ->setTeacherLastName('Einstein')
    ->save();

// Associate entries
$teacher->associateEntries()->setStudents([$student1, $student2]);

Reading Express Entry Data

Retrieve attribute data:

print $entry->getTeacherFirstName();
$value = $entry->getAttributeValueObject('teacher_first_name');

Retrieve associated entries:

$students = $teacher->getStudents();
foreach($students as $student) {
    print $student->getStudentFirstName();
}

$teacher = $student->getTeacher();
print $teacher->getTeacherFirstName();

Retrieving Entry Lists

Listing Entries

Retrieve student Express object, then list entries:

$entity = Express::getObjectByHandle('student');
$list = new Concrete\Core\Express\EntryList($entity);
$students = $list->getResults();
Filtering Lists

Filter by attribute:

$list->filterByStudentFirstName('Andrew');
$results = $list->getResults();

Filter by association:

$entity = Express::getObjectByHandle('medium');
$list = new EntryList($entity);
$languageEntry = Express::getEntry(10);
$association = $entity->getAssociation('medium_language');
$list->filterByAssociatedEntry($association, $languageEntry);
$entries = $list->getResults();

Retrieving an Entry by ID

Retrieve an entry and its attributes:

$student = Express::getEntry(1);
print $student->getFirstName();
$teacher = $student->getTeacher();
print $teacher->getTeacherFirstName();

Sorting Entry Lists

Sort using attribute names:

$list = new Concrete\Core\Express\EntryList($entity);
$list->sortByStudentFirstName('desc');
$result = $list->getResults();

Updating Entries

Modify and refresh entry attributes:

$student = Express::getEntry(1);
$student->setStudentFirstName('Andy');
$student->setAttribute("student_first_name", "Andy");
$student = Express::refresh($student);
print $student->getStudentFirstName();

Update associations:

$student->associateEntries()->setTeacher(null);

Deleting Entries

Delete an Express entry:

Express::deleteEntry($student->getID());

This procedure ensures the removal of all attribute values and associations.