Clarification on field usage and output location

[trancallan]

Hi, I’m trying to understand how to properly use fields in the system. I’ve read the documentation, but I’m still unsure about:

• How fields are added
• Where they should be defined
• What their intended usage is
  Are fields meant to be used in the admin panel, within pages, or elsewhere?
  Also, I came across the following method:

$files->getFiles(): Formwork\Files\FileCollection

It seems to return a list of files associated with the field, but I’m not sure where this list is actually displayed or how it’s meant to be used in practice.
Any clarification or examples would be greatly appreciated!
Thanks in advance.

[sgirard84]

Fields are used in schemes. A scheme is the structure definition of an element.. like a page.

https://getformwork.org/documentation/page-schemes/

In the website shipped with the default installation, there is a blog. You can see how a blog post is defined. See file:

site\schemes\pages\post.yaml

This is the structure. You can see fields like published date, tags, etc. This scheme is also extended from page scheme. So the admin UI will use both schemes to build dynamically the form in which you'll be editing the blog post entry in the admin.

Then, for the front end (public website), you can see how this scheme (and fields) are used in the blog post template file here:
site\templates\post.php

This is basic info, but start by looking at these files.

[giuscris]

Thank you @trancallan for reporting this, it's actually undocumented.
I think I'll add somewhere in the documentation the information I'm giving you there.

Basically the method getFiles in the file/files field is used to retrieve the options shown in the panel, from which you can choose a file.
By default the files are selected from the model attached to the field, i.e. the page in this case.

You can override this default by specifying the dynamic field property options@, providing another FileCollection.

This is the same with the image fields (in this case we have a getImages method, which returns a FileCollection containing images), just because is already used in the default site shipped with Formwork (in the Post template).

Let's say you want to allow only png images as cover images within the post.yaml scheme, for pages with the Post template.
Then in the scheme you should customize the options property with this syntax:

title: Blog Post

# ...

fields:
    # ...

    coverImage:
        type: image
        label: '{{page.image}}'
        options@: page.images.filterBy('extension', 'png')

    # ...

Basically with the syntax page.images.filterBy('extension', 'png') you're telling Formwork to filter the page images collection to include only files with the png extension.

Then in the panel, if you upload images of different types to the page, you'll find only the pngs in the Cover image field.

In a similar fashion, you could tell Formwork to take images from the site/files/ folder, which can be accessed from the the Formwork\Cms\Site::files() method (you can upload them in the site from the Upload files"button in "panel/files" by selecting Site as parent. In this case the dynamic field property becomes: site.files.filterBy('type', 'image').

[trancallan]

These days I’ve been a bit busy, but I’ve already started using Formwork.

@giuscris, @sgirard84 Thank you for your help in understanding how fields work, but it’s still something I can’t quite grasp at the moment. I find it difficult to add them to the schemes and make them work in the templates—I only get 500 errors. I’ll keep trying. In the end, I don’t think I’ll be able to understand it 🙂.

I have completed the translation of everything into Galician, which is my language alongside Spanish.

Formwork is a powerful but user-friendly CMS. The only features I find lacking are a more advanced Markdown editor and native folder support in the file manager. This is manageable until you accumulate many images across different years. For me, at the moment, a practical solution is to include the year in the file name.

My current question is how to insert icons into text—for instance, a 📂 or a .pdf icon. Is Unicode the only option?

[giuscris]

Thanks for the update, @trancallan

About the 500 errors when adding fields: if you can share the error message you get with debug mode enabled, I can help figure out what's going on. Most of the time it’s just a small YAML detail.

About files, Formwork is designed so that files usually live inside each page's folder, since they normally belong to that page. The site/files folder exists, but it's not really meant to store everything there.

For icons inside text, there isn't a built-in feature because it depends a lot on the project. You can use Unicode emojis, enable HTML in Markdown and insert them in the markup, or insert placeholders in the content and replace them in the template, whatever works best for your setup.

If you want, share an example of what you're trying to do and I can point you in the right direction.

And by the way, if you’d like to contribute the Galician translation, I'd be really happy to have it in the project.