Documentation

Just Custom Fields

Getting started

What is JCF?

Just Custom Fields is a WordPress plugin which can add new fields to the standard sections Posts and Pages and to the Custom Post Types. All data is saved similar to the standard WordPress Custom Fields box and can be accessible on the frontend with the same functions as WordPress Custom Fields.

After installation, you can create fields from WordPress Dashboard with a simple user interface:

jcf1_settings-640x351 What is JCF?

JCF supports fields of such types:

Input textUsual single-line text box
SelectUsual dropdown list
Select MultipleArea which allows you to select multiple options from the list
CheckboxYou can add one or multiple checkboxes
TextareaMulti-line text field. You can also enable WordPress editor for this field
DatepickerInput field with calendar popup to choose a date
Simple mediaUse this field to create image or file container
CollectionWith this field you can create repeatable groups of fields. You can add other fields to this collection. (For example, you can create your own Gallery, by adding Simple media for image, Input Text for Title, and Textarea for description).
Related ContentUsing this field allows you to link other post types with your post

Once saved field will appear on the post type edit form.

jcf2_post_edit-640x424 What is JCF?

Installation

  1. Download, unzip and upload to your WordPress plugins directory
  2. Activate the plugin within your WordPress Administration Backend
  3. Go to Settings > Just Custom Fields
  4. Choose Post Type (Standard/Custom) where you would like to edit custom fields
  5. Create Fieldset
  6. Add fields to the fieldset.

Field settings and Post page

To edit field settings, go to Settings > Just Custom Fields, and then choose the Post Type you want to modify.

Fieldsets

On this screen, you can create Fieldsets: logical fields’ grouping that appears as separate meta boxes on Post Type edit page. You can drag fieldsets to sort them.
If you remove Fieldset with fields, the data saved from Post pages won’t be removed and will be kept in the database. (So the site will keep its work)

Fields

Within each group, you can add fields. Each field always has such fields:

TitleField name
DescriptionField description, it appears under the field below
Slug

A machine name – by which you can get a value through the WordPress functions.

By default, the underlining is added at the beginning of all fields, (for example, “_title”).

This is made to hide this field from the standard Custom Fields meta box, otherwise the user can accidentally change the complex field value (for example, simple media), thereby entering the incorrect value in the database that will cause the error reading this field value.

EnabledEnable/disable the display of a field in the edit form

Collections

Collection is a special type of field. On the one hand, it is the same field as while creating. But on the other hand, you can add inside it the other fields, thus creating a group of repeatable items. For example, a slider set with an image and description of some special fields.

You can’t add the Collection inside it (i.e. you may not put the Collection into the Collection).

While adding fields into the Collection, the additional fields appear:

Use this field as collection item title
Using this checkbox, you can specify that the Text field can be used as a title in the interface (to make much easier to navigate through it). It is displayed on the Edit Section page after the post has been saved.

Field Width
Within one group, you can set preinstalled options of the obtained width. This makes it possible to place the items more beautiful and to reduce greatly the visible area of the group, making its editing more convenient.

Fieldset Settings

When you edit the Fieldset, several additional settings will appear, that are missing while creating:

Position – to place a meta box in the central or side panel. Options correspond to the settings available in WordPress. By default, the fieldset is placed in the central column.

Priority – to specify a priority for your field group. It influences the order in which all meta boxes are displayed on the edit form.

Visibility rules – to hide/show a fieldset depending on the chosen taxonomy or the page template.

You can set several Visibility rules. They are grouped consistently by operators AND/OR, i.e. first the result of first two rules is calculated, then this result combines with the third rule. It looks in the program code as follows:

( ( (rule1 AND rule2) OR rule3) OR rule4 ) ….

* AND/OR are arbitrary set for an example. They are chosen separately for each rule within creation.

Display setting (Hide/Show option) works inversely.
If you selected Hide if {condition}, it means that the block is ALWAYS displayed, until the condition is fulfilled.
If you selected Show if {condition}, it means that the block is ALWAYS hidden, until the condition is fulfilled.

