# Flex Objects Plugin ## About The **Flex Objects** Plugin is for [Grav CMS](https://github.com/getgrav/grav). Flex objects is a powerful new plugin that allows you to build custom collections of objects, which can modified by CRUD operations via the admin plugin to easily manage large sets of data that don't make sense as simple YAML configuration files, or Grav pages. These objects are defined by blueprints written in YAML and they are rendered by a set of twig files. Additionally both objects and collections can be customized by PHP classes, which allows you to define complex behaviors and relationships between the objects. ![](assets/flex-objects-list.png) ![](assets/flex-objects-edit.png) ![](assets/flex-objects-options.png) ## System Requirements Plugin requires **Grav** v1.7.19 or later version in order to run. Additionally you need **Form Plugin** v5.1.0 and optionally **Admin Plugin** v1.10.19 or later version. ## Installation Typically a plugin should be installed via [GPM](http://learn.getgrav.org/advanced/grav-gpm) (Grav Package Manager): ``` $ bin/gpm install flex-objects ``` Alternatively it can be installed via the [Admin Plugin](http://learn.getgrav.org/admin-panel/plugins) ## Sample Data Once installed you can either create entries manually, or you can copy the sample data set: ```shell $ mkdir -p user/data/flex-objects $ cp user/plugins/flex-objects/data/flex-objects/contacts.json user/data/flex-objects/contacts.json ``` ## Configuration This plugin works out of the box, but provides several fields that make modifying and extending this plugin easier: ```yaml enabled: true built_in_css: true extra_admin_twig_path: 'theme://admin/templates' admin_list: per_page: 15 order: by: updated_timestamp dir: desc directories: - 'blueprints://flex-objects/contacts.yaml' - 'blueprints://flex-objects/pages.yaml' - 'blueprints://flex-objects/user-accounts.yaml' - 'blueprints://flex-objects/user-groups.yaml' ``` Simply edit the **Flex Objects** plugin options in the Admin plugin, or copy the `flex-objects.yaml` default file to your `user/config/plugins/` folder and edit the values there. Read below for more help on what these fields do and how they can help you modify the plugin. Most interesting configuration option is `directories`, which contains list or blueprint files which will define the flex types. ## Displaying ![](assets/flex-objects-site.png) just create a page called `flex-objects.md` or set the template of your existing page to `template: flex-objects`. This will use the `flex-objects.html.twig` file provided by the plugin. ```twig --- title: Directory flex: directory: contacts --- # Directory Example ``` If you do not specify `flex.directory` name in the page header, the page will list all directories instead of displaying entries from a single directory. ![](assets/flex-objects-directory.png) # Modifications This plugin is configured with a sample contacts directory with a few sample fields: * published * first_name * last_name * email * website * tags These are probably not the exact fields you might want, so you will probably want to change them. This is pretty simple to do with Flex Objects, you just need to change the **Blueprints** and the **Twig Templates**. This can be achieved simply enough by copying some current files and modifying them. Let's assume you simply want to add a new "Phone Number" field to the existing Data and remove the "Tags". These are the steps you would need to perform: 1. Copy the `blueprints/flex-objects/contacts.yaml` Blueprint file to another location, let's say `user/blueprints/flex-objects/`. The file can really be stored anywhere, but if you are using admin, it is best to keep the blueprint file where admin can automatically find it. !!! **NOTE:** If you want to put the blueprints to `user/themes/yourtheme/blueprints`, you need to use the new blueprint folder structure from Grav 1.7. See [Plugin/Theme Blueprints](https://learn.getgrav.org/17/advanced/grav-development/grav-17-upgrade-guide#plugin-theme-blueprints-blueprints-yaml). 2. Edit the `user/blueprints/flex-objects/contacts.yaml` like so: ```yaml title: Contacts description: Simple contact directory with tags. type: flex-objects config: admin: list: title: name fields: published: field: type: toggle label: Publ width: 8 last_name: link: edit first_name: link: edit email: phone: data: storage: class: 'Grav\Framework\Flex\Storage\SimpleStorage' options: formatter: class: 'Grav\Framework\File\Formatter\JsonFormatter' folder: user-data://flex-objects/contacts.json form: validation: loose fields: published: type: toggle label: Published highlight: 1 default: 1 options: 1: PLUGIN_ADMIN.YES 0: PLUGIN_ADMIN.NO validate: type: bool required: true last_name: type: text label: Last Name validate: required: true first_name: type: text label: First Name email: type: email label: Email Address validate: required: true website: type: url label: Website URL phone: type: text label: Phone Number ``` See how we replaced `tags:` with `phone:` in the `config.admin.list.fields` section at the top. Also, notice how we removed the `tags:` Blueprint field definition, and added a simple text field for `phone:`. If you have questions about available form fields, [check out the extensive documentation](https://learn.getgrav.org/forms/blueprints/fields-available) on the subject. 3. We need to copy the frontend Twig file and modify it to add the new "Phone" field. By default your theme already has its `templates`, so we can take advantage of it 2. We'll simply copy the `user/plugins/flex-objects/templates/flex/contacts/object/default.html.twig` file to `user/themes/quark/templates/flex/contacts/object/default.html.twig`. Notice, there is no reference to `admin/` here, this is site template, not an admin one. We are also assuming you are using `Quark` theme, so you may have to change this to reference the theme you are using. 4. Edit the `default.html.twig` file you just copied so it has these modifications: ```twig
{{ object.phone }}
{% endif %}