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:
JCF supports fields of such types:
Input text | Usual single-line text box |
Select | Usual dropdown list |
Select Multiple | Area which allows you to select multiple options from the list |
Checkbox | You can add one or multiple checkboxes |
Textarea | Multi-line text field. You can also enable WordPress editor for this field |
Datepicker | Input field with calendar popup to choose a date |
Simple media | Use this field to create image or file container |
Collection | With 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 Content | Using this field allows you to link other post types with your post |
Once saved field will appear on the post type edit form.
Installation
- Download, unzip and upload to your WordPress plugins directory
- Activate the plugin within your WordPress Administration Backend
- Go to Settings > Just Custom Fields
- Choose Post Type (Standard/Custom) where you would like to edit custom fields
- Create Fieldset
- 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:
Title | Field name |
Description | Field 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. |
Enabled | Enable/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.
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:
Database | Settings are stored in the database in the wp_options table or in the wp_site_options table. |
File system: current theme | Settings 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: global | Settings 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.
Pingback: Creating components: Page additional menu – Just Custom Fields()