Frontend fields usage

JCF has built-in shortcodes to print fields and also support standard WordPress Post meta functions for skilled WordPress developers.

Built-in JCF opportunities

On the page editing entity (Post Type), each field has a question icon – it shows how it can be used to display the information on the frontend. For less experienced users this method helps to display easily the necessary information.

There are 2 variants for output of information in JCF:

Shortcode

This is a special code that can be inserted in the main editor:
[ jcf-value param1="value" param2="value" ]

These codes are recognized by WordPress and call required functions for displaying content.
In the tooltip popup, the first example is a shortcode that can be copied and inserted in the main editor. If the field is filled in, its content will be displayed on the frontend.

jcf3_help_popup-640x274 Built-in JCF opportunities

The shortcode has the option to show/hide title (label=”yes”) and also an opportunity to add the own CSS class and to set the HTML ID attribute.

Template function

For convenience, the shortcodes are also used in the templates. In the tooltip popup, you can see the example how to call Shortcode in the template.

Unfortunately, because of overall requirements, all shortcodes add many unnecessary html for the opportunity of adding any styles for them.

Unfortunately you can’t use this method for the Taxonomy term fields (which were added in version 3.3). To print fields on a category or a tag you should use standard WordPress functions.

WordPress standard

For skilled WordPress developers we recommend to use native meta functions such as:

get_post_meta()
get_post_custom()
get_term_meta()

Let’s see some examples.
Imaging, that you created 3 custom fields for the Page with such slugs:

  • _price (Input Text)
  • _features (Checkboxes / multiple)
  • _author_avatar (Simple Media / image)

To get values in the templates you need to place the following lines of code inside the loop functions:

<?php $price = get_post_meta(get_the_ID(), '_price', true); // we get value from input text $avatar_id = get_post_meta(get_the_ID(), '_author_avatar', true); // we get image attachment ID $features = get_post_meta(get_the_ID(), '_features', true); // we get array of checked checkboxes ?>

Now when you have variables with the data, you can print them in the template like this:

Price: <?php echo $price; ?>
Features: <?php foreach($features as $feature) echo $feature . ', '; ?>
Avatar: <?php wp_get_attachment_image($avatar_id, ‘thumbnail’); ?>

As for the second example let’s see how to get field value for taxonomy term. For example we created one extra field “_headline” for the Post Category.

To get it’s value inside category.php template you should use the code below:

<?php $headline = get_term_meta(the_category_ID(false), '_headline', true); 

Plugin Settings

JCF has several additional tabs with settings under Settings > Just Custom Fields.

Settings

On this page, you can select how the fields configuration will be saved.

Settings storage

This option shows where the field settings will be recorded:

DatabaseSettings are stored in the database in the wp_options table or in the wp_site_options table.
File system: current themeSettings are stored in JSON format in the folder of the current activated theme. When you change the theme, the settings are loaded from the new theme (i.e. if you want save the earlier settings, you must copy a file in the file system or use export/import).
File system: globalSettings are stored in the wp-content folder and don’t depend on the active theme or other settings.

MultiSite Settings

In the MULTISITE mode, one more settings block is available for the Database option from Settings Storage.

This setting allows you to store different field settings for each sub-website separately. Or all fields will be identical on all sub-websites.

Import / Export

On this tab, you can import or export the fields’ settings.

Export

You can selectively export the fields’ settings and save the results in JSON format.

Import

For import you may use only JSON file generated by export of the same plugin version that is used for import. When importing, the selected fields are updated or added. The import doesn’t delete fields that don’t exist in the JSON file or if they were not selected in the interface. Therefore, if some fields are outdated or were deleted on the other site, you must manually repeat this action.

Field types

Input Text

Besides the already described standard settings, the field has no additional settings.

For editing a text field appears that is shown as it is on the frontend.

