Facilitates WordPress plugin and theme development.
Description
One of the time-consuming part of developing WordPress plugins and themes is creating setting pages. As you more and more write plugins and themes, you’ll soon realize major part of code can be reused. Admin Page Framework aims to provide reusable code that eliminates the necessity of writing repeated code over and over again.
Admin Page Framework provides plugin and theme developers with easier means of building option pages. Extend the library class and pass your arrays that define the form elements to the predefined class methods. The library handles all the complex coding behind the scene and creates the pages and the forms for you.
Features
- Top-level Page, Sub Pages, and In-page Tabs – where your users will access to operate your plugin or theme.
- Forms – to let your users store their options.
- Custom Post Types – and the custom columns in the post listing table.
- Custom Taxonomies and Fields – to store options associated with a taxonomy in the taxonomy definition page.
- Meta Boxes and Fields – which help to store meta data associated with posts of set post types. Also meta boxes can be added to the pages created with the framework.
- Widgets and Fields – to display modular outputs based on the user’s settings in the front end.
- Network Admin Pages and Forms – for WordPress multi-sites.
- Contact Form – receive emails of user feedback and issue reports sent via the contact form embedded in an admin page.
- Extensible – the created admin pages will become highly extensible with the automatically created hooks. In other words, it empowers other developers to customize your plugin or theme. That will result on making your projects grow.
- Section Tabs – form sections can be displayed in a tabbed box.
- Collapsible Sections – form sections can be collapsed and expanded.
- Repeatable Sections and Fields – dynamically add/remove form sections and fields.
- Sortable Fields – drag and drop fields to change the order.
- Import and Export Options – buttons that the user can import and export settings by uploading and downloading text files.
- Reset Button – lets the user to initialize the saved options.
- Validation and Error Messages – with the pre-defined validation callbacks, the user’s submitting form data can be verified. Furthermore, by setting the error array, you can display the error message to the user.
- Contextual Help Pane – help contents can be added to the contextual help pane that appears at the top right of each screen.
- Custom Field Types – your own field type can be registered. This allows you to design own fields such as a combination of a checkbox with a text field.
- Portable – use the framework as a library and include the minified version and your plugin or theme does not require an extra plugin to be installed. Therefore, your product will be perfectly portable.
Built-in Field Types
text– a normal field to enter text input.password– a masked text input field.textarea– a text input field with multiple lines. It supports TinyMCE rich text editor.radio– a set of radio buttons that lets the user pick an option.checkbox– a check box that lets the user enable/disable an item.select– a drop-down list that lest the user pick one or more item(s) from a list.hidden– a hidden field that will be useful to insert invisible values.file– a file uploader that lets the user upload files.image– a custom text field with the image uploader script that lets the user set an image URL.media– a custom text field with the media uploader script that lets the user set a file URL.color– a custom text field with the color picker script.submit– a submit button that lets the user send the form.export– a custom submit field that lets the user export the stored data.import– a custom combination field of the file and the submit fields that let the user import data.posttype– a set of check-lists of taxonomies enabled on the site in a tabbed box.taxonomy– check-lists of taxonomies enabled on the site in a tabbed box.size– a combination field of the text and the select fields that let the user set sizes with a selectable unit.section_title– a text field type that will be placed in the section title so that it lets the user set the section title.system– displays the site system information.
Bundled Custom Field Types
With custom field types, you can create more detailed customized field outputs. The demo component includes the following example custom field types.
ace– a rich code editor.sample– a sample custom field type with a JavaScript script.github– displays GitHub buttons.
If you want a field type that are not listed here, you can check the field type pack or request a new one in the forum.
Getting Started
Go to Dashboard -> Admin Page Framework -> About -> Getting Started.
Demo
Activate the demo pages to see the possible features of the framework. To activate it, go to Dashboard -> Admin Page Framework -> Add Ons -> Demo.
Necessary Files
admin-page-framework.min.phpis in the library folder. Or you can get it from Dashboard -> Admin Page Framework -> Tool -> Minifier.- Alternatively you may use
admin-page-framework.phplocated in the development folder. In that case, all the class files in the sub-folders need to be copied.
Documentation
Hi again again Michael!
So I’ve got my Custom Post Type and a Custom Taxonomy pretty much up and running, and I’ve come up with two more questions — or maybe we’ll call them two observations.
1. Weird cursor behaviour around pre-populated textareas and text fields.
I don’t know if it’s just my setup, but I’ve found that after setting a value in a textarea field and then saving it, that it becomes very hard to modify. In my browser, once I have a pre-populated textarea selected, I can use the ‘Home’ or ‘End’ buttons on my keyboard to move the cursor about, but selecting the middle of the text with my mouse is impossible.
I’ve given it a try as well saving some stuff in the textarea of an APF Post (in your Admin Page Framework Demo) and then trying to click the field after saving it, but no dice. It’s just impossible to select text or move the cursor around with the mouse — same as in my Custom Post.
Incidentally, everything works fine in Chrome, but this problem I’m experiencing happens in Firefox or IE.
Found this after a bit of quick Googling (https://support.mozilla.org/en-US/questions/1003547), and it pretty well sums up my problem, but without any resolution.
Wonder if you knew about this, and, if so, why this is happening?
2. Is it possible to preserve unsaved values if a form doesn’t validate?
My Custom Post Type has about ten fields, and four of them are validated for errors (essentially, they can’t be left empty). But if I fill nine of them out and accidentally leave one of the validated fields empty, the options are not saved, and all the fields are all erased.
Pressing the back button in the browser gets back all of the values in the fields, but that’s obviously a hack.
Just wondering if I was missing out on something obvious, like if there’s a way around this? I mean, obviously the validation method can send the (unsaved) values back in an error message, so conceivably they could be re-entered into the fields they were in before.
I was playing around with it, but in the end I didn’t really get anywhere.
Any advice about this?
Hi Paul, sorry for the delay in response. For some reasons, I did not receive an email from the site for a new comment being posted. (I have to figure it out.)
For the first problem, there is a similar issue having been reported (https://github.com/michaeluno/admin-page-framework/issues/101) and I cannot confirm it in my environment unfortunately. I’ve tried it in FireFox and IE and don’t see it. I’ll keep it in mind though. If you are certain that it can be reproduced, reopen the issue on Github or create a new issue about it and let me know the way to reproduce it. Once I could reproduce it, it is likely to be fixed.
As for the second problem, that is something I’ve been wondering too. One way to work around it is to return the input array from the validation callback method, except the fields having an error. The validation callback methods receives three parameters. The first one is the user input array. The seconds one is the stored data. The third one is the admin page class object. You want to modify the first input array and drop the invalid fields and then return it.
The problem with the workaround though is that the framework will save those returned values, which means even if the user cancels the form submission after getting the validation errors, the returned values will remain. If you are suppressing the options array, it would not be the problem.
If you need an example, let me know.
Hey Michael,
Saving values and retrieving values has ceased to be a problem for me, but I’ve spent some time today with the first problem I mentioned — the unselectable text in textareas and input fields — and I’ve made no progress on it. I thought the problem might be related to CSS rules, but after mucking around with them for some time, I no longer think so.
What’s stranger is I seem to be getting inconsistent results across the three browsers that I used.
In Chrome, I can select text both with the mouse and with keyboard shortcuts (ctrl+a, for example). Chrome works perfectly.
In Firefox, I cannot select text with the mouse, but keyboard shortcuts are working.
With IE, neither the mouse nor the keyboard shortcuts are working.
With IE, it is still possible to modify the value in textareas using the arrow keys, keyboard characters, and the delete/backspace buttons, but even after modifying the field value, selecting text proves impossible.
This may be a bit unorthodox, but if I granted you access to our admin WordPress backend, do you think you could go in and check it out? I could do up a sample Post (where selecting text works), and then a sample CP made with APF in where I’ve been having problems. Should only take a few seconds to confirm if a problem exists or not.
If not, then I’m just going to recommend switching browsers because I’m totally mystified.
Paul
Hi Paul,
I’ve responded to the GitHub post.
Hey again Michael,
Was gonna reply to my original comment about six weeks ago, but figured my question being different this time around deserved a new thread. So here goes.
I’m trying to define a Custom Post type through the framework (“Jobs”, if it makes a difference) and I’ve hit a road bump. Basically, I was trying to get a quick and dirty version up (modeled explicitly after your ‘APF Post’ type), and though it seems to be working in the backend, I can’t get it to display on the public-facing side.
I’ve basically copied over your APF_PostType.php file and modified it a bit, and then ripped out lines 29-58 from your admin-page-framework-demo.php to try and get a new Post type showing up on the public facing site (both single posts and as an archive or them). Unfortunately, they don’t appear anywhere on the public site: I am either getting 404 errors or being redirected to my home page.
I was wondering what I have forgotten to do (or perhaps included accidentally). With the Demo Admin Page Framework plugin activated, mysite.com/apf_posts shows up just fine, but I’ve been going through the source code and it’s not obvious to me why my Post type isn’t there. Do I need to define a template somewhere in WordPress, or make some change to the rewrite rules? I’m also linking to your APF Demo plugin for Metaboxes and things right now, if that’s introducing a problem. I wouldn’t have thought so.
Relevant files are here, if you’re interested.
Adding my Custom Post Type to WordPress (lines 86-113): https://github.com/pcraig3/usc-jobs/blob/master/admin/class-usc-jobs-admin.php
Defining my Custom Post Type: https://github.com/pcraig3/usc-jobs/blob/master/admin/USCJob_PostType.php
Hi Paul,
You may want to make sure that the post type class is instantiated in the front end.
I’m talking about this line specifically.
new USCJob_PostType( 'usc_jobs' );In you case, the class named
USC_Jobs_Admininstantiates theUSCJob_PostTypeclass so make sureUSC_Jobs_Admindoes not have theif ( is_admin() ) { ... }check.Also you may try re-saving the WordPress permalink option by going to Dashboard -> Settings -> Permalinks and just press the Save Changes button.
Hope it helps!
Oh, duh. That was absolutely the problem.
Hey Michael,
So I’ve been tinkering with your plugin and generally quite impressed with it. It’s very powerful and seems like (once I spend a bit more time with it) it could greatly speed up the development time of a project I’m working on.
I’ve built myself a form and am trying to override the default functionality of the ‘submit’ button. Now, I’ve looked through your code and it looks like I would want to extend the
AdminPageFramework_FieldType_submitbutton with my own, but I’m afraid I’m still unclear over what actually happens when the submit button is pressed.1. Both
AdminPageFramework_FieldType_submitandAdminPageFramework_FieldType_exportdefine a number of hidden fields with different attributes. (a) What are the hidden fields for?(b) Are these fields critical to the form’s submission? (In the case of the ‘reset’ button, for example, the reset isn’t performed without a confirmation, but I’m not exactly sure how it is prevented.)
2. My goal is to submit the values in the input fields into a custom database table (so not ‘wp_options’). The table exists and my insert/update methods are defined already.
(a) How can I re-define the submit behaviour of a form–do I change it by modifying/extending something at the level of the form or the button?
Hi Paul,
I’m glad you find the framework useful.
For the question
1-a, those hidden fields are used to provide additional functionality including determining which submit button is pressed in the page that receives the form data. As you have guessed, the ‘reset’ argument uses one of them and displays a field notice to the user by determining the pressed button.For
1-b, no. Even you can use the WordPress built-in function, submit_button(), only to display a submit button and it is still functional to send the form.For
2-a, I’d suggest using one of the pre-defined validation callback methods to store submitted data in your preferred location. To display the data stored in the custom location, pass the value to the ‘value’ argument.I’ve posted a sample plugin on Gist.
https://gist.github.com/michaeluno/fb4088b922b71710c7fb
Thanks a lot for the example! Found it really easy to modify after seeing that.
I’ve got my database insert working properly now, and can’t think of any serious problems on the horizon.
I was wondering two more things, but these are much simpler questions–no need to write up an example for either of them. Just a quick answer will suffice.
Is it possible to customize the messages received after submitting the page? I’ve seen a few elements in your demos given
$this->oMsg(''use_this_image'')settings (use_this_imagebeing one example, just) but the string within the paratheses is always a constant defined inAdminPageFramework_Message. Could I just swap in my own message, or do all messages have to be defined the APF_Message class before they can be used?Secondly, doing a custom database insert during the validate hook seems to work pretty well, but my
wp_optionstable is still updated. It’s not the end of the world if I can’t suppress it, but I was wondering if there was an easy way to get rid of theupdate_optioncall on form submit.Again, I’m really just asking for brief answers; I’m sure you’re busy and I already troubled you yesterday.
Use the
setSettingNotice()method in the validation callback method before returning. Omit the second parameter for errors.To modify the message object, do it like this,
At the moment, it is not possible but can you post a feature request on GitHub? It shouldn’t be hard to implement.
This became possible in v3.4.1. It took a little while to implement but thanks for having brought it up to my attention about this.
Hi Michael,
Sorry for my english that’s not very fluent.
I found your plugin in github here : https://github.com/wp-plugins/admin-page-framework
I create a fork of the git repository to improve the plugin. My fork and modifications are here :
https://github.com/lolozere/admin-page-framework/commits/master
In comments, you can see what I improved. If you want, I could create a pull request to apply my commits in your repository. All my code use @since 2.1.7.2, your next version number.
Dont’t hesitate, contact me to discuss about I can contribute with same code rules.
Best regards,
Laurent
Hi Laurent,
I appreciate you took the opportunity to improve the library.
A few notes:
– You forked on the wrong repository (the wordpress.org mirror). Here is the original: https://github.com/michaeluno/admin-page-framework Please check the addressed issues there.
– If you like to suggest a change, let’s post an issue first. That way, you won’t waste your time writing code that won’t be implemented.
The next version number will probably be 3.0.0 unless a critical bug is found in the current version.
Also you might also want to check the latest development branch 3.0.0b, which has significant changes in many aspects. The branch can be found in the referred repository.
Hi Michael,
I like this plugin but I have 2 things I don’t understand
1. Say I create a text field with id company-info, then I want to put that info in the footer.php, how do I call it? I’ve tried get_option(‘company-info’) to no avail.
2. Is there a way to keep the settings when I migrate my site from localhost to the live area without having to do the extra step of export/import?
Great work though.
Thanks
Naz
Hi,
For #1, I posted an example at Gist https://gist.github.com/michaeluno/6238133.
For #2, if you migrate the database, you won’t need to export or import the settings. The framework saves the form data in the option table with the key of your choice or the used page slugs. I’m not sure why you are asking this. 🙄
Hi Michael,
Thank you for getting back to me.
I had a look at the demo, but does this mean that every time I want to call back some info I have write a function, or or do [page slug][id][content]? In the demo it seems an awful lot of work to just get the company url.
Re:2 I tried to migrate a theme from one PC to another as a test after creating a few text fields/areas and populating with data, but the values I had added to the setting page did not appear, it reverted to the defaults I had set, and any images I set also disappeared. Export and import worked though.
I have no idea how your plugin works, far too advanced for me, but many plugins like this serialise the data so when you migrate it no longer returns the info you entered. I liked the plugin Option Framework but that suffers this issue.
Thanks
Nazim
It depends on where you get the information from. If it is saved in the option table, you would need to use the
get_option()function and specify the proper key if it’s an array. In the next major version update though, the stored properties are more organized; thus it will be much easier to do this.How did you migrate the theme? If the database including the option table is migrated, you should not have lost the data.
Admin Page Framework is rather a library than a plugin. It is for developers to create a theme or a plugin. It creates the form with the defined arrays and will store the data in the option table as serialized array. So if you migrate the database, the entered information should not be lost.
Hi Michael,
I migrate it by going to phpMyAdmin and then exporting the SQL database, then I open it in a text editor and change the url to reflect the new location, then change the config file, and move over the files. Then finally import the SQL file.
I have checked the database and the options table, and it does retain the data that I entered but the options/settings page does not reflect that.
When do you think the update version will be out? It would be so awesome if this framework had a few tweaks to make it easier to construct custom options pages and call the data.
Thanks
Nazim
Something must be done in the wrong way then. I tested it myself and the settings of the page created by the framework were successfully migrated as well.
I suggest you do it with a very simple one. Try with the demo plugin I posted in the previous reply. It saves the submitted form data in the options table with the option name, apf_footer_link. Fill the form and make sure that the values are reflected when you reload the demo plugin’s setting page. Then migrate the site.
After moving the site including the database and the demo plugin, the values submitted at the old site should appear in the demo plugin’s setting page. If they don’t, it is a problem and you should submit a bug report. I get a feeling that you are doing it in the wrong way though.
Also check the database if the options table has a key named, apf_footer_link, and its contents should look like the following:
It’s already out at github. Just I haven’t found the time to write the documentation. Currently it has the version, 1.1.0, but it will be changed to 2.0.0 as it has so many breaking changes.
I believe the framework already provides easier means of constructing custom option pages and calling the data. Adding an easier means of inserting extra information into the admin footer on top of the current functionality does not mean it doesn’t.
Constructive discussions that involve suggesting better ideas are always welcome though.
Hi Michael,
I tried the it with the footer demo and it did retain the settings this time, so it must be to do with the code I was using, which is just a modified demo plugin that came with the framework, i’ll have to see if I can spot what’s wrong.
“I believe the framework already provides easier means of constructing custom option pages and calling the data”
I guess “easy” is a subjective word, and what I really mean is easy enough for me to do, other admin page plugins I used have the ability to just call a field using get_optios(‘id’), I am a bit of a novice at PHP, I still can’t call any data 3 days in lol.
The only suggestion I have is to add a colour wheel so hex colour values can be selected, and maybe a special field for inserting code like Google Analytics unless it’s already OK with that.
But what would really make this plugin different from others is if you had a wizard that help to create the custom page, so when you install the framework in WP there is a screen for creating your own custom page which then get saved and work with that theme. Then you can can edit a line in a framework file and it will no longer display the wizard page in the admin area, this may of course be outside the scope of what you are trying to do.
Thanks
Nazim
Adding a color picker field is in the to-do list. Thanks. I’m not sure about a special field for custom JavaScript scripts. I would leave it to the framework users.
Ha, interesting idea! Thanks for the suggestion.
Thanks for this Plugin. During testing it took me some time to find out why I can move my Option Submenu Pages to eveywhere else but not to “Appearance” (themes.php).
you should change ‘appearence’ => ‘themes.php’,
to ‘appearance’ => ‘themes.php’,
Ah, that’s a simple mistake! Terribly sorry for making you have spent extra time for the debug. Thank you for reporting it!