NewsPublisher Snippet Tutorial

I could tell you how many hours it takes to develop a MODX extra Transport Package complete with a build script, properties, multiple MODX elements, internationalized strings, error checks, and then fully test it, but you wouldn't believe me. If you use this extra and like it, please consider donating. The suggested donation for this extra is $20.00, but any amount you want to give is fine (really). For a one-time donation of $50.00 you can use all of my non-commercial extras with a clear conscience.


PayPal

NewsPublisher is a front-end resource creation and editing tool for MODX Revolution. It allows users to create new documents and edit existing documents in the front end of your site. Editing existing documents involves placing a tag for the NpEditThisButton snippet in your page template. Clicking on the button produced by the snippet launches NewsPublisher for that resource. You do not have to create *any* form fields. NewsPublisher creates them based on the field or TV type and its current or default value (if any).

Important: If you are upgrading from a version prior to NewsPublisher 3.0, be sure to see the Upgrade Notes at the bottom of this page.

(Jump to NewsPublisher System Settings Table.)

(Jump to NewsPublisher Snippet Properties Table.)

(Jump to npElFinderConnector Snippet Properties Table.)

(Jump to NpEditThisButton Snippet Properties Table.)

Acknowledgements

Special thanks are due to TinyMCE guru donshakespeare whose TinyMCEWrapper inspired much of the new version (3.0), and who helped solve some thorny problems with implementing the new file browser.

Markus Schlegel, who developed an earlier version of the NewsPublisher browser for files and images, the NewsPublisherEditor Policy and Policy Template, and who vastly improved the datepicker, was kind enough to step in and solve the many problems necessary to make the version 2.0 file browser work in MODX Version 2.3.

Installing NewsPublisher for MODX Revolution

Go to System | Package Management on the main menu in the MODX Manager and click on the "Download Extras" button. That will take you to the Revolution Repository. Put NewsPublisher in the search box and press Enter. Click on the "Download" button. When the download has finished, click on the "Back to Package Manager" button. That should bring you back to your Package Management grid. Click on the "Install" button next to NewsPublisher in the grid and follow the prompts. The NewsPublisher snippet should now be installed.

Using NewsPublisher

If you are used to using NewsPublisher in MODX Evolution, this version will take a little getting used to. Many of the properties are different, but you will have much more control over the content and style of your form. Each type of field has its own Tpl chunk (as does the form itself) and every individual field has a separate ID so they can be styled using CSS.

Setting up a basic form is very simple. Create a document called "NewsPublisher" in the Manager and put the following code in the Resource Content field:

[[!NewsPublisher]]

When you preview the document, you should see a basic resource editing form. If you fill it in and click on the "Submit" button, the resource should be created. The basic form shows several standard fields, but you can change that with the &show property. It should contain a comma-delimited list (no spaces) of the fields you would like to display in the form. It can include TV fields listed by name or by ID (shown in the Elements tree next to the TV's name). The fields will appear in the form in the order you list them in the property. You can create multiple NewsPublisher pages showing different sets of fields for different users.

The form is highly flexible and you can show any fields or TVs in any order. Some fields will require you to set certain properties. For example, if you have any rich text fields, you'll need to set the &initrte property. If you show any date fields, you'll need the &initdatepicker property. The &rtcontent and &rtsummary properties control whether those fields will have rich text editing. See the list below for more information on the available properties. If you'll be using the elFinder file/image browser, either for TinyMCE, or file, richtext, or image TVs, you'll need to set the &initfilebrowser property. The properties can be in any order. Here's an example:

    [[!NewsPublisher?
        &show=`pagetitle,description,pub_date,introtext,TV1,TV2`
        &initrte=`1`
        &initdatepicker=`1`
        &initfilebrowser=`1`
        &rtcontent=`1`
        &rtsummary=`1`
        &parentid=`12`
        &published=`1`
        &captions=`content:Enter Post,introtext:Summary,description:Give a brief description`
    ]]

 

The example above will show the fields in the &show property in the order they appear in that property. The new resource will be published and both the content and introtext (summary) fields will have rich text editing. The pub_date field will display a datepicker widget.

The captions field is optional, so try the form and see if the default captions will work for you. If not, add the &captions property. If your captions are long, you may have to adjust the CSS to keep them from wrapping.

Security

NewsPublisher responds to the MODX security permission system, so users can only create resources if they are logged in and have permission to do so. As the admin Super User, you'll have full rights (unless you've done something that takes them away) to create and edit any document in the front end. Other users, however, will have to be granted permission before they can do either and their ability to edit existing resources will depend on the resource group settings.

In addition, users (including you) will not be able to edit resources containing MODX tags without the NewsPublisher allow_modx_tags permission. As of NewsPublisher 1.3.0, this permission is included in the NewsPublisherEditor Policy but is unchecked by default. Turn it on if you want users to be able to insert MODX tags in their documents. Be sure to see the section below on dealing with MODX tags.

When you create Context Access ACL entries using the NewsPublisherEditor Policy, you may have to flush both permissions and sessions before the new Policy will show up in the list.

Be aware that if you upgrade or reinstall NewsPublisher, the allow_modx_tags permission may be unchecked during the process and any other permissions you changed may be reverted unless you have duplicated the NewsPublisherEditor Policy and are using the duplicate.

MODX Tags

