HTML Logo by World Wide Web Consortium (www.w3.org). Click to learn more about our commitment to accessibility and standards.

Moving forward with Composr

ocPortal has been relaunched as Composr CMS, which is now in beta. ocPortal 9 will be superseded by Composr 10.

Head over to compo.sr for our new site, and to our migration roadmap. Existing ocPortal member accounts have been mirrored.


match-keys mystery

Login / Search

 [ Join | More ]
 Add topic 
Posted
Rating:
#102393 (In Topic #20067)
Avatar

Well-settled

nothing works for me!

Greetings!

For my site's requirements, I need to achieve finely-grained viewing access control for a good many content modules - most types of catalogue, for example, where I want non-members to be able to navigate through category levels without  displaying entries, which I generally reserve for the last descendant category-level of each tree or tree-branch. 

I've lately started experimenting with match-key page-restrictions, working from the rather scant, elementary-level information and examples provided in the tutorials. It's been difficult extending beyond that level and developing a solid theoretical grasp and command of how they work and need to be declared syntactically, not least for the lack of documentation fully listing recognized key  terms and exactly what entities/contexts they could be applied to, along with the various values legitimately appendable to each key term - and practical examples covering each, intelligible enough for the uninitiated to get started on their own. The impression I've been led to believe is that mastering match-keys is the province of the elite - not so much an inherently unfathomable art for the non-nerd, but simply an arcane one.

But my greatest impediment on this score has been that I've not yet been able to get any of my experiments or even the simplest spelled out example match-key -  _WILD:downloads:type=view - to work on my v9.0.9 site (and in fact my particular needs should be served by this elementary form for other content types). I've been testing all my attempts on a dummy "Member" usergroup user, which has no secondary usergroups and view access (read-only) permission for all category tree levels including the last-descendant, in which my small number of download entries are all contained. 

To date I've amassed too little experience to tell whether I've overlooked some basic prerequisite for such match-keys to work, or whether there's a bug implicated - and I'd really appreciate some help with troubleshooting here, if anyone might care to.

Thanks for reading!
Back to the top
 
Posted
Rating:
#102398
Avatar

Hi,

I'm going to answer this in two parts. Please excuse my initial non-answer, but I do carry on to go into substantial detail on your actual question :).

For my site's requirements, I need to achieve finely-grained viewing access control for a good many content modules

Are you sure you need to? Throughout the development of ocPortal, we have always seen users pushing the features at the edge of the product to implement what are seen as basic requirements for a vision. It's similar to the classic problem of motorway building in the UK - however many roads get built, they always end up clogged up. The reality is that too often the fact ocPortal has so many features/configurability (more than most other CMSs) works like a drug on users, deferring the realisation that any out-of-the-box product will have limits – often to the detriment, as we give a lot of rope to hang yourself with. See my most recent blog post:
http://ocportal.com/site/news/view/chris_grahams_blog/minimum-viable-products.htm
I stress that there are only three viable ways to launch a complex site:
  • Either have a budget comparable to other complex sites, and employ programmers
  • Be a programmer yourself
  • Simplify down to a minimum viable product that sits well within the features of the software used, and then consider expanding complexity only after launch

It is vital that any user of any CMS make this realisation as early as possible in their site to avoid getting into a hole, when focus should usually be on content.

Take a site such as techcrunch.com. It is a wildly successful site, but not much more than Wordpress. They could have come in wanting to create something like Digg (which was created with a huge amount of programming investment), but instead they focused on adding value only through the content they write. TechCrunch is a good example of a minimum viable product, while Digg is a good example of a custom vision implemented via a team of programmers and funded by professional investment. Both have their place. What you never see is complex/custom well-designed sites, made by non-programmers, without strong budgets – I'd challenge anyone to come up with a single example that didn't at least have an in-house IT team behind it. Software like ocPortal provides a base for something more sophisticated, or it provides a commodity system to lay other business value on top of (e.g. news site, social community, and so on - standard kinds of out-of-the-box site). The distinction with ocPortal is it lets you mix things up more than other software, but still definitely within limits.

I've lately started experimenting with match-key page-restrictions, working from the rather scant, elementary-level information and examples provided in the tutorials.