Textarea

It is a multi-line text field.
This field has the additional setting – to turn on/off the WordPress editor for this field.

If the editor is turned on, a value filtered by wpautop is output on the frontend (auto adding paragraphs and checking the validity of HTML tags).

Select

It is a field for selection of given items.

When you create a field, the fixed set of options is specified from which you can select while editing post. At this time you can configure options using the multi-line field where each line is a new answer option.

Select Multiple

It is a field for selection of given items where you can set many values.
The value variants are set also as for single Select.

Checkbox

It is another type of a multiple choice selection, but already using the checkbox item.
The value variants are set also as for Select.

Datepicker

It creates a text field with a dropdown list for selection of date. By default, a part of controls is hidden.

The settings enable you additionally to activate the display of month/year select.

It is output on the frontend in such format as you can see on the edit form. If you want to display another format on the frontend you can use such code example inside your template:

<?php
$date = get_post_meta(get_the_ID(), '_my_date_field', true);
if ($date) echo date('m/d/y', strtotime($date));
?>

This code use standard PHP date functions to convert date into another format. Please follow date() function documentation to learn more.

Simple Media

It is a field for uploading additional media files for a post.

It has a setting for selection of file type, for example, an image. If you select a variant with the image, a media library filters by image types, and a small Preview of the image appears for each file.

On the frontend a link to the file or for the Thumbnail image is shown.
For the image, you can add an option size=”medium” (or other registered size) in shortcode to change the size of the displayed image.

Collection

This field type was already described above. Collection is a special type of field. You can add inside it the other fields, thus creating a group of repeated items.

Multilingual support

Translations

User interface translations into different languages will be added into next releases of v3 (v3.0 doesn’t have them, however we will add them in the next release)

Multilingual plugins support

MultiSite Network

Multilingual sites are usually built with WordPress MultiSite Networks. Usually Multilingual Press plugin simplify editing of posts and managing translations in such method. Our plugin is compatible with MultiSite Networks and Multilingual Press plugin, because all data is saved into separate database tables and does not require any additional work to be done.

WPML

WPML is a very popular plugin for building multilingual sites (however you need to purchase a license to use it). We didn’t find any problems and conflicts with Just Custom Fields and they works perfectly together.

Hooks, Actions, Shortcodes

We added some hooks inside the code, using them you can extend the plugin.
* If you have any suggestions for additional hooks, please write us on Github.

Action: ‘jcf_register_fields
’

Using this hook, you can register your component to have a possibility to add a field of new type. It can be used not only in the theme, but also in the plugin. See the Extending JCF section for further details.

Filter: ‘jcf_localize_script_strings’

This filter is used before the transfer of text signatures to JavaScript for further translation. Thus, while adding the scripts and the need to display any messages and text signatures, you can also add new texts in the JavaScript code using this filter.

Shortcode: jcf-value

This is the main shortcode for output of the fields’ values. It has the following parameters:

  • id – (string) optional
    Html id attribute for main wrapper div element
  • class – (string) optional
    Additional css class to be added to the main wrapper div element
  • field – (string) required
    Field slug (machine name of some field) to output value from
  • post_id – (integer) optional
    Post ID to take value from. By default, it equals to the current post ID inside “The Loop”
  • label – (boolean: yes|no) optional
    Enable or disable output of the field label name.
  • size – (string) optional
    Parameter is available only for Simple Media field of type “Images”. Allows to change default image size “thumbnail” to the one specified in this parameter.

Usage examples:

[ jcf-value field=”_my_field” post_id=”123” id=”my_field” class=”my-field wide” label=”yes”]
[ jcf-value field=”_my_field2”]

Each field in admin interface has a help icon where you can find shortcode usage for specific field.

Extending JCF

You can register your own UI field components within a theme or plugin. To do this you will need to create a component class as child of \jcf\core\JustField and register it with jcf action.

You can read our case study article for more details and code samples: Creating WP Menus component.