Recent versions of MODX include the allow_tags_in_post System Setting (not to be confused with the allow_modx_tags permission mentioned above). This makes MODX front-end forms much more secure because any MODX tags are removed from the $_POST array when a form is submitted. Unfortunately, it kills the option to edit resources or TVs containing MODX tags in the front end unless the allow_tags_in_post System Setting is on (which poses significant security risks). As of NewsPublisher 2.0, there is a workaround for this. It's not ideal, but it works. MODX tags are now represented in NewsPublisher in the form {{ ... }} instead of [[ ... ]]. This allows users with the required permission to edit MODX tags in NewsPublisher without turning on the System Setting.

For security reasons, it's strongly recommended that you leave the MODX allow_tags_in_post System Setting at its default setting of 'No'. If you want users to be able to edit MODX tags in NewsPublisher, put a check next to the allow_modx_tags permission in the NewsPublisherEditor Policy and save the Policy. For any users who will be using NewsPublisher, create a Context Access ACL entry for their User Group with a Context of 'web' and NewsPublisherEditor for the Policy. That will give them the allow_modx_tags permission. As always, flush permissions and sessions on the Security menu after making any changes. Remember, when testing, that if you are a sudo user, you have all possible permissions, so the restriction won't affect you.

NewsPublisher users will see all MODX tags in this form: {{ ... }} and will need to use the curly braces for any new tags they enter. All MODX tags are allowed and nested tags work fine in all my tests. The tags will be converted to standard MODX tags when the Resource is saved. Important: Note that if there are any tags in the form [[ ... ]] in any field of the NewsPublisher form, MODX will remove them when the form is submitted.

The NewsPublisherEditor Policy is based on the NewsPublisherPolicyTemplate, which in turn is based on the Administrator Policy Template, but with the addition of the allow_modx_tags permission. Both the Policy and the Policy Template should be installed automatically when you install the NewsPublisher Package.

Login Redirect

As of Version 3.0, NewsPublisher checks for login status and redirects users to the Login page if they are not logged in. If you don't want this, you can set the &np_login_redirect System Setting to No. It is set to Yes by default.

If &np_login_redirect is set to YES, the np_login_id System Setting (in the newspublisher namespace) must be set to the ID of your login page. NewsPublisher will try to do this for you during the install, but if the alias of your login page is not login, you'll have to do it yourself. I you want to use a separate login page for NewsPublisher, use an &np_login_id property in the NewsPublisher snippet tag set to the ID of that page. That will override the System Setting.