Match-keys are a very minor feature in ocPortal, designed for exceptional rare situations where you need to limit one screen or another. They aren't a major tool for defining or building sites, only a tweak/hack.

the various values legitimately appendable to each key term - and practical examples covering each

There is no standard for what can be used, because it maps directly onto what are actually used within URLs. However…

But my greatest impediment on this score has been that I've not yet been able to get any of my experiments or even the simplest spelled out example match-key -  _WILD:downloads:type=view

Now, this is my bad. I am guilty of accidentally misleading you on how they work via a typo in the example you saw. It should say _WILD:downloads:type=entry (i.e. entry not view). If you have short URLs disabled you will see the URL to view a download looks something like this:
http://baseurl/site/index.php?page=downloads&type=entry&id=test
The long form version of the page-link is site:downloads:type=entry:id=test (well actually site:downloads:type=entry:id=1 because it's ID#1, but using the generated URL moniker of test won't hurt much)
The short form page-link for this is site:downloads:entry:test, as you can strip out the standardised type= and id= if you follow the right parameter order. site:downloads:entry is not a page-link (there's nothing at http://baseurl/site/index.php?page=downloads&type=entry), but it can be used as a match key

Back to my original point though, I really feel I'm giving you more rope to hang yourself with here. If you only intend to define around 5 maximum, okay it's a nice little tool to give you a little extra control. If you're going to elaborately set up 50, you are going to give yourself an unscalable and unmaintainable headache that nobody will understand in 6 months time.

I have reviewed the page-link/entry-point/match-key documentation, and it was definitely messy. I repeat the point this is the very edge of what a non-programmer should ever be using, but if something is not as clear as it can be, definitely we should improve it. The relevant parts of the cleaned documentation are as follows…

Entry points / Page links

There is a simple standard in ocPortal for identifying a page accessed by URL, in a way that is not tied down to installation domain and directory, like a URL is. This standard is sometimes called an 'entry point' and sometimes called a 'page link'; generally, an 'entry point' is a predictable 'page link' that will work on any ocPortal installation with the same set/configuration of zones and pages. A 'page link' on the other hand, might depend on the actual content of the site.

Page links are commonly seen in their most simple form in the Comcode page editor. In this, a page is simply '<zone-name>:<page-name>'. This is the simplest case, as a Comcode page will never need any parameters (although they could take them, and use them if they contain blocks that do, to the parameter relates to ocPortal rather than the page itself). Note that the Welcome Zone is given with a blank, and hence just ':<page-name>' is written for a page in the Welcome Zone.

A more complex case is used in the menu editor, which has the ability to insert any ocPortal 'entry point' as an item on the menu. An example of an entry point is 'site:downloads:type=cat'. This points to the downloads module in the site zone, and specifies a 'type' parameter to be of value 'cat'; the URL will turn out to be like <base-url>/site/index.php?page=downloads&type=cat (or <base-url>/site/pg/downloads/cat if short-urls are enabled). Note that 'type' is a standard parameter name in ocPortal, used by almost all modules to segregate internal command (for instance, 'cat' in this case specifies category listing functionality, as opposed to viewing an actual download); the page-link syntax does not handle it any different, but the short-URL syntax does.

The most complex case is for a full blown 'page link' that could not be referred to as merely a standard 'entry point', because it depends on the state of content. An example of this might be 'site:downloads:type=cat:id=10', to view the download category of ID#10.

It is also worth understanding that page links have a long-form and a short form syntax. For simplicity I have used the long-form syntax above. The short form syntax allows you to remove type= and id=, so long as the parameters match the expected order. You can remove type= from the third component, and id= from the fourth component. So site:downloads:type=cat:id=10 will shorten to site:downloads:cat:10.

If you do not want to hard-code what zone to use, you may specify either '_SEARCH' or '_SELF' as the zone name in the page link. '_SEARCH' will cause ocPortal to dynamically find the module involved, whilst '_SELF' will use the same zone as the page link is dynamically being interpreted in (e.g. If if it used on a menu in the site zone, '_SELF' will be equivalent to 'site').

Entry points

Entry points are used in the site-tree tool in the menu editor.

Entry points are basically ocPortal links that are robust to changes in your website and are of the syntax, '<zone>:<page>[:<param>=<val>...]'. In other words, they all have at least a zone and a page, and may also specify additional parameters: for example, 'site:downloads:type=ad' is the entry point to add a download. If you do not want to hard-code what zone a page is in (perhaps because you might move it in the future), you may specify '_SEARCH' (do a search, which is slightly inefficient) or '_SELF' (the zone the menu is being displayed in).

Entry points are the subset of all "page links" that point to specific parts of the software, rather than some content that you have added.

Don't worry too much about entry point syntax as ocPortal will automatically convert any local URLs that you paste into the menu editor's URL field.

To copy an entry point to a branch in the menu editor you need to:
  • select the caption field of an item in the menu (this will cause an editing form to become available for that menu item)
  • click the entry point in the site-tree tool
You will then see the URL has been changed to the entry point you want. Do not be alarmed that this was placed in the 'URL' field, as the field also supports page links (of which entry points are a type of).

Match-keys

The menu system can use match-keys for matching against the URL the menu is being viewed from, to determine whether a branch will be shown. If the URL matches against one of the match-keys for a branch, then the branch will be shown, otherwise it won't. Note that if you leave the "Restrict link visibility" field blank, none of this checking happens, and the branch is shown.

Match-keys may also be used in other places in ocPortal, for other kinds of matching purposes.

Match-key s are usually written exactly like page links, but are instead used only for matching. They do not need to point to anything, unlike page links which are actually convertible into real URLs.

The only differences between a page link and a match-key are:
  • Match-keys may use '_WILD' as the zone or page in order to skip checking against zone/page
  • Related to the above, it makes no sense to use '_SEARCH' or '_SELF' as the zone/page in a match-key
  • While all specified components of a match-key enforce a match, the URL may also have additional parameters and the match-key does not need to state them – i.e. the match-key may specify a subset of the parameters of a URL, broadening the match

An example match-key list is '_WILD:cms_downloads:type=ad,_WILD:cms_galleries:type=ed'. This would match URLs that were generated from the following page links (whether these page links points themselves actually work is irrelevant):
  • cms:cms_downloads:type=ad
  • randomzone:cms_downloads:type=ad
  • :cms_downloads:type=ad:wide=1
  • cms:cms_galleries:type=ed
  • adminzone:cms_galleries:type=ed:keep_novalidate=1

It would not match URLs generated from the following page links:
  • site:cms_galleries:type=ad
  • randomzone:cms_example
  • :cms_downloads:type=ed:wide=1

In the menu editor, multiple match-keys may be entered in the "Restrict link visibility" field with commas to separate them.


Become a fan of ocPortal on Facebook or add me as a friend. Add me on on Twitter.
Was I helpful?
  • If not, please let us know how we can do better (please try and propose any bigger ideas in such a way that they are fundable and scalable).
  • If so, please let others know about ocPortal whenever you see the opportunity.
  • If my reply is too Vulcan or expressed too much in business-strategy terms, and not particularly personal, I apologise. As a company & project maintainer, time is very limited to me, so usually when I write a reply I try and make it generic advice to all readers. I'm also naturally a joined-up thinker, so I always express my thoughts in combined business and technical terms. I recognise not everyone likes that, don't let my Vulcan-thinking stop you enjoying ocPortal on fun personal projects.
  • If my response can inspire a community tutorial, that's a great way of giving back to the project as a user.
Back to the top
 
Posted
Rating:
#102435
Avatar

Well-settled

Sincerest thanks, Chris, for your thoroughly thoughtful and helpful reply!

First may I express my gratitude for your revisions to the documentation on page-links, entry-points and match-keys. Closely comparing them against the originals, the adjustments and additions you've made are few and small, but quite enough to enable me at last to clearly understand the relationship and distinctions between these concepts; they join the dots together in a way that the original didn't (for me), allowing me to fit the puzzle's pieces together and - helped by your typo's correction - start making actual headway with setting match-keys that achieve what I want and need. (Your changing the title of the "Match Key" field on individual menu editing pages to "Restrict link visibility" proved important, too - perhaps the former title applied in versions earlier than mine?)

Secondly, I'm equally grateful for your concern as to whether I really do need match-keys to achieve the vision and aims of my site, and as to the alternative possibility that I might be intoxicated by ocP's wealth of alluring out-of-the-box functionality "just there for the taking" instead of sticking to my original vision and seeking to create a minimal viable product that achieves it as simply as possible. In reply I can say with 100% certainty that, in my case, you may discard whatever suspicions you might have on that score - though they're more than justifiable when I contemplate the number of new users you will have had to reply to who've fallen prey to scope-drift bordering on gothic fantasy! I spotted and read your blog-post (along with others, including the vision behind ocP 10) about the concept of the minimal viable product about 2 weeks ago and I couldn't agree more with every point you made.

Concerning my vision, the site is essentially a knowledge-base and knowledge-sharing resource for pianists seeking to broaden and deepen their understanding of piano-playing skills. It's at once a vehicle for publishing the fruits of my 35+ years' academic research (monographs and written tutorials), for introducing pianists to the (by most of their kind unexplored) fields of inquiry that have fuelled my research, and for providing a hub from which subscribers can pursue their own online research and hopefully return to share their findings with other members. It's a place specifically designed to stimulate serious discourse and fruitful collaboration that will generate further original content and consequently increase the site's standing.

As I see it, the minimal viable product for this requires, simply, an area for containing the site's original, exclusive content and an online reference-library (mostly in HTML but some in searchable PDF format that could easily be converted to HTML in due course), a wiki, a forum (both of which incorporate my needed interfaces for user-input and for providing online help with using them) and a search engine capable of queries through all of these components' content. 

After 3 initial years trying on and off to build a Joomla site without programming skills - time mostly spent exploring countless promising-seeming third-party extensions that reflected their developers' visions but not mine, or which could have sufficed were it not for the renowned problems of achieving thorough bridging between them - in desperation I finally got round to re-investigating ocP and recognized at once its all-round sufficiency for developing a site having the cross-modular integration I need, a transparent and comprehensible infrastructure and ready tools provided for the kind of fine-tuning I might still need. In short, had Joomla sufficed I would never have had the occasion  - and immense pleasure - to be using ocP now. ocP's available, user-tweakable functionality extends well beyond my needs, and indeed a fair amount of what's in the box would have little or no useful role that I can imagine for my site's purposes. On the other hand, some of its ready-to-use-as-is functions, while falling outside my minimal-viable-product spec, offer what I know from experience to be highly valuable adjuncts for serving the site's aims - for example, private messaging, both forum-based and IM  (not general/public chat, however - I want my users present and active on-site, not tucked away depriving other members of their wisdom and me of my bandwidth!), the Author's system (though some day it'd be good to sound you out about its originally envisioned uses), the Collabzone (obviously, from my description) and Galleries (for containing video tutorials). But not much besides these.

There remains, though, one minimal-viable-product specification I have yet to mention. My potential custom is generally people with a background of involvement in piano-playing who are on the one hand intent on improving their understanding but, owing to the traditional norms and biases of the field, by and large somewhat wary of venturing into fields whose relevance they wouldn't suspect and might dismiss out of hand. In the interests of persuading non-paying visitors (my "Registered Guest" usergroup) to sign up as paying subscribers, I want them to be able to familiarize themselves as thoroughly as possible with the site and the content it's offering without giving them actual access to the latter - i.e. to window-shop. Currently my Joomla site serves the purpose of advertising the content offered in the ocP subscribers' site, and provides a sign-up interface, but doesn't give them a glimpse of the site itself. Gateway sites aren't liked either by hopeful surfers or by search engines, and I'm busy transferring my more basically pitched advertising to pages in the Welcome Zone - in preparation for dropping Joomla - where guests can read enough to make them consider registering and exploring the site's interior. Setting up the Welcome Zone presents no difficulties whatsoever software-wise (now I've got to grips with the Comcode issues you've helped me with), but my specifications for Registered Guests usergroup permissions extend marginally beyond the scope of its Permissions Tree editor options. Which is where match-keys become relevant to me - all of them of the same simple basic formulation and role. (The impression I got from your wise cautioning about creating 50 was out of concern that I'd be setting out to create 50 different elaborate formulations - God forbid, no way I'd understand them a week on, let alone in 6 months time!)

As I explained in my OP, the match-key need is important in relation only to entry-viewing screens at the last-descendant level of catalogue categories, since entries can't be view-access-barred via the Permissions editors without removing visibility of their containing category as well and displaying a misleading message. There are, I realize, workarounds or partial-workarounds, by far the simplest (and laziest) being just to change the wording in the NO_ENTRIES template to something like "To view the content below this category, please subscribe". That, however, still leaves the titles of container-categories  missing on their parent- category page. A possible workaround here would be to create dummy, Permissions-controlled,  last-descendant categories (accessible to Registered Guests only) bearing the same titles that Members see, but leading to an entry displaying a no-access message like that above. Given that there are going to be a considerable and likely increasing number of entry pages, that would be messy and laborious, and the option of creating redirects to a single common message page would result in just as many redirects as there would be if match-keys were used - but, unlike match-keys, without removing the need to create the dummy categories. So I would argue that the better, tidier, and less amateurish option would be to avoid that workaround and opt for match-keys that in principle are provided for meeting fine-tuned functionality requirements in this kind of context. Or, would it be better perhaps to enter into entry-viewing-screen templates some kind of {+START,IF{IS_IN_GROUP}} restrictor?

Even if that were the preferable solution over trying to use match-key page-restrictions, and I decide they have no useful role for my site after all, nevertheless I remain curious to explore them "off-site" as it were, and it would be of great help if there were a glossary - in the Code Book, say, of standard ocP parameters that can be used in match-keys and of values applicable to each; the significance of many values is not self-explanatory (e.g., misc) and the abbreviations used in some evidently commoner ones (cat, ed, ad) make it still more obscure what classes of object they refer to - is it actually necessary, for instance, to drop the final d from "ad", which spontaneously suggests "advertisement" to most people. Considered alongside the fully spelled values "entry" or "view", there seems to be some inconsistency of practice here - not at all like the uniformly applied standard of clarity adhered to in, for example, PHP files comments, truly a hallmark of ocP's excellence, educativeness, and overall philosophy! 

My curiosity regarding match-keys, however, is just the tip of the iceberg. ocP is an astonishing, fascinating work of art underpinned by a formidable rationality and a philosophical outlook that explicitly invites users to share, participate, explore, extend their active involvement with how things work, develop their understanding and web expertise... and leaves me hungry for all that and more besides. It's allowed me opportunities and freedom to hugely extend my know-how and level of achievement in basic areas like CSS and (X)HTML, and now Tempcode has become my next must-have. Quite apart from owning - now in very nearly every respect - a website that actually works in support of my past and future life's work instead of hindering it, I've now evidently acquired a new leisure pursuit - or could it be an addiction?
 
If you've made it to the end of this post (more a blog post than a forum one, I think),
thanks - on top of those for your help - for reading!

Best regards,

Richard
Back to the top
 
Posted
Rating:
#102436
Avatar

(Y)

I did skim read a bit to be honest so forgive me if I missed something :lol:.
Regarding discussion of improving URLs, I am collecting them in here:
0001365: Neaten up default URLs, remove 'misc' - ocPortal feature tracker
I hope to get this stuff processed as a part of v10, as it is the kind of classic cleanup material we're dealing with in this update.

it would be of great help … standard ocP parameters that can be used in match-keys and of values applicable to each

I added "Also create a keep_no_short_url parameter, for temporarily disabling short URLs when deciding on match-keys." to the tracker issue. That helps you see more clearly what they are if the short URL feature is obscuring what parameters are really there.

the significance of many values is not self-explanatory (e.g., misc)

Yeah, I'm not happy about 'misc', but it is a tricky situation. On one hand, I want to keep the neat zone/page/type/id hierarchy, and I want a default type (misc), but on the other hand it isn't very intuitive. So in the tracker issue I discuss trying to remove the default from visibility within URLs, or make it something clearer on a case-by-case basis (e.g. category). The big Sitemap rearchitecting we've done should help, as ocPortal is now better at self-declaring what URL structure there is within the system, so that things like the entry point tool in the menu editor get accurate and tidy entry points to insert.

the abbreviations used in some evidently commoner ones (cat, ed, ad) make it still more obscure what classes of object they refer to - is it actually necessary, for instance, to drop the final d from "ad", which spontaneously suggests "advertisement" to most people.

Yeah, I agree it's a bit confusing.
Truth be told, 'ad' actually stood for 'add download', which was the first full CMS module we implemented. It was retroactively changed to be an abbreviation for 'add' because we didn't want to break compatibility or cause inconsistencies when adding new CMS modules.
I have noted about it in the tracker issue.


Become a fan of ocPortal on Facebook or add me as a friend. Add me on on Twitter.
Was I helpful?
  • If not, please let us know how we can do better (please try and propose any bigger ideas in such a way that they are fundable and scalable).
  • If so, please let others know about ocPortal whenever you see the opportunity.
  • If my reply is too Vulcan or expressed too much in business-strategy terms, and not particularly personal, I apologise. As a company & project maintainer, time is very limited to me, so usually when I write a reply I try and make it generic advice to all readers. I'm also naturally a joined-up thinker, so I always express my thoughts in combined business and technical terms. I recognise not everyone likes that, don't let my Vulcan-thinking stop you enjoying ocPortal on fun personal projects.
  • If my response can inspire a community tutorial, that's a great way of giving back to the project as a user.
Back to the top
 
Posted
Rating:
#102437
Avatar

Well-settled

Hi Chris, 

Thank you once again! All of your points and proposed changes will, I'm certain, be of crucial help to everyone venturing into these areas towards gaining conceptual understanding and practical competence in them, and in all other areas deploying the same concepts, terminology and rationale. 

I just remembered what I forgot to include in my last message. Your blog-post on the minimal viable product principle - might I persuade you to consider raising its visibility level? In my own case, I stumbled upon it purely by chance in the course of needing to visit your profile for a wholly unrelated purpose (which, doubtless, you would've deduced soon after) Its points, argumentation and cautionary practical recommendations would be pertinent to no small number of people new to CMSs - and ocP especially - that offer so much to explore, get distracted by, and very possibly halted by when they need to be making progress towards their original objectives; and it'd be far more likely to achieve its purpose somewhere where it was more likely to be read! May I suggest the "Advice and Guidance" tutorials category? Or even more visibly, in the Adminzone newsblock?

Incidentally, returning to the subject of documentation - ocP documentation in general. It's a huge task to maintain, seemingly it's one that you alone take on, and I doubt that you get too many offers of assistance with it - not too many enjoy such work, after all. For me it's a driving passion - a central part of my chosen life for the past 40 years. My meagre technical knowledge about ocP obviously precludes me from composing any official documentation on it, but I do have good copy-editing and fair proof-reading skills, and if you should ever feel these would be of use to you, I'd be only too delighted to oblige. Just whisper me if and when.

Regards

Richard.
Back to the top
 
Posted
Rating:
#102438
Avatar

Hi,

Thanks for the offer there :).

In fact, we will be entirely overhauling our documentation with our v10 relaunch. This is one of a number of things being worked on in parallel.

Steven Jarvis has been writing a lot of documentation on the Arvixe blog – more practical tutorials, generally. This documentation will be merged with our current documentation, and also some of my blog posts will go into a 'bizdev' category, and also stuff from the community docs will get cleaned up. It will all be managed via Wiki+, which will also be integrated with git.

In simple terms, we're pulling everything together into a single system, with all the advantages of the individual things we have now.


Become a fan of ocPortal on Facebook or add me as a friend. Add me on on Twitter.
Was I helpful?
  • If not, please let us know how we can do better (please try and propose any bigger ideas in such a way that they are fundable and scalable).
  • If so, please let others know about ocPortal whenever you see the opportunity.
  • If my reply is too Vulcan or expressed too much in business-strategy terms, and not particularly personal, I apologise. As a company & project maintainer, time is very limited to me, so usually when I write a reply I try and make it generic advice to all readers. I'm also naturally a joined-up thinker, so I always express my thoughts in combined business and technical terms. I recognise not everyone likes that, don't let my Vulcan-thinking stop you enjoying ocPortal on fun personal projects.
  • If my response can inspire a community tutorial, that's a great way of giving back to the project as a user.
Back to the top
 
1 guests and 0 members have just viewed this: None
Control functions:

Quick reply   Contract

Your name:
Your message: