NewsPublisher Snippet Tutorial

This snippet is for use with MODX Revolution. NewsPublisher is a front-end resource creation and editing tool. 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).

Note: Earlier versions of TinyMCE do not work correctly in the front end. Be sure you're using the current version.

Important Security Note

If you show a file or image TV on your NewsPublisher form, your user will need to have Manager access in order to use the File/Image browser. If the user manually types in a Manager URL, he or she can access any part of the Manager. If you are going to include file or image TVs in your NewsPublisher form, it is *very* important that the user have a Context Access ACL entry for the mgr context that severely limits what the user can do in the Manager. Do not use the Administrator Policy for this ACL entry!!! If you do, the user can potentially do anything you can do in the Manager (including deleting you and becoming the admin Super User). In order for the Image or File TVs to work in NewsPublisher, the Login snippet must contain the following property setting:

    &contexts=`web,mgr`

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 (AKA Web Transport Facility). Put NewsPublisher in the search box and press Enter. Click on the "Download" button, and when it changes to "Downloaded," click on the "Finish" button. That should bring you back to your Package Management grid. Click on the "Install" button next to NewsPublisher in the grid. The NewsPublisher snippet should now be installed.

If NewsPublisher doesn't show up using the process above, here's another way to get it.

• Go to the GitHub NewsPublisher Page
• Click on the "Downloads" button
• Download the latest version to your MODX core/packages directory
• Go to Package Manager
• Click on "Add Package", then "Search Locally for Packages."
• Install from the Package Manager Grid

In order to 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.

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. The properties can be in any order. Here's an example:

    [[!NewsPublisher?
        &show=`pagetitle,description,pub_date,summary,TV1,TV2`
        &initrte=`1`
        &initdatepicker=`1`
        &rtcontent=`1`
        &rtsummary=`1`
        &parentid=`12`
        &published=`1`
        &captions=`content: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 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 allow_modx_tags permission. As of NewsPublisher 1.3.0, this permission is included in the NewsPublisherEditor Policy but is unchecked by default. You must check the Permission and save the NewsPublisherEditor Policy if you want to allow users to edit or create documents with MODX tags in them.

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.

NewsPublisher Editor Policy

As of NewsPublisher 1.3.0, the package includes an Access Policy called "NewsPublisherEditor". This Policy enables the basic permissions necessary to operate NewsPublisher in the front end without giving the user any dangerous permissions. Create a Context Access ACL policy for the web context for any users who will be using NewsPublisher. As always, flush permissions and sessions on the Security menu after making any changes.

The NewsPublisherEditor Policy is based on the NewsPublisherPolicyTemplate, which in turn is based on the Administratror 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.

To use File and Image TVs in your form, or the file/image browser in the rich text editor you must perform two more steps, because the file and image browsers require Manager access. First, include &contexts=`web,mgr` in the Login snippet tag or the user will have to login a second time when trying to use the File or Image browser. Second, create a second Context Access ACL entry (just like the one above) for any groups who will use the form, with a context of 'mgr'. These steps are only necessary if you show File and/or Image TVs in the form or if your users will be using the rich text editor to insert images or upload files. One word of warning: The users will then be able to access a very minimal version of the Manager if they can figure out how, but they will only be able to do four things:

• View the TVs attached to the default template (and their default values)
• View the schedule of upcoming documents to be published (if any)
• Edit their own profile
• Follow the links on the "Support" menu

They will not be able to create documents in the Manager, or change anything at all (unless you've given them the permissions necessary to do so) other than their own profiles.

Editing Existing Resources

To edit existing resources, simply place a tag for the NpEditThisButton snippet anywhere in the <body> section of your template(s). 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.

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.

Altering the Form

You can make many changes to the look of the form using CSS rules for styling. You can find the CSS form 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 and put the path to 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, 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.

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. 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 &aliasdatesuffix 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.

&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; default to NewsPublisher page. (must be set if any other property is set to `Parent`.

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
&hidemenu
&cacheable
&searchable
&richtext

Less Common Properties

&template — (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.

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

&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 to Manager language.

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 and 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>

Bugs, Feature Requests, and Questions

Bugs and feature requests should be reported here: GitHub NewsPublisher Page (on the "issues" tab).

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