If you are a sudo user and are previewing NewsPublisher from the Manager, the login checks and all permission checks will be bypassed. To test your permissions, you should logout all users (Manage -> Logout all Users on the Manager's top menu) and log in as a non-sudo user.


You no longer need to log users in to the mgr context, so you should remove mgr from the &contexts property of the NewsPublisher snippet tag and list only front-end contexts there.

Using the &redirectToPrior property in the Login snippet tag to redirect users back to the NewsPublisher page is not entirely reliable, since some browsers don't set the $_SERVER[HTTP_REFERER] variable properly. It's recommended instead to set the &loginResourceId property to the ID of the NewsPublisher page. If necessary, you can have a separate Login page for NewsPublisher. If you do this, be sure to use an &np_login_id property in the NewsPublisher snippet tag set to the ID of your NewsPublisher Login page.

Editing Existing Resources

To edit existing resources, simply place a tag for the NpEditThisButton snippet anywhere in the section of your template(s) or in the Resource Content field of a Resource. The button is positioned absolutely in the lower right section of the page. The &right property controls the distance from the right side of the page and the &bottom property controls the distance from the bottom. The default for these properties is `20%`. Like NewsPublisher, the button also responds to security permissions and is not shown on pages the user has no right to edit or save. It also does not show on the NewsPublisher page or the home page. If there are other pages where you would like to hide it, you can include a comma-delimited list of their IDs in the &noShow property of the NpEditThisButton snippet tag.

Because the button will be hidden until you get the permissions correct, it's recommended that you start with the button tag like this:

[[!NpEditThisButton? &debug=`1`]]

In debug mode, the button will always show, and if it would normally be hidden, the button itself will display a message explaining why it would not be shown.

With debug mode off, the button will show on any page that uses the template when the user has edit_document and save_document permissions in general, and save permission for the current resource (unless the page is excluded by the &noshow property.

When the ownpagesonly property is set, the button will show only on pages created by the current user (based on the resource's createdon field).

Altering the Form

You can make many changes to the look of the form using CSS rules for styling. You can find the CSS file at assets/components/newspublisher/css/newspublisher.css. Using CSS, you can change the text color, background color, size, and/or position of any field, though the control of richtext fields is limited. You can put fields side-by-side by using "display:inline;" for the appropriate field(s). If you plan to make changes, it's recommended that you make a copy of the CSS file, the assets/components/newspublisher/css directory and put the name of your new file in the &cssfile property.

If you feel you must, you can alter the Tpl chunks for any of the field types. Again, you should duplicate the existing chunk and put the name of your duplicate in the appropriate property. Be careful not to change the prefixes of any of the placeholders in the Tpl chunks, even if you specify a custom prefix for the form as a property. The prefixes will be altered automatically by the snippet. Note that there are both np. and npx. prefixes. The npx. prefixes are used internally by the snippet, the np. prefixes are usually in the value field of the element and will be set via placeholders.

NewsPublisher Tabs

As of NewsPublisher 1.4.1, you can show the Resource fields on separate tabs like in the Manager (thanks to Gregor Ċ ekoranja). The tabs and fields can be in any order and any field can go on any tab. You can have as many tabs as you want. The names of the tabs are arbitrary. Whatever names you use will be displayed in the tab menu on the form.

Set &usetabs=`1` in the NewsPublisher snippet tag and include a &tabs property in the following form:

&tabs=`{
    "Main" :    ["pagetitle","introtext","content"],
    "Dates" :   ["pub_date", "unpub_date"],
    "Publish" : ["publish"],
    "TVs" :     ["MyTv1","MyTv2"]
}`

Be very careful when entering the tabs. The whitespace is ignored (it could be all on one line), but the format is very particular. You will get an error message if the format is wrong. Here are some guidelines:

  • You must use double quotes
  • The tab names go on the left
  • The fields to show on each tab go on the right
  • The tab names and field names must be separated by a colon
  • All the field names must be in the &show property
  • Every tab name and field name must be enclosed in double quotes
  • The field list must be enclosed in square brackets
  • The Field names must be separated by commas (but no comma inside the brackets at the end of the list)
  • All the tab lines except the last one must end with a comma
  • The whole list must be surrounded by curly braces inside of back-ticks (`{ }`)

The Tab names are on the left and you can use any names you like and as many or as few tabs as you need. NewsPublisher will add a "Show All" button that will show all fields at once. If you include a field that is not in the &show property, you'll see an error message telling you that the tab field can't be found. If there is a field in the &show property that is not in your &tabs list, it will go on the "Other" tab (which will not be shown if all the fields are accounted for).

Duplicate Button

If the &duplicatebutton property is set to 1, a "Duplicate" button will be shown at the bottom of the NewsPublisher form. When the user clicks on the button, the page currently being edited will be duplicated and the user will be forwarded to the NewsPublisher page to edit the duplicate. Changes made to the original before duplication will be saved before it is duplicated.

Delete Button

If the &deletebutton property is set to 1, a "Delete" button will be shown at the bottom of the NewsPublisher form. When the user clicks on the button, the page currently being edited will be deleted. Children of the resource will be deleted as well. If the &confirmdelete property is set to 1 (this is the default), a dialog will pop up asking the user to confirm the decision and warning that children will be deleted. If the &confirmdelete property is set to 0, the resource (and any children) will be deleted immediately.

Plugins with NewsPublisher

NewsPublisher calls either the resource/create processor (for new docs) or the resource/update processor (for existing ones). Those processors fire the OnBeforeDocFormSave event just before saving the resource and the OnDocFormSave event just after a successful save of the resource.

You can attach plugins to either event to perform any extra processing you need. Any existing plugins attached to those events will also execute when the resource is saved.

The usual variables are available in the plugin ($id, $resource, and $mode). The $resource variable is a reference to the resource object itself, so you can check its fields and modify it at will. If the plugin is attached to OnDocFormSave, remember to save the Resource object again after making any changes to it.

Launch Notify

If the &shownotify property is set to 1, the "Launch Notify" option will be shown in the form. If it is selected, after the NewsPublisher form is successfully submitted, the user will be forwarded to the Notify form to send email notifying users of the new or updated page. There will also be radio buttons to allow the user to select a Notify Tpl chunk to use for the email.

In order for Notify to work properly, the user must have view_user permission in the front end and must have access these three pages in the front-end context:

  • Notify
  • NotifyPreview
  • NotifyStatus

Unless the user has the view_unpublished permission, the three pages must also be published, though they can be hidden from menus. If you are using tabs for the NewsPublisher display, you may have to select the "Show All" tab in order to see the "Launch Notify" section.

Configuring NewsPublisher

NewsPublisher has many options, but almost all of them are optional. You can see the list by editing the NewsPublisher snippet and clicking on the Properties tab. Unlock the default properties by clicking on the "Default Properties Locked" button. Then, click the little plus sign next to a property to see what it does. It is strongly recommended that you not change the default properties on the Properties tab of the snippet. Either put properties in the snippet tag to override them, or create a property set by clicking on the "Add Property Set" button and specify it in the snippet tag like this:

[[!NewsPublisher@PropertySetName]]

Common Properties

Here are some of the most commonly used properties — all are optional, but a few are necessary if other options are set:

&show — (string) Comma-separated list of fields to show.

Example: &show=`pagetitle,longtitle,pub_date,unpub_date,content,MyTv1,MyTv3`

&captions — (string) Comma-separated list of fieldnames:fieldcaptions. All standard resource fields are in all lowercase.

Example: &captions=`introtext:Summary,content:Enter Your Post`

&aliastitle — (0/1) Use this if you want an automatic alias for your resources (a hyphenated, lowercase version of the pagetitle).

&aliasprefix — (string) prefix for aliases, used only if alias is empty. Alias will be prefix + raw unix timestamp, unless &aliasdateformat is set.

&aliasdateformat — (string) Format for alias timestamp. If alias is empty and this is set, the alias will be the prefix (if any) + a formatted date/time. It's strongly recommended to include minutes and seconds in this to avoid duplicate aliases.

&initrte — (0/1) Use this if you will be showing any rich text fields.

&initfilebrowser — (0/1) Use this if you want the user to be able to browse for images or files.

&rtcontent — (0/1) Use this if you want richtext editing for the content field.

&rtsummary — (0/1) Use this if you want richtext editing for the summary field.

&initdatepicker — (0/1) This is required if you will be showing any date fields or TVs.

&parentid — (integer) ID of the parent for new pages; defaults to NewsPublisher page. If you want to force a particular parent, set this and don't include the parent field in the &show property. (For backward compatibility, &parent will also work.)

&parents — comma-separated list of possible parent IDs (must be IDs or Context Keys!) of parents for user to select from; Note: new_document_in_root permission may be necessary for new resources; default: empty. If &parentid is set, it will be selected in the list.

&duplicatebutton — (0/1) If set to 1, a "Duplicate" button will be placed at the bottom of the form.

&deletebutton — (0/1) If set to 1, a "Delete" button will be placed at the bottom of the form.

&confirmdelete — (0/1) If set to 1 (the default), a dialog will pop up asking the user to confirm the decision and warning that children will be deleted.

&templateid — (mixed) The name or ID of the template to be assigned to new docs. Can also be set to 'Parent' to assign the parent's template; default: default_template System Setting. To force a particular template, set this, and don't put the template field in the &show property. (For backward compatibility, &template will also work.)

&templates — comma-separated list of IDs (must be IDs!) of Templates for user to select from; default: empty. If &template is also set, it will be selected in the list.

Page Settings for New Documents

The next five properties control the standard page settings of the resource being created (whether you show them or not). They can each be set to `1`, `0`, `Parent`, or `System Default` (the default setting). If set to `Parent`, the settings of the resource's parent will be used (and the &parentid property must be set). If left unset, the MODX System Settings will be used for each one. Note that the published setting may be overridden if you show pub_date or unpub_date in the form and the user sets them.

&published_default
&hidemenu_default
&cacheable_default
&searchable_default
&richtext_default

Presets Property

You can preset values for new documents using the &presets property in the NewsPublisher snippet tag. This will work for most resource fields and TVs. The property must be in this form:

&presets=`content:Some default content,introtext:My preset introtext`

In each of the comma-separated pairs, the left side of the : is the lowercase name of the field or the name or ID of a TV. The right side of the : is the preset value you want in the field.

Important: To have a preset, a field must be in the &show property and must be spelled exactly the same way in both the &show property and the &presets property. In both cases, it must be the actual name of the database field (e.g., introtext, *not* summary, and *not* the value you use for a custom caption.

Tpl Properties

These are the properties you can use to tell NewsPublisher to use your custom Tpl chunk instead of the built-in one. Generally, the property is the name of the built-in chunk, minus the 'np' prefix:

  • &errortpl
  • &fielderrortpl
  • &outertpl
  • &datetpl
  • &booltpl
  • &listoutertpl
  • &listoptiontpl
  • &optionoutertpl
  • &optiontpl
  • &texttpl
  • &textareatpl
  • &inttpl
  • &filetpl
  • &imagetpl
  • &richtexttpl
  • &fielderrortpl
  • &tinymceinittpl
  • &elfinderinittpl

Less Common Properties

NewsPublisher Snippet

&stopOnBadTv — (0/1) Stop and print an error message if a TV in the &show property is not attached to the Template being used; if you set this to `0`, unattached TVs will be ignored and the form will display normally without them; default: `1`.

&allowedtags — HTML tags allowed in text fields; default: `<p><br><a><i><em><b><strong><pre><table><th><td><tr><img><span><div><h1><h2><h3><h4><h5><font><ul><ol><li><dl><dt><dd><object><blockquote><code>`.

&prefix — (string) a custom prefix to use for placeholders; default: `np`. This property is only necessary if the placeholders conflict with other placeholders on the page. Important: Do not include a dot in your custom prefix.

&cssfile — (string) Path to a custom CSS file. Set to `0` for no CSS file if you want to put the CSS in your site's master CSS file.

&groups — (string) A comma-separated list of resource groups to assign new pages to. Can also be set to `Parent` to use the parent's groups.

&tinyheight — (string) Height of the RTE window; defaults to 400px.

&tinyWidth — (string) Width of the RTE window; defaults to 95%.

&required — (string) Comma-separated list of required field names or TVs. Important: Do not set this for Checkbox, list, or radio TVs or for boolean (0/1) resource fields (like the five above).

&cancelid — (integer) ID of the page the user will be forwarded to on cancel. If you don't want a cancel button, just remove it from the npOuterTpl chunk.

&badwords — (string) Comma-separated list of words to be filtered from fields.

&listboxmax — (integer) maximum size of listboxes. Overflow will scroll; default: 8.

&readonly — (string) Comma-separated list of readonly fields. Does not work with listbox, checkbox, radio, or richtext fields. The id field is always readonly.

&intmaxlength — (integer) Max length for integer input fields; default: 10.

&textmaxlength — (integer) Max length for text input fields; default: 60.

&hoverhelp — (0/1) Show help when hovering over field caption (but not the field itself); default: `1`. The MODX help strings are shown for resource fields. For TVs, the TV description is shown.

&language — (string) language to use for form; defaults: (in order of application) cultureKey, manager_language, en.

&classkey — (string) Class key for new documents; only necessary if you have extended the resource object for a custom resource class or are editing Articles blog posts.

&usetabs — (0/1 - optional) If set, displays the fields on separate tabs.

&tabs — (JSON string - required if &usetabs is set) JSON string specifying which fields go on which tabs. Unlisted fields will go on the "Other" tab; See the example above.

&activetabs — (string - optional) If set, determines the tab shown when the form is loaded; if left out, all tabs are shown.

&shownotify — (0/1 - optional) If set, the "Launch Notify" option is set. If selected, Notify will be launched for the resource on successful submission; default: 0.

&notifychecked — (0/1 - optional) If is this option and &shownotify are set, the "Launch Notify" option will be checked by default; default: 0.

NpEditThisButton Snippet

&editHome — (0/1) Allow edit button to show on the home page; default: `0`.

Multiple NewsPublisher Pages

If you would like to have different NewsPublisher pages with different fields and settings, create a separate page for each one with a different snippet tag on each page. The NpEditThisButton, by default launches the page specified in its &np_id property. If you use the following snippet tag for the button, you can have it launch the appropriate NewsPublisher page by creating a TV for each page called NpId and setting the correct NewsPublisher page ID in it:

[[!NpEditThisButton? &np_id=`[[*NpId]]`

NewsPublisher and getResources

As of NewsPublisher 1.2.0, you can put the edit button tag in the getResources Tpl chunk and have an edit button for each resource retrieved using the &np_edit_id property. You can also hard-code a page with multiple NpEditThisButton tags. To use this technique with getResources, remove any NpEditThisButton tags from the page template and create a Tpl chunk something like this:

<div class="MyItem">
   [[+pagetitle]]
   [[+introtext]] . . . [[!NpEditThisButton? &np_edit_id=`[[+id]]`]]
</div>

This is handy if you'd like to present a list of resources that the user might want to edit with NewsPublisher.

NewsPublisher and Articles

As of version 1.4.0, NewsPublisher can be used to edit Articles blog posts in the front end. You can put the [[!NpEditThisButton]] tag in your blog post template and the Edit button will show up on the blog page. You will not be able to edit comments in NewsPublisher.

Important: If you will be using NewsPublisher for Articles, be sure to set all of the following properties in the NewsPublisher tag:

  • &parentid — The ID of the Articles container
  • &templateid — The ID of the blog post template
  • &classkey — `Article`
  • &hidemenu — `1`

Remember that all the resources you create with this NewsPublisher tag will be blog posts. If you want to also create regular resources, you'll need another NewsPublisher page with its own tag and you'll need to use a different &np_id value in the NpEditThisButton tag in the different templates so the button will redirect to the correct NewsPublisher page.

NewsPublisher should also work with other Custom Resource Classes as long as they are implemented properly, but I haven't had an opportunity to test it with anything but Articles.

Configuring elFinder

NewsPublisher 3.0 uses the elFinder Browser.

If you don't want users to see the file browser at all, uncheck the file_manager permission in the NewsPublisherEditor Policy (or whatever policy you have assigned for your NewsPublisher users).

If you do want to enable the file browser, you must also set the new &initfilebrowser property of the NewsPublisher snippet to Yes (in addition to checking the file_manager permission).

To configure the elFinder Browser, see the properties of the npElFinderConnector snippet. As always, you should create a property set if you want to change any of the default values to prevent them from being overwritten when you upgrade NewsPublisher. Most of the properties there are self-explanatory. In particular, you'll want to check the &disableCommands property. See the description of the property for a list of possible commands. To prevent users from accessing a specific feature, simply remove it from the list. The elFinder browser will automatically remove icons for commands that are disabled.

The &browserBasePath and &browserBaseURL properties of the npElfinderConnector snippet are set to the assets directory. You may want to change them, but be sure they match. Users will not be able to browse above them.

The &browserStartPath and &browserStartURL properties allow the browser to open in a lower directory. The two must match. Users will be able to browse above them, but only up to the &browserBasePath and &browserBaseURL directories.

There are also new System Settings in the newspublisher namespace that are used to configure elFinder: np_elfinder_remember_last_dir, np_elfinder_theme, np_elfinder_tmb_size, np_elfinder_height, and np_elfinder_width.

If np_elfinder_remember_last_dir is set to Yes (it's No by default), elFinder will open in the directory that was last accessed, though users can still browse above it up to the directory set in the &browserBasePath and &browserBaseURL properties of the npElfinderConnector snippet.

The np_elfinder_theme setting description lists the built-in themes, but you can add your own if you like. They go in the assets\components\newspublisher\elfinder\elfinderthemes directory. The only file loaded is elfinderthemes/theme name/css/theme.css, which sometimes uses other files in the same directory.

The default elFinder theme is osx, which I think is the most attractive. The other themes are not always reliable. The windows-10 theme, for example, hides the X that closes the window, though you can still click on the invisible X to close the window. You're welcome to fix problems you find with any of the themes and contribute them to future NewsPublisher releases. The moono theme seems to work well, but it you have to right-click on the images to see a preview. The themes may look slightly different in TinyMCE than they do for file and image TVs because TinyMCE controls the border and the title background.

The np_elfinder_tmb_size setting controls the size of the elFinder thumbnails. It's in pixels and the image is always square. The default is 48px. If you want to change that, you should do it before launching elFinder or uploading any images. If you forget, you can simply delete the existing thumbs. They are placed below each directory the images are in and are in a subdirectory named .tmb, unless you've changed the &tmbPath property of the npElFinderConnector snippet. You can use the elFinder thumbnails in your HTML code, but since their names are hashed, it's a pain, and it's not very well documented. I recommend using phpThumb or one of its replacements (e.g., phpThumbOf, or pThumb) for thumbnails.

The np_elfinder_height, and np_elfinder_width settings are expressed as percentages of the screen height and width. The default is 80 for both. Use a whole number. Do not include the percent sign.

You can also edit the code of the npelFinderInitTpl chunk to alter elFinder in more advanced ways, though typically, the supplied properties should do most of what you want. Get elFinder working first. To modify it, create a duplicate chunk and specify its name in the &elfinderinittpl property of the NewsPublisher snippet tag.

One use-case for modifying elFinder would be allowing users to browse in and under more than one directory (i.e., multiple roots). This requires modifying the npElFinderConnector snippet code. If you do this, duplicate the snippet and modify the tag on the npElFinderConnector Resource to point to your duplicate. See the docs here for an example. Note that this will not apply to any TVs. For TVs, the user's browsing will always be limited to the baseURL/basePath of each TV's Media Source. One great feature of elFinder using multiple roots is that the user can have different capabilities in each root. You might, for example, have one directory where users can only upload files and another where they can only download files. This would not be possible with the MODX file browser.

Configuring TinyMCE

NewsPublisher 3.0 loads TinyMCE 4 directly from tinymce.com.

There are three properties that affect TinyMCE in the NewsPublisher snippet properties: tinyheight, tinywidth, and tinysource. Their descriptions explain what each one does. You don't need to set these properties unless you want to change the defaults. You can change the &tinysource property to load TinyMCE 4 from another location.

There is also a System Setting for the TinyMCE skin: np_tinymce_skin. The setting is in the newspublisher namespace on the System Settings grid. The built-in themes are listed in the description, but you're welcome to add additional themes. They go in the assets/components/newspublisher/tinymceskins directory.

For more fine-grained control of TinyMCE, you can edit the npTinyMCEInitTpl chunk, which contains initialization code for TinyMCE. If you want to do this, be sure to duplicate the chunk, then specify the duplicate's name in the &tinymceinittpl property of the NewsPublisher snippet. You may want to modify the plugins and toolbar sections to customize TinyMCE.

There is also some TinyMCE initialization code your can modify in the npRichTextTpl chunk. Changes there will only affect Richtext TVs. If you make changes in the npTinyMCEInitTpl, you may (or may not) want to modify the npRichTextTpl chunk to match.


NewsPublisher Settings and Properties

The following four tables include all of the properties and System Settings for NewsPublisher and its various components.

NewsPublisher System Settings

To edit these settings, go to System (gear icon) -> System Settings and select newspublisher in the "Namespace" input field.

SettingDescriptionDefault
NewsPublisher
np_login_redirect If set to Yes, not-logged-in users will be directed to the login page; use &loginResourceId=`##` (where ## is the ID of the NewsPublisher page) in the login tag to bounce users back to newspublisher after login 1
np_login_id ID of login page; used to redirect not-logged-in users
TinyMCE
np_tinymce_skin Skin directory for TinyMCE skin in assets/components/newspublisher/tinymceskins; built-in options: modxPericles, fairOphelia, fallenMacbeth, light modxPericles
elFinder
np_elfinder_tmb_size Thumb size for elFinder in NewsPublisher (in pixels) 48
np_elfinder_remember_last_dir Make elFinder remember last directory browsed (must be the string true or false) false
np_elfinder_theme Theme for elFinder to use in NewsPublisher; built-in themes include: osx, windows-10, moono, material osx
np_elfinder_height Height of elFinder window as percent of screen size 80
np_elfinder_width Width of elFinder window as percent of screen size 80
np_media_source_var Name for Media Source $_GET variable sent from NewsPublisher to the file browser media_source

NewsPublisher Snippet Properties

PropertyDescriptionDefault
NewsPublisher Control Settings
activetab (optional) Tab to show when form is loaded (empty)
allowedtags (optional) Tags allowed in text fields <p>,<br>,<a>,<i>,<em>,<b>,<strong>,<pre>,<table>,<th>,<td>,<tr>,<img>,<span>,<div>,<h1>,<h2>,<h3>,<h4>,<h5>,<font>,<ul>,<ol>,<li>,<dl>,<dt>,<dd>,<object>,<blockquote>,<code>,
badwords (optional) Comma delimited list of words not allowed in document (empty)
cancelid (optional) Document ID to load on cancel http_referer
captions (optional) Custom captions -- Comma-separated list of FieldNames:FieldCaptions. Example: &captions=`introtext:Summary,content:Enter Your Post` (empty)
clearcache (optional) When set to Yes, NewsPublisher will clear the site cache after saving the resource 1
contentcols (optional) Columns to show in Content field 60
contentrows (optional) Rows to show in Content field 10
cssfile (optional) Name of CSS file to use, or `` for no CSS file; File should be in assets/newspublisher/css/ directory newspublisher.css
groups (optional) Comma-separated list of resource groups to put new document in (no effect with existing docs); set to `parent` to use parent's groups (empty)
hoverhelp (optional) Show help when hovering over field caption 1
initdatepicker (optional) Initialize date picker; set this if there are any date fields 1
initfilebrowser Initialize file browser for use in RTE and file/image TVs 0
initrte (optional) Initialize rich text editor; set this if there are any rich text fields 0
intmaxlength (optional) Max length for integer input fields 10
language (optional) Language to use in forms and error messages (empty)
listboxmax (optional) Maximum length for listboxes 8
multiplelistboxmax (optional) Maximum length for multi-select listboxes 20
parents Comma-separated list of parent IDs for user to select from (must be IDs or Context keys); If &parentid is sent, it will be selected in the list. Note: new_document_in_root permission may be necessary for new resources) (empty)
postid (optional) Document ID to load on success the page created or edited
prefix (optional) Prefix to use for placeholders np
readonly (optional) Comma-separated list of fields that should be read only; does not work with option or textarea fields (empty)
required (optional) Comma separated list of fields/tvs to require pagetitle,content
rtcontent (optional) Use rich text for the content form field 0
rtsummary (optional) Use rich text for the summary (introtext) form field 0
show (optional) Comma separated list of fields/tvs to show pagetitle,longtitle,hidemenu,published,description,menutitle,pub_date,unpub_date,introtext,content
stopOnBadTv (optional) If set to No, &show can contain TVs not attached to the current template without an error 1
stopOnNoRte (optional) If set to No, &show can contain richtext fields without an error when initrte is off 1
summarycols (optional) Number of columns for the summary field 60
summaryrows (optional) Number of rows for the summary field 10
tabs (required only if usetabs is set) Specification for tabs (see tutorial) (empty)
templates (optional) Comma-separated list of template IDs for user to select from (must be IDs); if &template is set, it will be selected in the list (empty)
textmaxlength (optional) Max length for text input fields 60
tinyheight (optional) Height of richtext areas 400px
tinysource Source to load TinyMCE from //cdn.tinymce.com/4/tinymce.min.js
tinywidth (optional) Width of richtext areas 95%
usetabs (optional) Show tabbed display 0
which_editor Rich-text editor to use; at present, TinyMCE is the only value that will work TinyMCE
Resource Field Settings
aliasdateformat (optional) Format string for auto date alias -- see tutorial PHP date + time format
aliasprefix (optional) Prefix to be prepended to alias for new documents with an empty alias; alias will be aliasprefix - timestamp (empty)
aliastitle (optional) Set to Yes to use lowercase, hyphenated, page title as alias. If set to No, 'article-(date created)' is used. Ignored if alias is filled in form 1
cacheable (optional) Sets the flag that determines whether or not the resource is cached; for new resources, set to `Parent` to use parent's setting System Default
classkey (optional) Class key for new resources; use only if you have subclassed resource or are using this for Articles (set to Article) modDocument
hidemenu (optional) Sets the flag that determines whether or not the new page shows in the menu; for new resources, set to `Parent to use parent's setting System Default
parentid (optional) Folder ID where new documents are stored NewsPublisher folder; to force a parent, set this and do not show the parent field
presets Preset values for new document fields in this form: `content:Some default content,introtext introtext`
published (optional) Set new resource as published or not (will be overridden by publish and unpublish dates). Set to `parent` to match parent's pub status System Default
richtext (optional) Sets the flag that determines whether or Rich Text Editor is used to when editing the page content in the Manager; for new resources, set to `Parent` to use parent's setting System Default
searchable (optional) Sets the flag that determines whether or not the new page is included in site searches; for new resources, set to `Parent` to use parent's setting System Default
template (optional) Name or ID of template to use for new document; for new resources, set to `Parent` to use parent's template; for `parent`, &parentid must be set the default_template System Setting
Tpls
booltpl (optional) Tpl used for Yes/No resource fields (e.g., published, searchable, etc.) npBoolTpl
datetpl (optional) Tpl used for date resource fields and date TVs npDateTpl
elfinderinittpl (optional) Tpl used to initialize elFinder
errortpl (optional) Name of Tpl chunk for formatting field errors. Must contain placeholder npErrorTpl
fielderrortpl (optional) Name of Tpl chunk for formatting field errors. Must contain placeholder npFieldErrorTpl
filetpl (optional) Tpl used for file TVs
imagetpl (optional) Tpl used for image TVs
inttpl (optional) Tpl used for integer resource fields npIntTpl
listoptiontpl (optional) Tpl used for each option of listbox TVs npListOptionTpl
optionoutertpl (optional) Tpl used for as a shell for checkbox, list, and radio option TVs npOptionOuterTpl
optiontpl (optional) Tpl used for each option of checkbox and radio option TVs npOptionTpl
outertpl (optional) Tpl used as a shell for the whole page npOuterTpl
richtexttpl (optional) Tpl used for richtext TVs
texttpl (optional) Tpl used for text resource fields npTextTpl
tinymceinittpl (optional) Tpl used to initialize TinyMCE

npElFinderConnector Snippet Properties

Property Description Default
browserBasePath Users can browse below this directory, but not above it. Must match browserBaseURL setting /home/softvill/public_html/bobsguides/assets
browserBaseURL Users can browse below this URL, but not above it. Must Match browserBasePath settings /assets
browserStartPath Set this to start the browser in a directory below the browserBasePath. Must Match browserStart URL browserBasePath
browserStartURL Set this to start browsing in a directory below browserBaseURL. Must match browserStartPath. Required only if browserStartPath is set
disableCommands Comma-separated list of commands to disable. To enable a command, delete it from the list.

archive, download, cut, copy, paste, duplicate, edit, open, mkdir, mkfile, netmount, netunmount, rm, rename, quicklook, upload, view
driver Driver type for file browser (for future use) LocalFileSystem
locale Locale setting. Will use MODX locale System Setting if empty
tmbPath Path to directory to store thumbnails on upload .tmb
uploadAllow Comma-separated list of mime types to allow image, text/plain
uploadAllowOverwrite Allow overwriting of existing files when uploading 1
uploadMaxSize Maximum upload file size. This size is per files. Can be set as number or string with unit 10M, 500K, 1G. Note you still have to configure PHP files upload limits 0 (use PHP max size)

NpEditThisButton Snippet Properties

PropertyDescriptionDefault
bottom (optional) - distance from bottom of window to place button. Can be in any legal CSS format 20%
debug (optional) - Displays the button on all pages with either the $buttonCaption, or a message explaining why it would not be shown 0
editHome (optional) If set to Yes, edit button may be shown on the Home page 0
language (optional) - Language to use for error messages (empty)
noShow Comma - separated list of IDs of documents on which the button should not be displayed IDs of Home page and NewsPublisher page
np_edit_id ID of page to edit (bottom and right properties are ignored -- button is displayed inline). You can use this in an edit button tag in your getResources Tpl chunk to have multiple buttons on a page: (empty)
np_id ID of NewsPublisher page (set automatically on first run); If you change the name of the NewsPublisher page, you have to set this manually (empty)
right (optional) - Distance from right of window to place button. Can be in any legal CSS format 20%
ownpagesonly (optional) - Show button only on pages the current user created (uses the resource's createdby field). 0

 

Troubleshooting

If you are using elFinder and have to scroll down to see browser window, check to make sure that you have <!DOCTYPE html> at the top of your template.

 

Bugs, Feature Requests, and Questions

Bugs and feature requests should be reported here: GitHub NewsPublisher Page.

Questions should be posted in the NewsPublisher topic at MODX Forums.

 

NewsPublisher 3.0 Upgrade Notes

NewsPublisher 3.0 has some great new features, but you'll have to do a little work to implement them. If you've changed any of the default Tpl chunks, (you'd never do that, right?) your changes may be lost unless you preserve them by renaming them *before* installing NewsPublisher 3.0.

New Features Overview

NewsPublisher no longer depends on extJS/modExt, access to the MODX Manager, or the MODX TinyMCE extra. You don't even have to have the TinyMCE extra installed to use NewsPublisher. NewsPublisher loads TinyMCE 4 directly from tinymce.com (or the location of your choice). The NewsPublisher package includes the elFinder file/image browser and loads JQuery and JQuery-UI from the Web.

NewsPublisher responds properly to the Media Sources of all file, image, and richtext TVs. Users will automatically be restricted to browsing in and below the root of the TV's Media Source. You can also disable the file browser altogether, or easily enable or disable specific commands within the file browser, such as upload, download, delete, and so on. Better yet, you can modify the TinyMCE initialization for Richtext TVs, so they will have their own version or TinyMCE in NewsPublisher.

The elFinder browser also provides image editing within NewsPublisher. You can crop, rotate, and resize images when you insert them without altering the original image.

New Tpl chunks for initializing TinyMCE and elFinder allow you to customize their operation by creating and specifying your own custom Tpl chunks, and you can set the directory for file browsing within richtext sections of any of your non-TV richtext sections.

There are also several changes to make NewsPublisher more secure.

Upgrade Checklist

Here are the main things you'll want to deal with after the upgrade. See the text below for details.

  • np_login_redirect and np_login_id System Settings (newspublisher namespace)
  • file_manager permission
  • &initfilebrowser property (NewsPublisher snippet)
  • &redirecttologin property (NewsPublisher snippet)
  • &loginResourceId property (Login snippet)
  • &contexts property (Login snippet)
  • npElfinderConnector snippet properties
  • Tpl Changes

Update: Login Redirect

NewsPublisher now checks for login status and redirects users to the Login page if they are not logged in. To configure this option, see the Login Redirect section above.

For improved security, you no longer need to log users in to the mgr context for NewsPublisher, so you should remove mgr from the &contexts property of the Login snippet tag and list only front-end contexts there.

Tpl Changes

If you have not changed the default Tpl chunks, and have not specified alternate chunks in the Tpl properties, you should be fine. If you have, these are the only Tpl chunks that have changed (as a result of integrating the elFinder file browser):

  • npFileTpl
  • npImageTpl
  • npTextTpl
  • npTextAreaTpl

If you have modified any of those default chunks, and need to keep the modifications, rename your chunks before installing NewsPublisher 3.0. Then, install NewsPublisher 3.0. Integrate the changes in NewsPublisher's new chunks into your renamed chunks. Then, specify the renamed chunks in the Tpl properties of the NewsPublisher snippet tag, or in a property set.

If you have duplicated the default chunks already and use properties to specify them, just install NewsPublisher 3.0 and integrate the features of its new Tpl chunks into your duplicates.

Update: File Browser Access, Customization, and Commands

NewsPublisher 3.0 uses the elFinder Browser.

To configure the file browser, see the Configuring elFinder section above.

Update: TinyMCE Configuration

NewsPublisher 3.0 loads TinyMCE 4 directly from tinymce.com

To configure TinyMCE, see the section above.

 

My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book is available from Amazon.

If you have the book and would like to download the code, you can find it here.

If you have the book and would like to see the updates and corrections page, you can find it here.

MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:

  • Installing MODX
  • How MODX Works
  • Working with MODX resources and Elements
  • Using Git with MODX
  • Using common MODX add-on components like SPForm, Login, getResources, and FormIt
  • MODX security Permissions
  • Customizing the MODX Manager
  • Using Form Customization
  • Creating Transport Packages
  • MODX and xPDO object methods
  • MODX System Events
  • Using PHP with MODX

Go here for more information about the book.

Thank you for visiting BobsGuides.com

  —  Bob Ray