Bob's Guides

NewsPublisher Snippet Tutorial

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-premium extras with a clear conscience.

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 without needing access to the MODX Manager. 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).

Fully Updated for MODX 3

Version 3.1.5 Notes

NewsPublisher now creates the NewsPublisher page and the Login page on any new install if there are not already pages with the aliases login and NewsPublisher. If you have changed the aliases of those pages, you may get a second NewsPublisher page or a second Login page. This should only apply to new installs, so it's unlikely to affect the NewsPublisher page, but you might end up with a second login page. The best solution is to change the alias back to 'login' before installing NewsPublisher.

If you forget to do that, Change the np_id property of the NpEditThisButton snippet to the ID of your original Login page.

Another nice update is the opportunity to customize the NewPublisher page with MODX chunks. Just add as many the chunk names in the &show property of the NewsPublisher snippet like this:

    &show=`pagetitle,longtitle,someChunk,content,SomeOtherChunk`

The show properties are displayed in the order they appear in the &show property, If anything in the list is not a resource field or TV, NewsPublisher will inject the chunk content at that point. Obviously, the chunk names shouldn't match any resource fields or TVs.

Another change is that the permissions in your NewsPublisherEditor policy won't be overwritten when you upgrade NewsPublisher.

(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.

Lucy Iannotti's suggested improvements to this page were invaluable.

Thanks to todd.b for help testing the use of &ownpagesonly on aggregating pages.

Installing NewsPublisher for MODX Revolution

If you haven't installed the Login package, do that before installing NewsPublisher.

To install NewsPublisher, go to Extras | Installer 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

View the NewPublisher Resource. You should see a basic resource editing form. If you fill it in and click on the "Submit" button, the resource should be created (it will be under the NewsPublisher resource, though you can change that).

The example 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 &show property. You can also 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 the content and summary 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 as shown in the example above. The part before the : is the field name, the part after it is the caption that will be shown. The fields are separated by commas. 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. Important: this feature won't work if the NewsPublisher page is protected by a Resource Group Access ACL entry. That ACL entry hides the page so the NewsPublisher snippet never executes. The user will be sent to the error (page not found) page instead.

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. If 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.

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 login snippet's &loginResourceId property to the ID of the NewsPublisher page.

If you use the Login page only for NewsPublisher, and you have only one NewsPublisher page, you can use the following property in the Login tag to redirect users back the NewsPublisher page (where ## is the ID of the NewsPublisher page):

    &loginResourceId=`##`

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 <body></body> 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.

Notify requires the installation of the Subscribe extra, so be sure that it's installed if you want to use Notify.

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.

As of version 3.1.0 you can combine the technique above with &ownpagesonly by adding this property to the NpEditThisButton tag example above:

    [[!NpEditThisButton? &np_edit_id=`[[+id]]` &createdby=`[[+createdby]]` ]]

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. It contains a long list of commands that are disabled in the file browser. The ability to upload files, for example, is disabled by default and the upload button won't appear in the file browsers. To let users upload files, remove ,upload from the &disableCommand property. See the description of the property for a list of possible commands. To allow users to access a specific feature, simply remove it from the list. The elFinder browser will automatically show icons for any commands that are *not* 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.

NewsPublisher Snippet Properties

npElFinderConnector Snippet Properties

NpEditThisButton Snippet Properties

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.

If the NpEditThisButton doesn't work, be sure the NpEditThisButton property np_id is set to the ID of the page with the NewsPublisher snippet tag.

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.

Copyright © 2011-2025
Bob Ray